编程 Wrangler v4 迁移：wrangler.jsonc、v3 起移除的命令与 node_compat 弃用处理

2026-09-22 00:03:44

Wrangler v4 迁移：wrangler.jsonc、v3 起移除的命令与 node_compat 弃用处理

项目地址：cloudflare/workers-sdk
官方文档：Wrangler 官方文档

配置文件格式

Wrangler 可选使用配置文件自定义 Worker 的开发与部署。

从 Wrangler v3.91.0 起，Wrangler 同时支持 JSON（wrangler.json 或 wrangler.jsonc）和 TOML（wrangler.toml）配置文件；在此之前只支持 wrangler.toml。Cloudflare 建议新项目使用 wrangler.jsonc，部分较新的 Wrangler 功能只对使用 JSON 配置的项目开放。两种格式的配置内容完全一致，只是语法不同。最佳实践是把 Wrangler 配置文件当作 Worker 配置的单一事实来源。

最小必填：name、main、compatibility_date 三个键是部署 Worker 的最低要求。main 对纯 assets 的 Worker 可省略。

name 只能包含字母数字和短横线 -，不能用下划线 _，最长 255 字符；若要用 workers.dev 子域，名字须 ≤63 字符且不能以短横线开头或结尾。

配置示例（JSON）：

{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
"main": "src/index.js",
"compatibility_date": "2026-09-21",
"workers_dev": false,
"route": { "pattern": "example.org/*", "zone_name": "example.org" },
"kv_namespaces": [ { "binding": "", "id": "" } ],
"env": {
"staging": {
"name": "my-worker-staging",
"route": { "pattern": "staging.example.org/*", "zone_name": "example.org" },
"kv_namespaces": [ { "binding": "", "id": "" } ]
}
}
}

环境

[env.] 定义命名环境，用 -e / --env 预览或部署，例如 npx wrangler deploy --env staging。

多数键可继承给环境；但 Bindings（如 vars、kv_namespaces）不可继承，必须在每个环境里显式定义。升级时会踩的坑：顶层写了 kv_namespaces 就以为 staging 会自动继承，部署后发现绑定缺失。判断依据：Bindings 不可继承。

少数键只能出现在顶层（不能在命名环境里定义）：

keep_vars（boolean，可选）：部署时是否保留在 dashboard 里配置的变量。
send_metrics（boolean，可选）：是否向 Cloudflare 发送使用数据，默认 true。
dependencies_instrumentation（object，可选）：部署/上传时收集 npm 依赖元数据（包名与版本），默认启用。
site（object，可选，已弃用）：见 Workers Sites，Cloudflare Pages / Workers Assets 更被推荐。Vite 插件不支持。

如果使用 Cloudflare Vite 插件，环境通过 CLOUDFLARE_ENV 环境变量选择，而不是 --env 标志。

自动创建资源（Beta）

在配置文件里加 binding 但不写资源 ID（R2 不写 bucket name），Wrangler 可以在部署时自动创建资源，资源名以 Worker 名为前缀。支持 KV、R2、D1、Flagship、AI Search、Agent Memory、Dispatch Namespaces、Queues。

运行 wrangler dev 时会自动创建本地资源，且在多次运行间持久保留。运行 wrangler deploy 时会为你创建资源，并把 ID 写回配置文件。

如果从 dashboard（例如通过 GitHub）部署一个带资源但没写资源 ID 的 Worker，资源会被创建，但 ID 只能在 dashboard 看到，目前不会写回你的仓库。踩坑：CI 或本地再拉代码时拿不到这个 ID，配置仍缺绑定。

wrangler dev --local 说明

wrangler dev 在 v3 起默认就是本地模式，由 Miniflare 驱动。

弃用与破坏性变更

Wrangler v4

Workers Sites：使用 Workers Sites 已弃用，建议迁移到 Workers Static Assets。未来版本会移除 Wrangler 对 Workers Sites 的支持。
Service environments：通过 legacy_env 属性启用的 Service Environments 已弃用，建议迁移到 Wrangler Environments，未来版本移除。

Wrangler v3 起已弃用的命令（v4 移除）

wrangler generate：弃用，v4 完全移除。新项目用 npm create cloudflare@latest。
wrangler publish：弃用，v4 完全移除。部署用 npx wrangler deploy。
wrangler pages publish：弃用，v4 完全移除。Pages 部署用 wrangler pages deploy。
version：改用 wrangler --version 查看当前版本。

Wrangler v3 起已弃用的选项

--experimental-local：v3 的 wrangler dev 默认本地，不再需要。
--local：同上，不再需要。
--persist：wrangler dev 默认自动持久化数据，不再需要。
wrangler pages dev 的 -- 、--proxy、--script-path：会妨碍准确模拟生产静态资源行为，已弃用。改为把静态资源构建到目录，再用 wrangler pages dev 。
--legacy-assets 与 legacy_assets 配置属性：建议迁移到 Workers assets。
--node-compat 与 node_compat 配置属性：改用 nodejs_compat 兼容性标志，它包含旧 node_compat polyfill 的功能以及原生实现的 Node.js API。
usage_model 配置属性：Workers Standard Pricing 全面铺开之后已无任何效果。

Wrangler v2 的常见弃用

wrangler.toml 不再是必需。
dev 和 publish 接受 CLI 参数；tail 可用于任意 Worker 名；init 创建项目模板；vars 支持 JSON 绑定；dev 有本地模式；模块系统；DevTools；TypeScript 支持；可在互联网共享开发环境。
type 不再必需（自动推断）；zone_id 不再必需（可从 routes 推断）；build.upload.format 不再使用。
build.upload.main / build.upload.dir 不再必需，用顶层 main。
site.entry-point 不再必需，用 main。
webpack_config 和 webpack 属性不再支持。
v1 命令已移除：wrangler preview（用 wrangler dev）、wrangler build（用 wrangler deploy --outdir=path/to/output）、wrangler route（在配置文件定义 routes）、wrangler config（用 wrangler login/logout 或 CLOUDFLARE_API_TOKEN 环境变量）、wrangler subdomain（在 dashboard 创建 workers.dev 子域）。

其它弃用行为

dashboard 定义的 routes 不会和 Wrangler 定义的 routes 并存；两者都定义时只有配置文件里的 route/routes 生效。若只想用 dashboard 管路由，要删掉 route/routes 并加 workers_dev = false。
Wrangler 不再把调用 wrangler dev 目录下的 index.js 当入口，用 main 或显式传参 wrangler dev index.js。
不再假定裸模块说明符是文件名：import SomeDependency from "some-dependency.js" 会打弃用警告，将来报错，应写 "./some-dependency.js"。

Secrets / 类型

secrets 配置属性声明 Worker 需要的 secret 名，用于本地开发与部署时校验，并作为类型生成的来源，required: string[] 列出部署必须设置的名字。