从 Wrangler v3 迁移到 v4

Wrangler v4 是一次主要版本发布，专注于底层系统和依赖项的更新，以及保持 Wrangler 命令一致和清晰的改进。与之前专注于基础重写 ↗和重新架构 ↗的 Wrangler 主要版本不同——Wrangler 第 4 版包含的变更集要小得多。如果你今天使用 Wrangler，你的工作流程很可能不会改变。

虽然许多用户应该可以无操作升级，但以下部分概述了更重要的变更以及必要时迁移的步骤。

要在 Worker 项目中升级到最新的 Wrangler v4，请运行：

npm i -D wrangler@4

yarn add -D wrangler@4

pnpm add -D wrangler@4

bun add -d wrangler@4

升级后，你可以验证安装：

npx wrangler --version

yarn wrangler --version

pnpm wrangler --version

• 更新的 Node.js 支持策略： Node.js v16 于 2022 年达到生命周期结束，Wrangler v4 不再支持。Wrangler 现在遵循 Node.js 的官方支持生命周期 ↗。

• 升级 esbuild 版本：Wrangler 使用 esbuild ↗ 在部署前打包 Worker 代码，之前固定为 esbuild v0.17.19。Wrangler v4 使用 esbuild v0.24，这可能影响动态通配符导入。今后，Wrangler 将定期更新 Wrangler 中包含的 esbuild 版本，由于 esbuild 是 1.0.0 之前的工具，这有时可能包括打包工作方式的破坏性变更。特别是，我们可能会在 Wrangler 次要版本中升级 esbuild 版本。

• 命令默认为本地模式：所有可以在本地或远程模式运行的命令现在默认为本地，需要 --remote 标志才能通过 API 查询。

• 已移除已弃用的命令和配置： 旧版命令、标志和配置已被移除。

Wrangler 现在仅支持与 Node.js 官方生命周期 ↗ 一致的 Node.js 版本：

• 支持：Current、Active LTS、Maintenance LTS
• 不再支持： Node.js v16（2022 年 EOL）

Wrangler 测试不再在 v16 上运行，仍在使用此版本的用户可能会遇到不受支持的行为。仍在使用 Node.js v16 的用户必须升级到受支持的版本，才能继续获得 Wrangler 的支持和兼容性。

node --version

Wrangler v4 将 esbuild 从 v0.17.19 升级到 v0.24，带来改进（例如能够使用 using 关键字与 RPC 配合）以及打包行为变更：

• 动态导入： 通配符导入（例如 import('./data/' + kind + '.json')）现在会自动在 bundle 中包含所有匹配的文件。

依赖通配符动态导入的用户可能会看到不需要的文件被打包。在 esbuild v0.19 之前，具有动态路径的 import 语句（如 import('./data/' + kind + '.json')）不会打包匹配 glob 模式（*.json）的所有文件。只有使用 find_additional_modules 显式引用或包含的文件才会被打包。从 esbuild v0.19 开始，通配符导入现在会自动打包匹配 glob 模式的所有文件。这可能导致不需要的文件被打包，因此用户可能希望避免通配符动态导入，改用显式导入。

所有命令现在默认在本地模式下运行。Wrangler 有许多用于访问 KV 和 R2 等资源的命令，但这些命令以前在本地或远程环境中运行时不一致。例如，D1 默认查询本地数据存储，需要 --remote 标志才能通过 API 查询。另一方面，KV 以前默认通过 API 查询（隐式使用 --remote 标志），需要 --local 标志才能查询本地数据存储。为了使 Wrangler 的行为一致，每个命令现在默认使用 --local 标志，需要显式 --remote 标志才能通过 API 查询。

例如：

• 之前的行为（Wrangler v3）： wrangler kv key get 默认远程查询。
• 新行为（Wrangler v4）： wrangler kv key get 默认本地查询，除非指定 --remote。

使用 wrangler kv key 和/或 wrangler r2 object 命令查询或写入数据存储的用户需要添加 --remote 标志才能复制之前的行为。

grep -rE "wrangler (kv|r2)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

# Before (Wrangler v3 - queried remote by default)
wrangler kv key get --binding MY_KV "my-key"

# After (Wrangler v4 - must specify --remote)
wrangler kv key get --binding MY_KV "my-key" --remote

Wrangler v2 和 Wrangler v3 中所有先前已弃用的功能现已移除。此外，Wrangler v3 发布期间已弃用的以下功能也已移除：

• Legacy Assets（使用 wrangler dev/deploy --legacy-assets 或 legacy_assets 配置文件属性）。相反，我们建议你迁移到 Workers Static Assets。
• Legacy Node.js 兼容性（使用 wrangler dev/deploy --node-compat 或 node_compat 配置文件属性）。相反，请使用 nodejs_compat 兼容性标志。这包括旧版 node_compat polyfill 的功能和原生实现的 Node.js API。
• wrangler version。相反，使用 wrangler --version 检查当前 Wrangler 版本。
• getBindingsProxy()（通过 import { getBindingsProxy } from "wrangler"）。相反，使用 getPlatformProxy() API，它接受完全相同的参数。
• usage_model。在 Workers Standard Pricing 推出 ↗ 后，这不再有任何效果。

# For TOML files
grep -E "(legacy_assets|node_compat|usage_model)\s*=" wrangler.toml

# For JSON files
grep -E "\"(legacy_assets|node_compat|usage_model)\"" wrangler.json wrangler.jsonc

grep -rE "wrangler.*(--legacy-assets|--node-compat)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

grep -rE "getBindingsProxy" --include="*.js" --include="*.ts" --include="*.mjs" .