企业官网建设流程全解析

Cloudflare Wrangler 开发模式实战指南：从初始化、本地开发到测试与部署的完整工作流

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇指南以 patterns.md 为核心脉络，系统讲解 Cloudflare Workers 开发中最常用的 Wrangler 工作流与最佳实践：从新建 Worker 项目、本地/远程开发调试，到 KV 与 D1 资源接入、多环境部署、四种测试模式（Node.js Test Runner、Vitest、Service Bindings 多 Worker、外部 API Mock）、版本监控、TypeScript 类型生成与 Workers Assets 静态资源托管。读完本篇，你将获得一套可直接复制、可投入生产环境的完整开发链路，并能理解每个命令与配置项背后的实现原理。

从零开始：创建并部署你的第一个 Worker

Wrangler 是 Cloudflare 开发者平台的官方 CLI，负责创建、开发、管理并部署 Workers，同时支持 KV、D1、R2、Durable Objects 等各类绑定资源的配置、迁移与集成测试（见 README.md）。安装后（npm install wrangler --save-dev或全局npm install -g wrangler），一个典型的新项目工作流只有三步：

wrangler init my-worker && cd my-worker wrangler dev # Develop locally wrangler deploy # Deploy

wrangler init会生成项目骨架，其中wrangler.jsonc是推荐使用的配置文件格式（v3.91.0+ 起支持 JSON Schema 校验）。一个最小化的wrangler.jsonc通常包含以下字段（参见 configuration.md）：

