预览 URL

预览 URL 允许你在不部署到生产环境的情况下预览 Worker 的新版本。

预览 URL 有两种类型：

• 版本化预览 URL：为 Worker 的每个新版本自动生成的唯一 URL。
• 别名预览 URL：可手动分配给 Worker 版本的静态、可读别名。

两种预览 URL 均遵循以下格式：<VERSION_PREFIX OR ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev。

预览 URL 可用于：

• 集成到 CI/CD 流水线中，为每个拉取请求自动生成预览环境。
• 团队协作，在实时环境中测试代码变更并验证更新。
• 测试新 API 端点、验证数据格式，并确保与现有服务的向后兼容性。

在测试某个版本的 zone 级性能或安全功能时，我们建议使用版本覆盖（version overrides），以便应用 zone 的性能和安全设置。

每次创建 Worker 的新版本时，都会自动生成一个唯一的静态版本预览 URL。这些 URL 使用版本前缀，格式为 <VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev。

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

• wrangler deploy
• wrangler versions upload
• 或通过 Cloudflare 仪表板进行编辑

如果已启用预览 URL，它们在版本创建后即可公开访问。

wrangler versions upload 命令会上传 Worker 的新版本，并为每个上传的版本返回预览 URL。

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

   Go to Workers & Pages ↗

2. 选择你的 Worker。

3. 前往 Deployments（部署） 选项卡，找到要查看的版本。

别名预览 URL 允许你为特定 Worker 版本分配一个持久、可读的别名。这对于在多个版本之间链接到稳定的预览很有用（例如，分享一个即将推出但仍在积极开发的新功能）。常见的工作流程是为你正在开发的分支分配一个别名。此类预览 URL 与其他预览 URL 遵循相同的模式： <ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev

别名可在 versions upload 期间创建，通过 --preview-alias 标志提供有效的别名名称：

wrangler versions upload --preview-alias staging

生成的别名将与此版本关联，并立即可在以下地址访问： staging-<WORKER_NAME>.<SUBDOMAIN>.workers.dev

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

启用后，所有预览 URL 均可公开访问。你可以使用 Cloudflare Access 要求访问者在访问预览 URL 之前进行身份验证。你可以将访问限制为自己、队友、组织或你在访问策略中指定的任何其他人。

要将预览 URL 限制为仅授权邮箱访问：

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

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择你的 Worker。

3. 前往 Settings（设置） > Domains & Routes（域名和路由）。

4. 对于 Preview URLs，点击 Enable Cloudflare Access（启用 Cloudflare Access）。

5. 可选：要配置 Access 应用程序，点击 Manage Cloudflare Access（管理 Cloudflare Access）。在那里，你可以更改要授权的邮箱地址。查看 Access 策略 了解如何配置其他规则。

6. 在 Worker 脚本中使用提供的受众（aud）标签和 JWKs URL 验证 Access JWT。

注意：

• 启用 workers_dev 时，预览 URL 默认启用。
• 禁用 workers_dev 时，预览 URL 默认禁用。
• 禁用预览 URL 将同时禁用版本化和别名预览 URL 的路由。

要切换 Worker 的预览 URL：

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

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择你的 Worker。

3. 前往 Settings（设置） > Domains & Routes（域和路由）。

4. 对于 Preview URLs，点击 Enable（启用） 或 Disable（禁用）。

5. 确认操作。

要切换 Worker 的预览 URL，在 Worker 的 Wrangler 文件中包含以下任一配置：

{
	"preview_urls": true
}

preview_urls = true

{
	"preview_urls": false
}

preview_urls = false

如果未指定，默认值为 preview_urls = workers_dev。

• 实现了 Durable Object 的 Worker 不会生成预览 URL。
• 目前不会为 Workers for Platforms 用户 Worker 生成预览 URL。这是临时限制，我们正在努力移除。
• 目前无法配置预览 URL 在 workers.dev 以外的子域上运行。
• 目前无法查看预览 URL 的日志，包括 Workers Logs、Wrangler tail 和 Logpush。