Cloudflare 会定期更新 Workers 运行时。这些更新会全局应用于所有 Workers,且不应导致已部署的 Worker 停止运行。但有时某些更改可能不向后兼容。特别是,运行时 API 中可能存在现有 Worker 无意中依赖的 bug。Cloudflare 会实现 bug 修复,新 Worker 可以选择启用,而已部署的 Worker 将继续看到 buggy 行为,以防止破坏已部署的 Worker。
兼容日期和标志是开发者选择加入这些运行时更改的方式。兼容性标志 通常会有一个默认启用的日期,因此通过为 Worker 指定 compatibility_date,您可以快速启用截至该日期(含)的所有各种兼容性标志。
启动项目时,应始终将 compatibility_date 设置为当前日期。您应偶尔更新 compatibility_date 字段。更新时,应参考兼容性标志页面了解变更内容,并仔细测试 Worker 以确认更改是否影响您,必要时更新代码。新的兼容日期在您下次运行 npx wrangler deploy 命令时生效。
如果您不想更新 compatibility_date,则无需更新。Workers 运行时将永久支持旧的兼容日期。如果 Cloudflare 出于某种原因必须进行会破坏线上 Worker 的更改,Cloudflare 将主动联系受影响的开发者。尽管如此,Cloudflare 会尽可能避免这种情况。
但是,即使您不需要更新 compatibility_date 字段,出于以下两个原因,定期更新仍是良好实践:
- 有时,新功能只能提供给具有当前
compatibility_date的 Worker。要访问最新功能,您需要保持最新。 - 通常,除兼容性标志页面外,Workers 文档可能仅描述当前的
compatibility_date,省略有关历史行为的信息。如果您的 Worker 使用旧的compatibility_date,您需要持续参考兼容性标志页面,以检查您使用的任何 API 是否已更改。
兼容日期可以在 Worker 的 Wrangler 配置文件 中设置。
{
// Opt into backwards-incompatible changes through April 5, 2022.
"compatibility_date": "2022-04-05"
}compatibility_date = "2022-04-05"通过 Cloudflare 仪表板创建 Worker 时,兼容日期会自动设置为当前日期。
兼容日期可以在 Cloudflare 仪表板 ↗ 的 Workers 设置中更新。
上传 Worker 时,可以在请求体的 metadata 字段中使用 Workers Script API 或 Workers Versions API 设置兼容日期。
如果通过 API 上传时未指定兼容日期,则默认为最早的兼容日期,即任何标志生效之前(2021-11-02)。创建新 Worker 时,强烈建议通过 API 上传时将兼容日期设置为当前日期。