Wrangler CLI

使用项目的 Wrangler 版本，并在编写命令或配置之前检索相关文档。CLI 标志和配置字段会变化；不要依赖记忆中的示例。

检查项目

• 查找包管理器、已安装的 Wrangler 版本、包脚本、框架和 Wrangler 配置。通过项目的脚本或包管理器运行命令，以便使用其本地版本。需要时使用现有锁文件安装依赖；不要静默升级 Wrangler 以匹配当前文档。如果 Wrangler 不是依赖项，请遵循安装指南将其本地添加。
• 识别构建或部署命令使用的配置，包括框架生成的配置。编辑其来源，而不是生成的输出。
• 在运行会更改目标账号、Worker、环境和资源的命令之前，先确定这些目标。对于数据操作，确定目标是本地还是远程。

获取任务所需信息

如果可用，使用 Cloudflare MCP docs 工具，或直接获取相关链接页面。请跟踪链接到所涉及的具体命令或产品；避免加载整个参考文档。如果页面已移动，请通过 Wrangler 命令索引 或 Cloudflare 文档搜索重新找到它。

| 任务 | 来源 | | --- | --- | | 发现命令和标志，包括资源管理、部署、回滚和诊断 | 项目本地 wrangler --help 和 wrangler <command> --help；命令参考 | | 编辑配置或添加绑定 | 已安装的 wrangler/config-schema.json（通常位于 node_modules 下）；配置参考 | | 部署框架应用 | 框架指南；遵循适用于项目现有框架和适配器的指南 | | 在用户要求时将应用迁移到 Workers | Pages 到 Workers；Vercel 到 Workers | | 配置预发布或生产 | 环境 | | 在本地、CI 或已部署 Worker 上设置密钥 | 密钥 | | 生成绑定和运行时类型 | TypeScript | | 本地运行或选择测试方法 | 本地开发；测试 | | 诊断身份验证或选择账号 | 通用命令，包括 whoami；身份验证配置文件 | | 部署未认证原型 | 声明部署，用于资格、过期和声明 URL 处理；生产或 CI 使用永久账号 |

使用已安装的帮助和 schema 检查文档中的功能是否存在于项目版本中。如果所需功能需要升级，请明确说明该依赖。如果无法检索，请说明缺口并使用可用的本地证据，而不是编造语法。

应用变更

• 新配置优先使用 wrangler.jsonc。将新项目的兼容性日期设置为今天；推进现有项目日期时，检查运行时变更并进行测试。保留现有项目约定，避免偶然的格式迁移。
• 在添加绑定或变量之前检查环境继承。某些字段必须为每个环境分别指定；可用的默认配置并不能证明预发布环境已配置。
• 使用 Cloudflare Vite 插件时，在开发或构建时通过 CLOUDFLARE_ENV 选择环境。部署生成的构建；在部署时设置环境不会重新指向其扁平化配置。参见 Vite 环境。
• 部署前将管理面板变更与配置进行协调：Wrangler 可以覆盖管理面板变量和路由。绑定现有资源时，验证其标识符；省略标识符可能触发自动预配。
• 开发时区分本地模拟与远程绑定。本地运行的 Worker 仍可能访问真实资源；测试写入前检查所选绑定。
• 将密钥值排除在命令参数、源代码和日志之外。使用该命令文档说明的交互式输入或受保护的文件/stdin 机制。本地密钥文件必须被版本控制忽略，并且不会自动上传为已部署密钥。对于缺失的本地密钥，检查文件优先级以及密钥文档中的任何 secrets.required 声明。
• 将 wrangler secret put 和 secret delete 视为部署：它们会创建版本并立即部署。当变更必须暂存时，使用文档说明的 wrangler versions secret 工作流。
• 回滚前检查回滚限制：关联资源及其数据不会随 Worker 代码一起回滚。

验证

在 TypeScript 项目中更改配置或绑定后，使用项目的 wrangler types 命令重新生成类型，而不是手动编辑生成的声明。运行相关现有类型检查或测试。

对于部署变更，在支持的情况下，使用项目的构建工作流和 wrangler deploy --dry-run，并指定预期配置和环境。成功的试运行会检查构建和打包；它不能证明远程资源或运行时行为正常。根据请求的工作使用任务特定的本地或远程检查。

报告变更内容、目标环境、已执行检查，以及任何未解决的验证缺口。当结果依赖当前命令或配置行为时，链接所使用的文档。