{ "$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决定了运行时行为随 Cloudflare 平台演进的方式，务必显式设置，否则可能遭遇“意外的运行时行为变化”这类难以排查的问题（参见 gotchas.md）。部署前建议先用npx wrangler whoami确认认证状态，首次部署需执行wrangler login完成一次性 OAuth 登录。

本地开发：local 模式与 remote 模式的选择

wrangler dev是开发期使用频率最高的命令，它提供两种执行模式，对应不同的精度与速度权衡：

wrangler dev # Local mode (fast, simulated) wrangler dev --remote # Remote mode (production-accurate) wrangler dev --env staging --port 8787 wrangler dev --inspector-port 9229 # Enable debugging

• 本地模式（默认）：基于 Miniflare/workerd 在本机模拟运行时，启动快、迭代快，适合日常开发，但某些行为与生产环境存在差异；
• 远程模式（--remote）：请求真正打到 Cloudflare 边缘执行，使用真实的远程绑定资源，结果与生产一致但延迟更高。当本地表现与生产不一致时，切换到--remote是官方推荐的排查手段；
• --env staging指定目标环境，--port 8787自定义监听端口；
• --inspector-port 9229开启调试端口，配合 Chrome DevTools 的chrome://inspect → Configure → localhost:9229即可对 Worker 代码进行断点调试。

密钥管理：Production Secrets 与本地 .dev.vars

Worker 的敏感信息（API Key、Token 等）不应写死在代码或wrangler.jsonc中。生产环境使用 Wrangler 的 Secret 系统管理：

# Production echo "secret-value" | wrangler secret put SECRET_KEY # Local: use .dev.vars (gitignored) # SECRET_KEY=local-dev-key

关键区别在于：wrangler secret put设置的密钥只作用于已部署的线上 Worker，本地开发时并不生效（这是 gotchas.md 中明确列出的常见坑）。本地开发请使用.dev.vars文件，每行一条KEY=value，且该文件应加入.gitignore防止密钥泄露。若需集中管理可跨 Worker 复用的密钥，可进一步使用wrangler secret-store:secret put STORE_NAME SECRET_NAME与 Secrets Store 绑定。

接入 KV：键值存储的完整接入链路

KV（Key-Value Store）适合存储配置、会话与缓存类数据。接入流程分为三步：创建命名空间、写入配置、部署：

wrangler kv namespace create MY_KV wrangler kv namespace create MY_KV --preview # Add to wrangler.jsonc: { "binding": "MY_KV", "id": "abc123" } wrangler deploy

wrangler kv namespace create MY_KV返回的id需要写入wrangler.jsonc的kv_namespaces数组，其中binding是代码中使用的绑定名，id是资源标识——不要混淆二者（gotchas.md 中“Binding ID vs name mismatch”即为此问题）。--preview会额外创建一个预览命名空间，用于本地/预发布测试。部署后，Worker 代码中即可通过env.MY_KV.get("key")/env.MY_KV.put(...)访问该绑定。

接入 D1：关系型数据库与迁移管理

D1 是 Cloudflare 的 SQLite 兼容关系型数据库。接入流程包含建库、创建迁移、本地应用、部署、远程应用五个步骤：

wrangler d1 create my-db wrangler d1 migrations create my-db "initial_schema" # Edit migration file in migrations/, then: wrangler d1 migrations apply my-db --local wrangler deploy wrangler d1 migrations apply my-db --remote

迁移文件创建后会生成在migrations/目录下，你需要按需编辑其中的 SQL，再依次应用到本地与远程环境。注意--local与--remote需分别执行，本地数据库状态持久化在.wrangler/state中。D1 还内置了**时间旅行（Time Travel）**能力，可将数据库恢复到任意历史时间点：

# Time Travel (restore to point in time) wrangler d1 time-travel restore my-db --timestamp 2025-01-01T12:00:00Z

这一能力非常适合误操作后的快速恢复场景。此外，日常查询可用wrangler d1 execute NAME --command "SQL"直接执行语句。若 D1 数据量或地理位置优化是瓶颈，可参考 configuration.md 中的 Smart Placement（placement: { "mode": "smart" }）——它只在 Worker 访问 D1 或 Durable Objects 时降低延迟，对 KV/R2/外部 API 无效。

多环境管理：staging / production 隔离部署

多环境（Multi-Environment）允许用同一份代码管理多个部署目标，是 pre-production 验证的标准手段：

wrangler deploy --env staging wrangler deploy --env production

对应在wrangler.jsonc中通过env字段声明各环境的差异化配置：

{ "env": { "staging": { "vars": { "ENV": "staging" } } } }

理解字段继承规则是正确使用多环境的关键（参见 configuration.md）：

• 可继承字段：name、main、compatibility_date、routes、triggers——子环境可覆盖；
• 不可继承字段：vars、各类绑定（KV、D1、R2 等）——每个环境必须显式定义。

如果生产环境发现vars或绑定“凭空消失”，多半是违反了上述继承规则（gotchas.md 中的 “Environment not inheriting config” 正是此问题）。本地开发同样可用wrangler dev --env staging指定环境。

集成测试：Node.js Test Runner 与 startWorker

从 v3 起，Wrangler 提供了稳定的编程式 APIstartWorker（取代旧的unstable_startWorker，参见 api.md），可直接在 Node.js 测试中启动带真实本地绑定的 Worker 实例：

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" // Fast tests with real bindings }); }); 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); }); });

startWorker的remote选项有三种取值（api.md 有完整参数表）：

务必在测试结束后调用worker.dispose()，否则测试进程会挂起（gotchas.md 明确提醒）。若需测试单个函数而非完整 Worker，可改用getPlatformProxy，它无需启动 Worker 即可在 Node.js 中模拟 KV、D1、R2、Cache 等绑定。

测试进阶：Vitest、多 Worker 服务绑定与外部 API Mock

Vitest 集成测试

安装依赖后，通过@cloudflare/vitest-pool-workers的defineWorkersConfig让 Vitest 在 Workerd 运行时中执行测试：

安装：npm install -D vitest @cloudflare/vitest-pool-workers

vitest.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"); });

其中SELF用于向当前 Worker 发起请求，env直接暴露所有已配置的绑定供测试读写。

多 Worker 开发（Service Bindings）

微服务架构下，一个 Worker 常通过 Service Binding 调用另一个 Worker。startWorker支持同时启动多个 Worker 并通过bindings参数注入服务绑定，从而在测试中真实演练跨服务调用：

const authWorker = await startWorker({ config: "./auth/wrangler.jsonc" }); const apiWorker = await startWorker({ config: "./api/wrangler.jsonc", bindings: { AUTH: authWorker } // Service binding }); // Test API calling AUTH const response = await apiWorker.fetch("http://example.com/api/protected"); await authWorker.dispose(); await apiWorker.dispose();

这与配置文件中services: [{ "binding": "AUTH", "service": "auth-worker" }]的声明方式对应，是 api.md 中“Multi-Worker Registry”能力的测试侧印证。

Mock 外部 API

当 Worker 依赖第三方外部 API 时，可通过outboundService回调拦截并模拟出站请求，避免测试依赖真实网络：

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); // Pass through other requests } }); // Test Worker that calls external API const response = await worker.fetch("http://example.com/proxy"); // Worker internally fetches api.external.com - gets mocked response

注意：Mock 函数必须返回Response，且对不打算 Mock 的请求必须return fetch(req)透传，否则请求会失败（gotchas.md 中 “outboundService not mocking fetch” 一节专门强调了这一点）。

监控与版本管理：tail、versions 与 rollback

生产环境的问题排查与发布回滚依赖以下命令：

wrangler tail # Real-time logs wrangler tail --status error # Filter errors wrangler versions list wrangler rollback [id]

• wrangler tail实时输出 Worker 的生产日志，--status error可过滤出错误级别的日志，也可用--env production指定环境；
• wrangler versions list查看历史版本，wrangler rollback [id]可在发布异常时快速回滚到指定版本。配合 configuration.md 中的observability: { "enabled": true, "head_sampling_rate": 0.1 }可开启链路追踪采样，让wrangler tail呈现更完整的调用上下文。

TypeScript 类型生成与安全访问绑定

手动为env编写类型容易遗漏或出错，Wrangler 提供自动生成：

wrangler types # Generate types from config

该命令基于wrangler.jsonc中的绑定声明生成worker-configuration.d.ts，因此每次修改配置后都应重新执行（api.md 的最佳实践清单中有此要求）。生成后即可获得类型安全的绑定访问：

export default { async fetch(request: Request, env: Env): Promise<Response> { return Response.json({ value: await env.MY_KV.get("key") }); } } satisfies ExportedHandler<Env>;

satisfies ExportedHandler<Env>让编译器校验整个 handler 是否符合ExportedHandler契约，从类型层面提前暴露绑定名拼写错误等问题。

Workers Assets：静态资源与 API 混合托管

当 Worker 需要同时提供前端静态资源与 API 时，使用 Workers Assets 配置（替代旧的site配置方案）：

{ "assets": { "directory": "./dist", "binding": "ASSETS" } }

完整的资产配置还支持 HTML 处理与 404 处理策略（参见 configuration.md）：

{ "assets": { "directory": "./public", "binding": "ASSETS", "html_handling": "auto-trailing-slash", // or "none", "force-trailing-slash" "not_found_handling": "single-page-application" // or "404-page", "none" } }

• html_handling控制目录请求的斜杠处理：auto-trailing-slash自动补齐/去除尾斜杠，force-trailing-slash强制尾斜杠，none不做处理；
• not_found_handling控制 404 行为：SPA 应用用single-page-application将所有未命中路由回落到index.html，传统站点用404-page。

在 Worker 代码中，推荐的模式是“API 优先、资产兜底”——先处理 API 路由，其余请求交给env.ASSETS.fetch：

export default { async fetch(request, env) { // API routes first if (new URL(request.url).pathname.startsWith("/api/")) { return Response.json({ data: "from API" }); } return env.ASSETS.fetch(request); // Static assets } }

需要留意资产相关限制（gotchas.md 的 Limits 表）：单次部署资产体积上限 25 MB、文件数上限 20,000；若遇到 404，先确认assets.directory是否指向正确的构建产物，再检查html_handling与not_found_handling是否匹配应用形态。

延伸阅读

• Wrangler 总览与常用命令 —— 安装方式、Essential Commands、快速决策树
• Wrangler 配置参考 —— wrangler.jsonc 字段、绑定声明、环境与路由
• Wrangler 编程式 API ——startWorker选项、getPlatformProxy、事件系统与动态重配置
• Wrangler 常见问题与限制 —— 常见错误根因、资源限额、调试技巧

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills