Cloudflare Wrangler 完全指南从安装、认证到部署与测试的 CLI 实战手册【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsWrangler 是 Cloudflare 开发者平台的官方 CLI用于从命令行创建、开发、调试、测试并部署 Workers 及各类平台资源KV、D1、R2、Durable Objects 等。本文以 wrangler 参考文档 为主线系统讲解安装方式、常用命令、认证流程、配置规范、测试 API 与常见坑点帮助你在本地与生产之间建立可复现的完整工作流。读完本文你将掌握从wrangler init到wrangler deploy的全链路操作并能用startWorker编写集成测试、用wrangler tail定位线上问题。Wrangler 是什么Wrangler 是 Cloudflare Worker 运行时workerd官方命令行工具围绕 Workers 的完整生命周期提供能力创建、开发与部署 Workers管理各类绑定Binding包括 KV、D1、R2、Durable Objects、Queues、Vectorize 等配置路由Routing与环境Environments运行本地开发服务器底层由 miniflare 驱动模拟 workerd 运行时执行数据库迁移与资源管理支持集成测试与可观测性调试。在本仓库中Wrangler 参考文档位于 wrangler 目录与 workers、miniflare、workerd 等参考文档同属于 cloudflare-deploy 技能包供 Agent 在部署 Cloudflare 应用时按需加载。安装与版本管理Wrangler 通过 npm 分发推荐以项目依赖方式安装便于锁定版本、接入 CInpm install wrangler --save-dev # 或全局安装 npm install -g wrangler安装后通过npx wrangler command执行命令使用 pnpm / yarn 时则对应pnpm wrangler、yarn wrangler。说明本文命令基于当前仓库文档所述版本配置建议使用 v3.91.0 的wrangler.jsonc格式执行前可用wrangler --version确认本机版本。认证部署前的第一道关卡部署前必须先完成认证。快速判断方式npx wrangler whoami # 显示账号信息未认证时退出码非 0本仓库的 SKILL.md 明确指出认证在任何wrangler deploy、wrangler pages deploy或npm run deploy之前是必选项。完整认证细节见 auth.md。交互式登录本地开发推荐npx wrangler login # 打开浏览器完成一次性 OAuth 流程 npx wrangler whoami # 验证显示邮箱与 Account IDOAuth 凭证保存在本机之后所有命令自动生效。API TokenCI/CD 或无头环境登录 Cloudflare 控制台进入My Profile → API Tokens点击Create Token选择模板Edit Cloudflare Workers覆盖 Workers、Pages、KV、D1、R2复制 Token仅展示一次注入环境变量export CLOUDFLARE_API_TOKENyour-token-here场景模板 / 权限部署 Workers/PagesEdit Cloudflare Workers 模板只读访问Read All Resources 模板自定义最小权限Account:Read Workers Scripts:Edit 具体资源常见认证问题错误原因解决Not logged in无凭证wrangler login或设置CLOUDFLARE_API_TOKENAuthentication errorToken 无效/过期在控制台重新生成 TokenMissing account选错账号wrangler whoami检查并在wrangler.jsonc中补充account_id本地可用但 CI 失败Token 作用域账号不一致核对两边 Account ID 是否一致Insufficient permissionsToken 缺少权限按所需权限重新创建 Tokenwrangler whoami的输出包含邮箱OAuth 登录时、Account ID 与名称、Token 权限范围API Token 时。常用命令速查以下命令全部来自 README.md 的 Essential Commands按生命周期分组。项目与开发wrangler init [name] # 创建新项目 wrangler dev # 本地开发服务器快速、模拟运行 wrangler dev --remote # 使用远端资源联调接近生产 wrangler deploy # 部署到生产 wrangler deploy --env staging # 部署到指定环境 wrangler versions list # 列出版本 wrangler rollback [id] # 回滚部署 wrangler login # OAuth 登录 wrangler whoami # 检查认证状态KV键值存储wrangler kv namespace create NAME wrangler kv key put key value --namespace-idid wrangler kv key get key --namespace-ididD1关系型 SQLitewrangler d1 create NAME wrangler d1 execute NAME --command SQL wrangler d1 migrations create NAME description wrangler d1 migrations apply NAMER2对象存储wrangler r2 bucket create NAME wrangler r2 object put BUCKET/key --file path wrangler r2 object get BUCKET/key其他资源wrangler queues create NAME wrangler vectorize create NAME --dimensions N --metric cosine wrangler hyperdrive create NAME --connection-string ... wrangler workflows create NAME wrangler constellation create NAME wrangler pages project create NAME wrangler pages deployment create --project NAME --branch mainSecrets机密管理wrangler secret put NAME # 设置 Worker 机密 wrangler secret list # 列出 Worker 机密 wrangler secret delete NAME # 删除 Worker 机密 wrangler secret bulk FILE.json # 从 JSON 批量上传 # Secrets Store集中式、可跨 Worker 复用 wrangler secret-store:secret put STORE_NAME SECRET_NAME wrangler secret-store:secret list STORE_NAME监控wrangler tail # 实时日志 wrangler tail --env production # 追踪指定环境 wrangler tail --status error # 按状态过滤wrangler.jsonc 配置详解推荐格式与 Schema 校验wrangler.jsonc 为推荐格式v3.91.0自带 Schema 校验配置错误在写入阶段即可被发现{ $schema: ./node_modules/wrangler/config-schema.json, name: my-worker, main: src/index.ts, compatibility_date: 2025-01-01, // 使用当前日期 vars: { API_KEY: dev-key }, kv_namespaces: [{ binding: MY_KV, id: abc123 }] }compatibility_date决定运行时行为基线缺失会导致“意外运行时变化”详见 gotchas.md。字段继承规则多环境关键可继承name、main、compatibility_date、routes、triggers不可继承需每个环境单独定义vars、各类绑定KV、D1、R2 等这也是 gotchas 中 “Environment not inheriting config” 的根源非继承字段必须在每个环境里重新声明。多环境Environments{ name: my-worker, vars: { ENV: dev }, env: { production: { name: my-worker-prod, vars: { ENV: prod }, route: { pattern: example.com/*, zone_name: example.com } } } }部署指定环境wrangler deploy --env production。环境数量没有上限见 gotchas 的 Limits 表。路由Routing// 自定义域名推荐 { routes: [{ pattern: api.example.com, custom_domain: true }] } // 基于 Zone { routes: [{ pattern: api.example.com/*, zone_name: example.com }] } // workers.dev { workers_dev: true }绑定Bindings绑定是 Worker 访问平台资源KV/D1/R2/DO 等的桥梁完整配置如下// 变量 { vars: { API_URL: https://api.example.com } } // KV { kv_namespaces: [{ binding: CACHE, id: abc123 }] } // D1 { d1_databases: [{ binding: DB, database_id: abc-123 }] } // R2 { r2_buckets: [{ binding: ASSETS, bucket_name: my-assets }] } // Durable Objects { durable_objects: { bindings: [{ name: COUNTER, class_name: Counter, script_name: my-worker // 外部 DO 必填 }] } } { migrations: [{ tag: v1, new_sqlite_classes: [Counter] }] } // Service BindingsWorker 间调用 { services: [{ binding: AUTH, service: auth-worker }] } // Queues { queues: { producers: [{ binding: TASKS, queue: task-queue }], consumers: [{ queue: task-queue, max_batch_size: 10 }] } } // Vectorize { vectorize: [{ binding: VECTORS, index_name: embeddings }] } // Hyperdrivepg/postgres 需要 nodejs_compat_v2 { hyperdrive: [{ binding: HYPERDRIVE, id: hyper-id }] } { compatibility_flags: [nodejs_compat_v2] } // Workers AI { ai: { binding: AI } } // Workflows { workflows: [{ binding: WORKFLOW, name: my-workflow, class_name: MyWorkflow }] } // Secrets Store集中式机密 { secrets_store: [{ binding: SECRETS, id: store-id }] } // ConstellationAI 推理 { constellation: [{ binding: MODEL, project_id: proj-id }] }注意绑定名称binding/name即代码中env的键与资源 IDid/database_id/bucket_name是两个不同概念预览绑定还需单独提供preview_id、preview_database_id。混淆两者正是 gotchas 中 “Binding ID vs name mismatch” 的常见原因。Workers Assets静态文件推荐用assets取代旧的site配置来托管静态文件{ assets: { directory: ./public, binding: ASSETS, html_handling: auto-trailing-slash, // 或 none、force-trailing-slash not_found_handling: single-page-application // 或 404-page、none } }Worker 内访问静态资源export default { async fetch(request, env) { // 先尝试服务静态资源 const asset await env.ASSETS.fetch(request); if (asset.status ! 404) return asset; // 非资源请求走自定义逻辑 return new Response(API response); } }静态资源部署限制见 gotchas.md单次部署 25 MB、最多 20,000 个文件。Placement地理位置控制{ placement: { mode: smart // 或 off } }smart将 Worker 调度到靠近数据源D1、Durable Objects的位置以降低延迟off默认分布随处运行。注意Smart Placement 仅在访问 D1 或 Durable Objects 时有收益对 KV、R2 或外部 API 的延迟没有影响。自动预置资源Beta省略资源 IDWrangler 会在部署时自动创建并回写配置{ kv_namespaces: [{ binding: MY_KV }] } // 无 id —— 自动预置首次部署后配置会自动补上 ID。此时应提交更新后的配置后续部署会复用已存在资源详见 gotchas 中 “Auto-provisioned resources not appearing”。高级配置// Cron 触发器 { triggers: { crons: [0 0 * * *] } } // 可观测性链路追踪 { observability: { enabled: true, head_sampling_rate: 0.1 } } // 运行时限制 { limits: { cpu_ms: 100 } } // Browser Rendering { browser: { binding: BROWSER } } // mTLS 证书 { mtls_certificates: [{ binding: CERT, certificate_id: cert-uuid }] } // Logpush把日志流转到 R2/S3 { logpush: true } // Tail Consumers用另一个 Worker 处理日志 { tail_consumers: [{ service: log-worker }] } // Unsafe bindings访问任意绑定 { unsafe: { bindings: [{ name: MY_BINDING, type: plain_text, text: value }] } }程序化 API在 Node.js 中启动与测试 Worker除了 CLIWrangler 还导出 Node.js API见 api.md让测试与自动化脚本可以直接启动 Worker。startWorker集成测试的核心startWorker是稳定 API取代了已废弃的unstable_startWorker以真实本地绑定启动 Workerimport { startWorker } from wrangler; import { describe, it, before, after } from node:test; import assert from node:assert; describe(worker, () { let worker; before(async () { worker await startWorker({ config: wrangler.jsonc, environment: development }); }); after(async () { await worker.dispose(); }); it(responds with 200, async () { const response await worker.fetch(http://example.com); assert.strictEqual(response.status, 200); }); });Options 一览选项类型说明configstringwrangler.jsonc 路径environmentstring配置文件中的环境名persistboolean \| { path: string }启用持久化状态bundleboolean启用打包默认 trueremotefalse \| true \| minimal远程模式false本地、true完全远程、minimal仅远端绑定三种远程模式// 本地模式默认—— 快、模拟运行 const worker await startWorker({ config: wrangler.jsonc }); // 完全远程 —— 贴近生产、较慢 const worker await startWorker({ config: wrangler.jsonc, remote: true }); // 最小远程 —— 远端绑定 本地 Worker兼顾速度与真实绑定 const worker await startWorker({ config: wrangler.jsonc, remote: minimal });getPlatformProxy不启动 Worker 模拟绑定适用于单元测试只测单个函数或需要绑定能力的脚本import { getPlatformProxy } from wrangler; const { env, dispose, caches } await getPlatformProxyEnv({ configPath: wrangler.jsonc, environment: production, persist: { path: .wrangler/state } }); // 使用绑定 const value await env.MY_KV.get(key); await env.DB.prepare(SELECT * FROM users).all(); await env.ASSETS.put(file.txt, content); // 平台 API await caches.default.put(https://example.com, new Response(cached)); await dispose();事件系统与动态重配置监听 Worker 生命周期事件适合构建监控或高级工作流import { startWorker } from wrangler; const worker await startWorker({ config: wrangler.jsonc, bundle: true }); // 打包事件 worker.on(bundleStart, (details) { console.log(Bundling started:, details.config); }); worker.on(bundleComplete, (details) { console.log(Bundle ready:, details.duration); }); // 重配置事件 worker.on(reloadStart, () console.log(Worker reloading...)); worker.on(reloadComplete, () console.log(Worker reloaded)); await worker.dispose();动态重配置const worker await startWorker({ config: wrangler.jsonc }); // 整体替换配置 await worker.setConfig({ config: wrangler.staging.jsonc, environment: staging }); // 局部修改字段 await worker.patchConfig({ vars: { DEBUG: true } }); await worker.dispose();多 Worker 注册表测试 Service Bindingsimport { startWorker } from wrangler; const auth await startWorker({ config: ./auth/wrangler.jsonc }); const api await startWorker({ config: ./api/wrangler.jsonc, bindings: { AUTH: auth } // Service binding }); const response await api.fetch(http://example.com/api/login); // API Worker 通过 env.AUTH.fetch() 调用 AUTH Worker await api.dispose(); await auth.dispose();最佳实践集成测试用startWorker测完整 Worker单元测试用getPlatformProxy测单个函数排查生产相关问题用remote: true追求“真实绑定 快速”用remote: minimal调试时开启persist: true让状态跨运行保留配置变更后运行wrangler types重新生成类型始终调用dispose()防止资源泄漏监听 bundle 事件做构建监控用多 Worker 注册表验证 Service Bindings。实战模式与工作流新建项目与本地开发wrangler init my-worker cd my-worker wrangler dev # 本地模式快、模拟 wrangler deploy # 部署本地开发进阶选项wrangler dev --remote # 远程模式贴近生产 wrangler dev --env staging --port 8787 wrangler dev --inspector-port 9229 # 开启调试调试方法打开 Chrome进入chrome://inspect→ Configure → 添加localhost:9229。机密管理开发 vs 生产# 生产通过 stdin 注入 echo secret-value | wrangler secret put SECRET_KEY # 本地使用 .dev.vars已被 gitignore 忽略 # SECRET_KEYlocal-dev-key注意wrangler secret put设置的机密只对已部署的 Worker 生效本地开发必须用.dev.vars。添加 KVwrangler kv namespace create MY_KV wrangler kv namespace create MY_KV --preview # 写入 wrangler.jsonc{ binding: MY_KV, id: abc123 } wrangler deploy添加 D1含迁移与时间旅行wrangler d1 create my-db wrangler d1 migrations create my-db initial_schema # 编辑 migrations/ 下的迁移文件然后 wrangler d1 migrations apply my-db --local wrangler deploy wrangler d1 migrations apply my-db --remote # Time Travel恢复到时间点 wrangler d1 time-travel restore my-db --timestamp 2025-01-01T12:00:00Z多环境工作流wrangler deploy --env staging wrangler deploy --env production{ env: { staging: { vars: { ENV: staging } } } }测试Node.js Test Runner 集成测试import { startWorker } from wrangler; import { describe, it, before, after } from node:test; import assert from node:assert; describe(API, () { let worker; before(async () { worker await startWorker({ config: wrangler.jsonc, remote: minimal // 快 真实绑定 }); }); after(async () await worker.dispose()); it(creates user, async () { const response await worker.fetch(http://example.com/api/users, { method: POST, body: JSON.stringify({ name: Alice }) }); assert.strictEqual(response.status, 201); }); });测试Vitest Workers 池安装npm install -D vitest cloudflare/vitest-pool-workersvitest.config.ts:import { defineWorkersConfig } from cloudflare/vitest-pool-workers/config; export default defineWorkersConfig({ test: { poolOptions: { workers: { wrangler: { configPath: ./wrangler.jsonc } } } } });tests/api.test.ts:import { env, SELF } from cloudflare:test; import { describe, it, expect } from vitest; it(fetches users, async () { const response await SELF.fetch(https://example.com/api/users); expect(response.status).toBe(200); }); it(uses bindings, async () { await env.MY_KV.put(key, value); expect(await env.MY_KV.get(key)).toBe(value); });Mock 外部 API通过outboundService拦截 Worker 的出站请求const worker await startWorker({ config: wrangler.jsonc, outboundService: (req) { const url new URL(req.url); if (url.hostname api.external.com) { return new Response(JSON.stringify({ mocked: true }), { headers: { content-type: application/json } }); } return fetch(req); // 其余请求透传 } }); const response await worker.fetch(http://example.com/proxy); // Worker 内部 fetch api.external.com 时得到 mock 响应注意mock 函数必须返回Response未命中 mock 的请求务必用fetch(req)透传否则请求会被静默丢弃。TypeScript 类型生成wrangler types # 生成 worker-configuration.d.tsexport default { async fetch(request: Request, env: Env): PromiseResponse { return Response.json({ value: await env.MY_KV.get(key) }); } } satisfies ExportedHandlerEnv;Assets API 混合架构{ assets: { directory: ./dist, binding: ASSETS } }export default { async fetch(request, env) { // 先处理 API 路由 if (new URL(request.url).pathname.startsWith(/api/)) { return Response.json({ data: from API }); } return env.ASSETS.fetch(request); // 静态资源兜底 } }常见坑点与排查典型错误速查现象原因解决Binding ID vs name mismatch混淆绑定名与资源 IDbinding是代码名id/database_id/bucket_name是资源 ID预览绑定需preview_id/preview_database_idEnvironment not inheriting config非继承字段未在环境内重定义vars与绑定必须按环境重新声明routes、compatibility_date可继承本地与生产行为不一致使用本地模拟而非远程执行需要真实行为时用wrangler dev --remote或remote: truestartWorker doesnt match production本地模式缺少远程资源传remote: true或minimal意外运行时变化缺少compatibility_date始终设置compatibility_dateDO 绑定不生效外部 DO 缺少script_name外部 DO 必填script_name同 Worker 内本地 DO 可省略自动预置资源“消失”首次部署回写的 ID 未提交提交更新后的配置后续部署复用已有资源本地开发拿不到机密secret put仅对已部署 Worker 生效本地用.dev.varsNode.js 兼容错误缺少兼容标志Hyperdrive pg等场景加compatibility_flags: [nodejs_compat_v2]Workers Assets 404路径不匹配或html_handling配置错误检查assets.directorySPA 用auto-trailing-slashnot_found_handling: single-page-applicationPlacement 未降低延迟误解 Smart Placement 适用场景仅当访问 D1/DO 时有效对 KV/R2/外部 API 无效unstable_startWorker not found使用过期 API改用稳定版startWorkeroutboundService未拦截mock 函数未返回 Response总是返回Response未命中时fetch(req)透传资源与限制Limits资源/限制数值备注每 Worker 绑定数64所有类型合计环境数量无限制配置中的命名环境配置文件大小约 1MB保持合理Workers Assets 大小25 MB单次部署Workers Assets 文件数20,000上限脚本大小压缩1 MB免费档付费档 10 MBCPU 时间10-50ms免费档付费档 50-500ms子请求数50免费档付费档 1000排查命令# 认证 wrangler logout wrangler login wrangler whoami # 配置校验 wrangler check # 配合 $schema 验证配置 # 部署失败 wrangler tail # 查看日志 wrangler deploy --dry-run # 预检 wrangler whoami # 检查账号限制 # 本地开发问题 wrangler dev --remote # 使用远端绑定 wrangler dev --persist-to ./local-state # 自定义持久化位置 wrangler dev --inspector-port 9229 # 开启调试注原文建议rm -rf .wrangler/state清理本地状态请按你的实际需要谨慎使用。决策树按需求快速定位Need to test your Worker? ├─ 测完整 Worker 绑定 → api.md §startWorker ├─ 测单个函数 → api.md §getPlatformProxy └─ 用 Vitest 测试 → patterns.md §Testing with Vitest Need to configure something? ├─ 绑定KV、D1、R2 等 → configuration.md §Bindings ├─ 多环境 → configuration.md §Environments ├─ 静态文件 → configuration.md §Workers Assets └─ 路由 → configuration.md §Routing Development not working? ├─ 本地与生产不一致 → 使用 wrangler dev --remote ├─ 绑定不可用 → gotchas.md §Binding Not Available └─ 认证问题 → auth.md Authentication issues? ├─ Not logged in / Unauthorized → auth.md ├─ 首次部署 → wrangler login一次性 OAuth └─ CI/CD 配置 → auth.md §API Token延伸阅读本仓库cloudflare-deploy技能包中与 Wrangler 紧密相关的参考资料wrangler 完整参考命令总览即本文主线文档wrangler 配置参考wrangler.jsonc全量字段wrangler 认证参考登录与 API Token 细节wrangler 程序化 APIstartWorker/getPlatformProxy完整选项wrangler 实战模式KV/D1/多环境/测试工作流wrangler 常见坑点错误排查与限制清单workers 运行时 APIWorker 侧编程模型miniflare 本地测试wrangler dev背后的本地模拟器workerd 运行时驱动wrangler dev的实际运行时cloudflare-deploy 技能入口部署前的认证检查与决策树。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考