配置项

wrangler.jsonc 支持注释，所以可以放心写说明。所有字段都可以放在 .toml 里（老项目常见），但新项目一律用 JSONC。

`name`

Worker 的唯一标识，也是默认域名 https://<name>.<子域>.workers.dev 的那一段。同一个账号下不能重名。

{ "name": "my-worker" }

`compatibility_date`

必填。决定平台用哪一套行为跑你的代码，见术语表。

{ "compatibility_date": "2026-09-21" }

`compatibility_flags`

按字符串数组开关具体的运行时能力。

{ "compatibility_flags": ["nodejs_compat"] }

nodejs_compat：让依赖 Node API 的包能用。不开的话 import { Buffer } from 'node:buffer' 之类直接解析失败
global_fetch_strictly_public：Worker 内部发出的 fetch 走公网而不是内部捷径，调试出站行为时有用

`main`

入口文件。纯静态托管不需要它，一旦写了就变成“Worker + 资源”的混合模式。

{ "main": "src/index.ts" }

`assets` 实验性

把构建产物交给 Workers 托管。

{
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "not_found_handling": "404-page"
  }
}

directory：产物目录
binding：给代码里访问资源用的绑定名，不写则不注入
not_found_handling："single-page-application" / "404-page" / "none"。默认是 none，此时访问不存在的路径返回 404 状态码但响应体为空——想让 404.html 生效必须显式写 "404-page"
run_worker_first：默认 false，即命中静态文件就直接返回、不进 Worker。要做全站鉴权得设 true

`kv_namespaces` / `r2_buckets` / `d1_databases`

绑定声明，形状一致：一个代码里用的 binding 名，加一个资源标识。

{
  "kv_namespaces": [{ "binding": "MY_KV", "id": "..." }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "..." }],
  "d1_databases": [{ "binding": "DB", "database_name": "...", "database_id": "..." }]
}

id 缺失时 wrangler deploy 会提示创建资源（自动开通）。把创建出来的 id 写回配置并提交，CI 里就不会再走这条路径。

`routes`

自定义域名和路径匹配。

{
  "routes": [
    { "pattern": "api.example.com/*", "zone_name": "example.com" },
    { "pattern": "example.com/blog/*", "zone_name": "example.com" }
  ]
}

`triggers.crons`

{ "triggers": { "crons": ["0 */6 * * *"] } }

UTC 时间，代码里要实现 scheduled handler。

`observability`

{ "observability": { "enabled": true } }

开了才能在控制台和 wrangler tail 里看到调用日志与指标。生产项目没有理由关着。

`vars`

非敏感的键值对，明文存在配置里。

{ "vars": { "API_BASE": "https://api.example.com" } }

任何看起来像密钥的东西都不该出现在这里，用 wrangler secret put。

配置项

name

compatibility_date

compatibility_flags

main

assets 实验性

kv_namespaces / r2_buckets / d1_databases

routes

triggers.crons

observability

vars