配置

Previews 不会继承生产设置。在配置文件的 previews 块中定义它们。有关绑定如何共享或隔离数据和状态，请参阅资源和隔离。

在团队分支来源的分支（例如 main）上定义起始 previews 块。Git 会将配置文件带入每个新分支。

当某个分支的 Preview 需要不同设置时，在该分支上更改 previews 块。运行 npx wrangler preview 时，Wrangler 将当前分支的配置文件作为真实来源。有关设置说明，请参阅快速入门。

密钥不能存储在 Wrangler 配置文件中。为了保留分支模型，而无需手动为每个 Preview 应用相同密钥，请在 Previews Base 配置中一次性设置共享密钥。每个新 Preview 创建时都会收到这些密钥。需要时为单个 Preview 设置不同的值。之后对 Base 密钥的更改仅应用于新 Preview，因此活动 Preview 保持不变。

如果省略 --name 标志，则默认为当前 git 分支。

Wrangler 文件在顶层包含生产设置，在 previews 块中包含 Preview 设置。previews 块是必需的，但如果 Preview 不需要单独设置，它可以是空的。将 Preview 绑定指向预发布或测试资源，而不是生产资源。

{
  // ...
  "vars": {
    "ENVIRONMENT": "production"
  },
  "r2_buckets": [
    {
      "binding": "UPLOADS",
      "bucket_name": "prod-uploads"
    }
  ],
  // ...
  "previews": {
    // ...
    "vars": {
      "ENVIRONMENT": "preview"
    },
    "r2_buckets": [
      {
        "binding": "UPLOADS",
        "bucket_name": "r2-staging"
      }
    ]
    // ...
  }
}

[vars]
ENVIRONMENT = "production"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "prod-uploads"

[previews.vars]
ENVIRONMENT = "preview"

[[previews.r2_buckets]]
binding = "UPLOADS"
bucket_name = "r2-staging"

如果 npx wrangler preview 创建了 Preview URL 但警告缺少绑定，则 URL 已上线但运行时配置不完整。将缺少的绑定复制到 previews 块中，使用对 Preview 安全的值和测试资源。有关资源共享行为，请参阅资源和隔离。

使用此表确定每项设置的位置。

如果 Worker 仅使用顶层设置，请包含一个空的 previews 块：

{
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "assets": {
    "directory": "./public"
  },
  "previews": {}
}

# Set this to today's date
compatibility_date = "2026-11-14"
previews = { }

[assets]
directory = "./public"

不要将 Queue consumers、Cron Triggers 或生产路由添加到 previews。这些不会以 Previews 为目标。有关 Preview 主机名，请参阅自定义域名。

来自 Preview 的 Service bindings 会调用绑定 Worker 的生产部署。更多限制请参阅限制。

你可以在仪表板中配置 Previews Base 设置，但必须将生成的配置复制到 Wrangler 文件中。为避免这一额外步骤，请直接在 Wrangler 文件中配置 Preview 设置。