看到 Cloudflare 新 CLI 的消息，最容易顺手做的一件事，是把 package.json 里的 wrangler deploy 改成 cf deploy。两个工具都能发布 Worker，名字看起来像直接替代关系。但现阶段这样改，可能让程序部署成功了，配置却不是原来那份。
cf 于 2026 年 9 月 28 日进入 Beta。它扩展了公共 API 的覆盖范围，也引入 TypeScript 项目配置。对已有 Workers 项目，决定是否迁移，应该从运行依赖和配置差异开始，而不是从安装命令开始。
先判断是不是必须迁移
如果需求只是查 DNS、列出 R2 桶或管理账户资源，可以直接使用 cf 的资源命令。项目开发和发布继续交给 Wrangler，不需要先动应用配置。
真正需要考虑迁移的情况，是团队希望配置有类型提示、希望统一项目与资源操作，或者希望构建一次后重复部署同一份产物。仍依赖 Wrangler 特定能力的项目，则可以保持现状。
当前官方说明，实时日志流和单个 secret 设置还有操作需要 Wrangler。因此“覆盖整个公共 API”不等于“每一种开发工作流都已经替代完成”。Wrangler 用户指南
两份配置文件不会自动互认
Wrangler 使用 wrangler.jsonc 或 wrangler.toml，cf 项目使用 cloudflare.config.ts。后者出现以后，cf 不再用旧文件作为项目配置；Wrangler 也不会读取新文件。
这会产生一个实际风险：配置迁了一半，脚本仍调用 Wrangler，看到的仍是旧绑定。另一个风险是反过来的，脚本已经改成 cf，但新配置缺少原来的入口、路由或环境定义。
官方文档列出了未迁移项目直接运行 cf build 的不同结果。有的项目报错；有的静态资产项目被自动识别成静态站点，构建甚至可以成功，但生成的配置没有原来的 Worker 代码和绑定。构建成功不能当成迁移完整的证据。
最稳妥的准备，是先记录现有 Worker 名称、入口文件、兼容日期、路由、资源 ID、环境和部署命令。代码差异容易审阅，少了一个触发器却可能只在定时任务运行时才被发现。
在干净的分支里预览迁移
确认 Node.js 至少为 22.18，保留当前 lockfile，然后在独立分支进行：
git status --short
cf --version
cf migrate --dry-run
如果目录有未提交改动，先按照团队流程保存，不要用 --force 跳过检查。这里的“干净”包括未跟踪文件；把本来的工作和迁移生成物混在一起，会让回退和审查都更难。
预览时检查工具准备写哪些文件，是否识别了正确的配置文件，以及选择了哪个构建器。项目可能沿用 Wrangler bundler，也可能已经使用 Cloudflare Vite 插件；迁移不要求所有项目都改用 Vite。
迁移命令提供的构建器、预览和安装选项。
确认预览以后再运行 cf migrate，随后查看 git diff。工具处理大部分转换，但它生成的文件不是不可质疑的最终答案。迁移完整流程
TODO 要解决，不要只把阻止构建的代码删掉
遇到需要人工处理的项目，迁移器会加入 TODO(@cloudflare)。有必需事项时，还会在文件顶部生成 throw，防止后续构建发布。
这类阻断说明有配置尚未完成。为了让构建继续，直接删除 throw，却不处理下面的绑定和生命周期，相当于把提醒关掉了，问题还在。
Durable Objects 尤其需要认真看。迁移器不会简单转换旧 migrations 历史，需要按已经在线运行的类声明相应 exports，并匹配现有 storage。已经执行过的重命名、删除或转移记录，不应机械复制成新的操作。
同样，Workflows、Containers 和部分构建设置也可能需要手动处理。读懂 TODO 对应的资源，再决定配置；不要凭“它大概是这个字段”去猜。程序化配置说明
环境名变化，会影响发布目标
Wrangler 常用 --env，cf 使用 --mode。迁移器会把环境转换为按 ctx.mode 分支返回的配置。
cf build --mode staging
cf deploy --dry-run --mode staging
这里应重点检查 staging 里的 Worker 名称和所有资源 ID。预发布环境的配置必须完整，不能认为顶层变量或绑定会自然继承过去。
还要注意 Vite 的默认 development、production 模式。如果原环境恰好叫这两个名字，迁移器可能要求人工审阅。一次未显式传 mode 的本地构建，可能选中与你预期不同的分支。
因此，审查时用一张简单清单对应每个环境：Worker、路由、数据库、队列、定时任务、secrets 声明。不要只对比文件行数。CLI 变了，真正不该变的是应用访问的那组资源。
数据库迁移需要额外小心
D1 旧配置中的迁移目录、文件匹配和迁移表参数，不能假设都会直接带进新配置。官方说明这些需要对应到 cf d1 migrations apply 的参数。
更关键的是默认作用位置：cf d1 migrations apply 默认操作远程数据库，只有加支持的 --local 才指向本地。旧脚本如果习惯本地默认值，迁移时必须重新审阅。
cf d1 migrations apply --help
先读当前版本帮助和数据库 ID，不要在迁移项目配置时顺手执行数据库迁移。代码配置转换、数据结构变更、远程发布是三种不同动作，最好分别留证据和回退安排。
构建工具没换，也要检查 build 的前后步骤
有些项目在构建之前生成样式、类型或静态文件。cf build 调用构建器，并不自动执行你 package.json 中任意自定义的 build 脚本。换入口时要检查原来的前置步骤是否仍被调用。
如果沿用 Wrangler bundler，部分构建选项会转移到 wrangler.config.ts。使用 Vite 时，则需要将对应选项放进 vite.config.ts。把所有选项都塞进 cloudflare.config.ts，并不能让它们自动生效。
此外要提交必要配置和锁文件，将 .cloudflare/ 生成目录加入忽略规则，并按官方说明处理模块类型及生成类型文件。命令与字段对照
先本地，再 dry run，再预发布
解决所有必需 TODO 后，运行本地开发，检查真实入口、绑定和关键接口；再构建与预览部署：
cf dev
# 停止开发服务后再执行
cf build
cf deploy --dry-run
对每个实际环境重复验证。dry run 不上传，但也不能替代预发布环境里的功能测试。它看不到真实账号权限、远程资源数据和外部服务行为。
最终正式发布前，应确认脚本调用的是 cf、新配置指向正确资源，并保留已知可用的代码和配置。如果后续还需要 wrangler tail，暂时保留旧配置，知道哪一条命令读哪一份文件。
迁移完成的标志，是应用按预期运行、各环境目标正确，而不是旧配置文件已经被删除。