wrangler

Wrangler CLI

仅当项目包含 wrangler.jsonc、wrangler.json 或 wrangler.toml，且不包含 cloudflare.config.ts 时，或用户要求使用 Wrangler 时，才使用此技能。对于新项目、包含 cloudflare.config.ts 的项目或没有 Cloudflare 配置的项目，请改用 Cloudflare CLI（cf）：如果已安装 cf-cli 技能，请加载该技能；否则请遵循与编码 Agent 一起使用 cf。不要在这些项目中添加 Wrangler。

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

检查项目

• 找出包管理器、已安装的 Wrangler 版本、包脚本、框架和 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
在本地运行或选择测试方法	本地开发；测试
为 Wrangler 选择角色、范围或 API 令牌权限	角色和权限；Workers 角色和权限
创建或管理分支或拉取请求环境	预览概览；开始使用；配置
确定预览资源是隔离还是共享	资源和隔离，包括当前限制
配置预览 URL、访问权限、调试或 CI	自定义域名；测试和调试；示例
在预览、版本 URL 和 Wrangler 环境之间进行选择	比较工作流
诊断身份验证问题或选择账户	常规命令，包括 whoami；身份验证配置文件
部署未经身份验证的原型	查看认领部署，了解资格、过期时间和认领 URL 的处理方式；生产环境或 CI 请使用永久账户

使用已安装版本的帮助信息和架构，检查文档中提到的功能是否存在于项目所用版本中。如果所需功能需要升级，请明确说明这一依赖。如果无法检索信息，请指出这一缺口，并依据可用的本地证据操作，而不要臆造语法。

应用变更

• 新建配置时优先使用 wrangler.jsonc。将新项目的兼容性日期设为今天；推进现有项目的日期时，请检查运行时变更并进行测试。保留现有项目约定，避免顺带迁移格式。
• 添加绑定或变量前，先检查环境继承情况。有些字段必须针对每个环境分别指定；默认配置可正常工作，并不代表 staging 环境已配置。
• 使用 Cloudflare Vite 插件时，在开发或构建时通过 CLOUDFLARE_ENV 选择环境。部署生成的构建产物；在部署时设置环境不会重新指定其扁平化配置。请参阅 Vite 环境。
• 部署前，将仪表板中的变更与配置进行协调：Wrangler 可能会覆盖仪表板变量和路由。绑定现有资源时，请核实其标识符；省略标识符可能会触发自动预配。
• 开发时要区分本地模拟和远程绑定。本地运行的 Worker 仍可能访问真实资源；测试写入操作前，请检查所选绑定。
• 执行远程命令前，确认已通过身份验证的成员或 API 令牌，并获取执行确切操作所需的当前角色和权限范围。优先选择满足用户意图的最小权限范围。wrangler login OAuth 流程不支持细粒度授权；需要细粒度访问权限时，请使用账户所有者创建的 API 令牌，且绝不要要求用户将其值粘贴到聊天中。
• 不要将密钥值放入命令参数、源代码或日志中。请使用文档说明的交互式输入方式，或受保护的文件／stdin 机制来执行命令。本地密钥文件必须从版本控制中排除，并且不会自动作为已部署的密钥上传。缺少本地密钥时，请检查文件优先级以及密钥文档中的 secrets.required 声明。
• 将 wrangler secret put 和 secret delete 视为部署操作：它们会创建一个版本并立即部署。需要暂存变更时，请使用文档说明的 wrangler versions secret 工作流。
• 回滚前，请检查回滚限制：关联资源及其数据不会随 Worker 代码一起回滚。

使用 Workers Previews

• Workers Previews 要求项目本地的 Wrangler 版本为 4.135.0 或更高；项目命令不会使用较新的全局安装版本。检查项目锁定的版本，并明确进行任何必要的依赖升级。
• 使用 Previews 为同一 Worker 创建分支和拉取请求环境。使用 Version URLs 检查已上传版本在生产资源下的运行情况；使用 Wrangler 环境部署持久且独立的 Worker。请遵循比较工作流，不要沿用旧版的别名 Version URL 工作流。
• 首先检查用户如何管理生产配置和部署。通过与生产环境相同的配置系统（例如 Wrangler、控制面板或 Terraform）配置 Preview 域名。除非用户要求采用其他工作流，否则应通过用户现有的路径（例如本地 CLI、Workers Builds 或外部 CI）运行 Preview 部署。保持管理方式一致，而不是照搬生产资源绑定或数据。
• 部署前，请遵循当前的配置放置表和资源矩阵与限制。不要根据 Preview 名称推断隔离情况，也不要允许写入生产资源，除非用户明确表示要共享这些资源。
• 告知用户，除非配置了访问控制，否则 Preview URL 是公开的，然后让用户决定是否保护这些 URL。请根据所选设置遵循自定义域名和访问指南。
• 确认用户打算针对哪个 Worker 或 Wrangler 环境。针对 Wrangler 环境时，所有 Preview 命令都要传入相同的 --env 值；省略该参数会针对顶层 Worker。

验证

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

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

对于 Previews，如果 Wrangler 报告缺少绑定，那么返回的 URL 并不能验证依赖这些绑定的行为。请使用 Preview 专用日志和配置（如有需要），验证用户要求的行为。对生产资源执行写入、破坏性测试以及删除指定的 Preview，都必须符合用户的明确意图。

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