Version URL

Version URL（以前称为 preview URL）让你可以在将 Worker 部署到生产环境之前访问已上传的版本。Version URL 使用该 Worker 版本的现有配置和资源，而不是创建单独的环境。

这对于直接测试特定版本很有用。若要在测试该版本时应用 zone 的性能或安全设置，请使用版本覆盖（version overrides）。

对于隔离的分支或拉取请求测试，请使用 Previews。要比较 Previews、Version URL 和 Wrangler 环境，请参阅比较工作流。

Version URL 使用以下格式：

<version-prefix>-<worker-name>.<subdomain>.workers.dev

别名 Version URL 使用以下格式：

<alias>-<worker-name>.<subdomain>.workers.dev

每次创建 Worker 的新版本时，Cloudflare 都可以为该版本生成唯一的 Version URL。

在以下情况下会创建新版本：

• wrangler deploy
• wrangler versions upload
• 仪表板代码编辑并保存新版本

如果已启用 Version URL，该 URL 在版本创建后即可公开访问。

wrangler versions upload 命令会上传 Worker 的新版本，并返回该版本的 Version URL。

npx wrangler versions upload

1. 在 Cloudflare 仪表板中，前往 Workers & Pages。

   前往 Workers & Pages ↗

2. 选择你的 Worker。

3. 前往 Deployments。

4. 找到要测试的版本。

别名 Version URL 允许你为特定 Worker 版本分配可读别名。当你希望为手动上传的版本提供稳定 URL 时，这很有用。

在版本上传期间使用 --preview-alias 创建别名：

npx wrangler versions upload --preview-alias staging

该别名指向该命令上传的版本：

staging-<worker-name>.<subdomain>.workers.dev

别名只能在版本上传期间创建。

启用后，Version URL 可公开访问。要要求访问者登录，请使用 Cloudflare Access。

Access 可以保护一个 Worker 或账户中每个 Worker 的 Version URL。你也可以同时保护生产和版本部署。

要在 Worker 中使用已登录用户的详细信息，请从已验证的 JSON Web Token (JWT) 或 /cdn-cgi/access/get-identity 端点读取用户身份。

当不存在 Version URL 设置时，Version URL 会遵循与 workers.dev 路由相同的默认值：

• 如果启用了 workers_dev，则默认启用 Version URL。
• 如果禁用了 workers_dev，则默认禁用 Version URL。
• 禁用 Version URL 会禁用到 Version URL 和别名 Version URL 的路由。

1. 在 Cloudflare 仪表板中，前往 Workers & Pages。
2. 选择你的 Worker。
3. 前往 Settings > Domains & Routes。
4. 找到 Version URLs。
5. 选择 Enable 或 Disable。

要启用 Version URL，请在 Wrangler 配置中添加 preview_urls：

{
  "preview_urls": true
}

preview_urls = true

要禁用 Version URL：

{
  "preview_urls": false
}

preview_urls = false

如果省略 preview_urls，Wrangler 不会更改现有的 Version URL 设置。要更改它，请显式设置 preview_urls。

• 别名只能在版本上传期间创建。
• 别名只能使用小写字母、数字和短横线。
• 别名必须以小写字母开头。
• 别名与 Worker 名称用短横线连接后不得超过 63 个字符，受 DNS 标签长度限制。
• 仅保留最近部署的 1000 个别名。当创建超出此限制的新别名时，最近部署时间最早的别名将被删除。

• 实现了 Durable Object 的 Worker（包括 Containers 和 Sandbox Worker）不会生成 Version URL。有关 Containers 测试选项，请参阅部署 Containers。
• 目前不会为 Workers for Platforms 用户 Worker 生成 Version URL。
• 无法将 Version URL 配置为在 workers.dev 以外的子域上运行。
• 无法通过 Workers Logs、Wrangler tail 或 Logpush 查看 Version URL 的日志。