已弃用

了解 Wrangler 各版本之间的差异，特别是已弃用项和破坏性变更。

Workers Sites 的使用已弃用。建议迁移到 Workers Static Assets。未来版本的 Wrangler 将移除对 Workers Sites 的支持。

通过 Wrangler 配置中的 legacy_env 属性启用的 Service Environments ↗ 已弃用。建议迁移到 Wrangler Environments。未来版本的 Wrangler 将移除对 Service Environments 的支持。

以下命令在 Wrangler v3 中已弃用。这些命令将在未来版本的 Wrangler 中完全移除。

wrangler generate 命令已弃用，但在 v3 中仍可用。wrangler generate 将在 v4 中完全移除。

对于新的 Workers 和 Pages 项目，请使用 npm create cloudflare@latest。

wrangler publish 命令已弃用，但在 v3 中仍可用。wrangler publish 将在 v4 中完全移除。

使用 npx wrangler deploy 部署 Workers。

wrangler pages publish 命令已弃用，但在 v3 中仍可用。wrangler pages publish 将在 v4 中完全移除。

使用 wrangler pages deploy 部署 Pages。

请改用 wrangler --version 检查当前 Wrangler 版本。

v3 中的 wrangler dev 默认在本地运行，因此不再需要此选项。

v3 中的 wrangler dev 默认在本地运行，因此不再需要此选项。

wrangler dev 默认自动持久化数据，因此不再需要此选项。

这些选项会阻止 wrangler pages dev 准确模拟生产环境中静态资源的提供行为，因此已弃用。与其依赖 Wrangler 代理到其他上游开发服务器，不如将静态资源构建到目录中，然后使用 wrangler pages dev <directory> 指向该目录，以模拟更准确的行为。

建议迁移到 Workers assets。

请改用 nodejs_compat 兼容性标志。它包含旧版 node_compat polyfill 的功能，以及原生实现的 Node.js API。

在 Workers Standard Pricing 全面推出 ↗ 后，此属性不再有任何效果。

Wrangler v2 为配置引入了新的字段，为 Worker 的开发和部署提供了新功能，同时弃用了一些冗余字段。

• 不再强制要求 wrangler.toml。
• dev 和 publish 接受 CLI 参数。
• tail 可在任意 Worker 名称上运行。
• init 创建项目样板。
• vars 的 JSON 绑定。
• wrangler dev 的本地模式。
• 模块系统（适用于 modules 和 service worker 格式的 Workers）。
• DevTools。
• TypeScript 支持。
• 在互联网上共享开发环境。
• 更广泛的平台兼容性。
• 开发者快捷键。
• 更好的配置验证。

以下视频介绍了 Wrangler v2 的一些主要变更，并展示了 Wrangler v2 如何帮助加快你的工作流程。

请参阅以下列表，了解不再需要的常见字段。

• 不再要求 type。Wrangler 会自动推断正确的项目类型。
• 不再要求 zone_id。可以直接从路由推断。
• 不再使用 build.upload.format。格式现在会从代码自动推断。
• 不再要求 build.upload.main 和 build.upload.dir。请使用顶层 main 字段，它现在是 Worker 的入口点。
• 不再要求 site.entry-point。入口点应通过 main 字段指定。
• 不再支持 webpack_config 和 webpack 属性。请参阅从 Wrangler 版本 1 迁移 webpack 项目。 以下是 Wrangler v1 中不再支持的命令：
• wrangler preview - 使用 wrangler dev 命令在本地环境中运行 Worker。
• wrangler generate - 如果要使用入门模板，请克隆其 GitHub 仓库并手动初始化。
• wrangler route - 路由在 Wrangler 配置文件 中定义。
• wrangler report - 如果发现 bug，请在 Wrangler issues ↗ 报告。
• wrangler build - 如果要访问打包 Worker 的输出，请使用 wrangler deploy --outdir=path/to/output。

这些是可以添加到你的 Wrangler 配置文件 的新字段。

• main: string，可选

  main 字段用于指定 Worker 的入口点。可以是传统的 service worker 格式，也可以是较新的、首选的 modules 格式。现在必须显式指定入口点，可以通过 main 字段配置，也可以直接作为命令行参数传递，例如 wrangler dev index.js。此字段取代了旧版 build.upload.main 字段（仅适用于 modules 格式的 Workers）。

• rules: array，可选

  rules 字段是模块类型与文件模式之间的映射数组。它指示 Wrangler 以不同于 JavaScript 的方式解释特定文件。例如，这对于将类似文本的内容读取为文本文件，或将编译后的 WASM 读取为可直接实例化和执行的内容非常有用。这些规则适用于传统 service worker 格式和较新的 modules 格式的 Workers。此字段取代了旧版 build.upload.rules 字段（仅适用于 modules 格式的 Workers）。

一些以前必填的配置字段，现在在特定情况下变为可选。它们可以被推断，或作为优化项添加。使用 Wrangler v2 启动时不再有任何必填字段，你可以根据需要逐步添加配置。

