在 Cloudflare Workers 项目用…

当你需要运行或排查 Wrangler CLI 命令、为 Worker 项目配置本地开发/Preview/部署/Cloudflare 资源时使用。

适用场景

解决思路

1. 写命令或配置前，先使用项目自身的 Wrangler 版本并检索对应版本文档；CLI flag 与配置字段会变化，不要依赖记忆中的示例。
2. 先摸清项目的包管理器、已安装的 Wrangler 版本、package scripts、框架和 Wrangler 配置；通过项目的 scripts 或包管理器运行命令，确保使用其本地版本。
3. 需要时按现有 lockfile 安装依赖；不要为了对齐最新文档而静默升级 Wrangler。若 Wrangler 不是项目依赖，按安装指南把它本地加入。
4. 确认构建或部署命令实际使用的配置（包括框架生成的配置）；改其源文件，而不是改生成产物。
5. 在执行会改动目标的命令前，先确定目标账号、Worker、环境和资源；数据操作要先判断目标是本地还是远程。
6. 检索资料时优先用 Cloudflare MCP 的 docs 工具，或直接抓取相关链接页面；顺着链接进入具体命令或产品页，避免加载整个参考文档。页面迁移时通过 Wrangler 命令索引或 Cloudflare 文档搜索重新找到它。
7. 按任务选择来源：发现命令与 flag（含资源管理、部署、回滚、诊断）用项目本地 `wrangler --help`、`wrangler <command> --help` 和命令参考；编辑配置或加 binding 用已安装的 `wrangler/config-schema.json`（通常在 node_modules 下）和配置参考；部署框架应用用框架指南并遵循项目现有框架与适配器；把应用迁移到 Workers 用 Pages to Workers、Vercel to Workers 迁移指南；配置 staging 或 production 用 Environments 文档；在本地、CI 或已部署 Worker 上设置 secret 用 Secrets 文档；生成 binding 与运行时类型用 TypeScript 文档；本地运行或选择测试方案用 Local development 与 testing 文档；为 Wrangler 选择角色、scope 或 API token 权限用 Roles and permissions 与 Workers roles and permissions；创建或管理分支/PR 环境用 Previews 的 overview、get started、configuration 文档；判断 Preview 资源是隔离还是共享用 Resources and isolation（含其当前限制）；配置 Preview URL、访问控制、调试或 CI 用对应文档；在 Previews、Version URLs、Wrangler environments 之间选择用 Compare workflows；诊断认证或选账号用 general commands（含 `whoami`）与 authentication profiles；部署未认证原型用 Claim deployments 了解资格、过期与 claim URL 处理，生产或 CI 则用永久账号。
8. 用已安装的 help 和 schema 校验文档里的特性在项目版本中是否存在；若某特性必须升级才能用，把这项依赖升级显式化。
9. 若无法检索文档，明确说明这一缺口，改用已有的本地证据，而不是编造语法。
10. 新配置优先用 `wrangler.jsonc`；新项目的 compatibility date 设为当天；推进已有项目的日期时先审查运行时变化并测试；保留项目既有约定，避免顺手做格式迁移。
11. 添加 binding 或变量前先检查环境继承：有些字段必须为每个环境单独指定；默认配置能跑通并不代表 staging 已配置好。
12. 使用 Cloudflare Vite 插件时，在 dev 或 build 阶段通过 `CLOUDFLARE_ENV` 选择环境；部署生成好的构建产物；在部署时设置环境不会重定向已被扁平化的配置。
13. 部署前把 dashboard 上的改动与配置对齐：Wrangler 可能覆盖 dashboard 的变量和路由；绑定已有资源时核对资源标识符，省略标识符可能触发 automatic provisioning。
14. 开发中区分本地模拟与远程绑定：本地运行的 Worker 仍可能访问真实资源，测试写入前先检查所选 binding。
15. 执行远程命令前，确认已认证的成员或 API token，并查清该具体操作当前所需的角色与 scope，选择满足用户意图的最窄 scope。`wrangler login` 的 OAuth 流程不支持细粒度授权；需要细粒度访问时使用账号自有的 API token，且绝不要让用户把 token 值粘贴到聊天中。
16. secret 值不得出现在命令参数、源码和日志里；使用文档规定的交互式输入或受保护文件/stdin 机制。本地 secret 文件必须被版本控制忽略，且不会自动作为部署 secret 上传。本地 secret 缺失时，检查文件优先级和 secrets 文档中的 `secrets.required` 声明。
17. 把 `wrangler secret put` 和 `wrangler secret delete` 当作部署对待：它们会立即创建版本并部署；需要暂存时改用文档中的 `wrangler versions secret` 流程。
18. 回滚前查看回滚限制：关联资源及其数据不会随 Worker 代码一起回滚。
19. Workers Previews 需要项目本地 Wrangler 4.135.0 或更高版本；项目命令不会使用更新版本的全局安装。检查项目固定的版本，并把必须的依赖升级显式化。
20. 用 Previews 承载同一 Worker 下的分支与 PR 环境；用 Version URLs 配合生产资源查看某个具体已上传版本；用 Wrangler environments 做持久、独立部署的 Worker；遵循 Compare workflows，而不是改造旧的别名 Version URL 工作流。
21. 先了解用户如何管理生产配置与部署；Preview 域名通过与生产相同的配置体系（Wrangler、dashboard 或 Terraform）配置；Preview 部署走用户既有路径（本地 CLI、Workers Builds 或外部 CI），除非用户要求不同流程；镜像其管理方式，而不是镜像生产资源绑定或数据。
22. Preview 部署前，遵循最新的 configuration placement table 和 resource matrix 与 limitations；不要凭 Preview 名称推断隔离性；除非用户明确要共享，否则不要写入生产资源。
23. 告知用户 Preview URL 默认是公开的（除非配置了访问控制），再由其决定是否保护这些 URL；按所选方案遵循 custom domain 与 access 指南。
24. 确认用户想针对哪个 Worker 或 Wrangler 环境；针对某个 Wrangler 环境时，每条 Preview 命令都传相同的 `--env` 值，省略它就会指向顶层 Worker。
25. TypeScript 项目改动配置或 binding 后，用项目的 `wrangler types` 重新生成类型，不要手改生成的声明；运行项目已有的相关 typecheck 或测试。
26. 部署变更时使用项目的 build 流程，并在支持时用带目标配置与环境的 `wrangler deploy --dry-run`；dry run 成功只验证构建与打包，不证明远程资源或运行时行为可用；按任务需要做相应的本地或远程检查。
27. 对 Previews，返回的 URL 不能验证那些依赖 Wrangler 报告为缺失的 binding 的行为；按用户请求验证行为，必要时使用 Preview 专用日志和配置；写入生产资源、破坏性测试、删除具名 Preview 必须与用户明确意图一致。
28. 汇报改了什么、目标环境、做了哪些检查、以及任何未解决的验证缺口；当结果依赖当前命令或配置行为时，附上所用文档链接。

适用边界 · 注意事项

• 不适用于非 Cloudflare Workers 或没有 Wrangler 依赖的项目。
• 不要凭记忆或旧版本示例执行 Wrangler 命令与配置，也不要为对齐最新文档而静默升级项目固定的 Wrangler 版本。
• 无法检索 Cloudflare 文档/帮助/schema 时，不要编造命令、flag 或配置字段，应说明信息缺口。