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 静态资源托管。读完本篇你将获得一套可直接复制、可投入生产环境的完整开发链路并能理解每个命令与配置项背后的实现原理。从零开始创建并部署你的第一个 WorkerWrangler 是 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 # Deploywrangler 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.varsWorker 的敏感信息API Key、Token 等不应写死在代码或wrangler.jsonc中。生产环境使用 Wrangler 的 Secret 系统管理# Production echo secret-value | wrangler secret put SECRET_KEY # Local: use .dev.vars (gitignored) # SECRET_KEYlocal-dev-key关键区别在于wrangler secret put设置的密钥只作用于已部署的线上 Worker本地开发时并不生效这是 gotchas.md 中明确列出的常见坑。本地开发请使用.dev.vars文件每行一条KEYvalue且该文件应加入.gitignore防止密钥泄露。若需集中管理可跨 Worker 复用的密钥可进一步使用wrangler secret-store:secret put STORE_NAME SECRET_NAME与 Secrets Store 绑定。接入 KV键值存储的完整接入链路KVKey-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 deploywrangler 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 Placementplacement: { 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 有完整参数表取值行为适用场景false默认本地模拟速度快日常单元/集成测试minimal真实远程绑定 本地 Worker速度快需要真实绑定的快速测试true全远程执行结果与生产一致但更慢排查生产专属问题务必在测试结束后调用worker.dispose()否则测试进程会挂起gotchas.md 明确提醒。若需测试单个函数而非完整 Worker可改用getPlatformProxy它无需启动 Worker 即可在 Node.js 中模拟 KV、D1、R2、Cache 等绑定。测试进阶Vitest、多 Worker 服务绑定与外部 API MockVitest 集成测试安装依赖后通过cloudflare/vitest-pool-workers的defineWorkersConfig让 Vitest 在 Workerd 运行时中执行测试安装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); });其中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): PromiseResponse { return Response.json({ value: await env.MY_KV.get(key) }); } } satisfies ExportedHandlerEnv;satisfies ExportedHandlerEnv让编译器校验整个 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.fetchexport 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare Wrangler 开发模式实战指南：从初始化、本地开发到测试与部署的完整工作流
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 静态资源托管。读完本篇你将获得一套可直接复制、可投入生产环境的完整开发链路并能理解每个命令与配置项背后的实现原理。从零开始创建并部署你的第一个 WorkerWrangler 是 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 # Deploywrangler 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.varsWorker 的敏感信息API Key、Token 等不应写死在代码或wrangler.jsonc中。生产环境使用 Wrangler 的 Secret 系统管理# Production echo secret-value | wrangler secret put SECRET_KEY # Local: use .dev.vars (gitignored) # SECRET_KEYlocal-dev-key关键区别在于wrangler secret put设置的密钥只作用于已部署的线上 Worker本地开发时并不生效这是 gotchas.md 中明确列出的常见坑。本地开发请使用.dev.vars文件每行一条KEYvalue且该文件应加入.gitignore防止密钥泄露。若需集中管理可跨 Worker 复用的密钥可进一步使用wrangler secret-store:secret put STORE_NAME SECRET_NAME与 Secrets Store 绑定。接入 KV键值存储的完整接入链路KVKey-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 deploywrangler 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 Placementplacement: { 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 有完整参数表取值行为适用场景false默认本地模拟速度快日常单元/集成测试minimal真实远程绑定 本地 Worker速度快需要真实绑定的快速测试true全远程执行结果与生产一致但更慢排查生产专属问题务必在测试结束后调用worker.dispose()否则测试进程会挂起gotchas.md 明确提醒。若需测试单个函数而非完整 Worker可改用getPlatformProxy它无需启动 Worker 即可在 Node.js 中模拟 KV、D1、R2、Cache 等绑定。测试进阶Vitest、多 Worker 服务绑定与外部 API MockVitest 集成测试安装依赖后通过cloudflare/vitest-pool-workers的defineWorkersConfig让 Vitest 在 Workerd 运行时中执行测试安装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); });其中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): PromiseResponse { return Response.json({ value: await env.MY_KV.get(key) }); } } satisfies ExportedHandlerEnv;satisfies ExportedHandlerEnv让编译器校验整个 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.fetchexport 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