• name: string

  name 配置字段对于 wrangler dev 或任何 wrangler kv:* 命令不再必填。此外，也可以作为命令行参数 --name <name> 传递。对于 wrangler deploy 仍然必填。

• account_id: string

  account_id 字段对于任何命令都不再必填。任何相关命令都会检查你是否已登录，如果未登录，将提示你登录。登录后，将使用你的账户 ID，在登录会话过期之前不会再次提示。如果你有多个账户 ID，将显示账户列表供你选择。

  你仍然可以在 Wrangler 文件中配置 account_id，或将其设置为环境变量 CLOUDFLARE_ACCOUNT_ID。这可以加快启动速度，并在有多个 ID 时跳过选择列表。CLOUDFLARE_API_TOKEN 环境变量对于无法交互式登录的情况也很有用。了解更多，请参阅在 CI/CD 中运行。

• workers_dev boolean，默认：无路由时为 true

  workers_dev 字段用于指示 Worker 应发布到 *.workers.dev 子域。例如，对于名为 my-worker 且已配置 *.workers.dev 子域 username 的 Worker，该 Worker 将发布到 my-worker.username.workers.dev.com。此字段不是必填的，当未配置 route 或 routes 时默认为 true。存在路由时，默认为 false。如果既不想发布到 *.workers.dev 子域，也不想发布到任何路由，请将 workers_dev 设置为 false。当你将 Worker 发布为只能通过另一个 Worker（services）访问的独立服务时，这很有用。

一些配置字段已弃用，但其存在目前还不是破坏性变更。建议阅读警告消息并按照说明迁移到新配置。它们将在未来版本中移除并停止工作。

• zone_id: string，已弃用

  zone_id 字段已弃用，将在未来版本中移除。现在会从 route/routes 推断，使用 wrangler dev 时还可从 dev.host 推断。这也简化了将单个 Worker 部署到多个域名的操作。

• build.upload: object，已弃用

  build.upload 字段已弃用，将在未来版本中移除。使用它会产生警告，并提供重写配置文件以消除警告的建议。

  • build.upload.main/build.upload.dir 被 main 字段取代，适用于 service worker 格式和 modules 格式的 Workers。
  • build.upload.rules 被 rules 字段取代，适用于 service worker 格式和 modules 格式的 Workers。
  • 不再指定 build.upload.format，由 wrangler 自动推断。

一些配置字段已弃用，将不再按预期工作。建议阅读错误消息并按照说明迁移到新配置。

• site.entry-point: string，已弃用

  site.entry-point 配置用于指定带有 [site] 配置的 Worker 的入口点。它已被顶层 main 字段取代。

• type: rust | javascript | webpack，已弃用

  type 配置用于指定 Worker 的类型。它已变得冗余，现在会从使用情况推断。如果你使用 type = "webpack"（以及可选的 webpack_config 字段），应阅读 webpack 迁移指南 以修改项目并使用自定义构建。

以下命令在 Wrangler v2 中已弃用。

wrangler build 命令不再可用于构建 Worker。

等效功能可以通过 wrangler publish --dry-run --outdir=path/to/build 实现。

wrangler config 命令不再可用于通过 API 令牌进行身份验证。

使用 wrangler login / wrangler logout 管理 OAuth 身份验证，或通过 CLOUDFLARE_API_TOKEN 环境变量提供 API 令牌。

wrangler preview 命令不再可用于创建 Worker 的临时预览实例。

请尝试使用 wrangler dev 在开发期间测试 Worker。

wrangler subdomain 命令不再可用于创建 workers.dev 子域。

在 Workers & Pages > 选择你的 Worker > Your subdomain（你的子域名） > Change（更改） 中创建 workers.dev 子域。

wrangler route 命令不再可用于为 Worker 配置路由。

路由在 Wrangler 配置文件 中指定。

• Cloudflare 仪表板定义的路由不会与 Wrangler 定义的路由一起添加。Wrangler 定义的路由是 wrangler.toml 中的 route 或 routes 键。如果两者都定义，只有 wrangler.toml 中定义的路由有效。要仅通过 Cloudflare 仪表板管理路由，请从 Wrangler 文件中移除任何 route 和 routes 键，并添加 workers_dev = false。

• Wrangler 不再将调用 wrangler dev 的目录中的 index.js 作为 Worker 的入口点。请使用 main 配置字段，或显式将其作为命令行参数传递，例如：wrangler dev index.js。

• Wrangler 不再假设裸说明符（bare specifiers）在未表示为路径时是文件名。例如，在如下文件夹中：

  project
  ├── index.js
  └── some-dependency.js

  其中 index.js 的内容为：

  import SomeDependency from "some-dependency.js";
  
  addEventListener("fetch", (event) => {
    // ...
  });

  Wrangler v1 会将 import SomeDependency from "some-dependency.js"; 解析为文件 some-dependency.js。这在 Wrangler v2 中仍然有效，但也会记录弃用警告。将来，这将因错误而中断。相反，你应该重写 import 以指定它是相对路径，如下所示：

  - import SomeDependency from "some-dependency.js";
  + import SomeDependency from "./some-dependency.js";