跳转到内容
搜索文档

兼容日期

最后更新 查看 MarkdownAgent 设置

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 字段,出于以下两个原因,定期更新仍是良好实践:

  1. 有时,新功能只能提供给具有当前 compatibility_date 的 Worker。要访问最新功能,您需要保持最新。
  2. 通常,除兼容性标志页面外,Workers 文档可能仅描述当前的 compatibility_date,省略有关历史行为的信息。如果您的 Worker 使用旧的 compatibility_date,您需要持续参考兼容性标志页面,以检查您使用的任何 API 是否已更改。

通过 Wrangler

兼容日期可以在 Worker 的 Wrangler 配置文件 中设置。

{
	// Opt into backwards-incompatible changes through April 5, 2022.
	"compatibility_date": "2022-04-05"
}
compatibility_date = "2022-04-05"

通过 Cloudflare 仪表板

通过 Cloudflare 仪表板创建 Worker 时,兼容日期会自动设置为当前日期。

兼容日期可以在 Cloudflare 仪表板 的 Workers 设置中更新。

通过 Cloudflare API

上传 Worker 时,可以在请求体的 metadata 字段中使用 Workers Script APIWorkers Versions API 设置兼容日期。

如果通过 API 上传时未指定兼容日期,则默认为最早的兼容日期,即任何标志生效之前(2021-11-02)。创建新 Worker 时,强烈建议通过 API 上传时将兼容日期设置为当前日期。

这篇文档对您有帮助吗?