Workerd 运行时 API 实战指南从 Worker 入口、Web 平台 API 到 CLI 与 Wrangler 集成【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 Cloudflare Deploy 技能库skills/.curated/cloudflare-deploy中的 Workerd API 文档 为骨架系统讲解 Workerd 运行时的 Worker 代码模型ES Modules / Service Worker / Durable Objects / 服务间 RPC、内置 Web 平台 API 全集、CLI 命令以及 Wrangler 集成方式。读完本文你将能直接编写可运行的 Workerd Worker 代码、为绑定生成 TypeScript 类型并把本地开发、测试与生产部署串成一条完整链路。一、背景Workerd 是什么以及 API 文档的适用范围Workerd 是基于 V8 的 JS/Wasm 运行时也是 Cloudflare Workers 的底层引擎。正如 Workerd 运行时总览 所述它可以作为应用服务器、开发工具或 HTTP 反向代理使用核心特性包括基于标准的 Fetch API / Web Crypto / Streams / WebSocket、通过服务绑定实现纳米服务式本地调用、以及通过显式绑定实现能力安全防止 SSRF。需要特别注意的是官方安全提醒workerd 不是加固型沙箱切勿运行不可信代码。它面向的是本地/自托管部署你自己的代码场景Cloudflare 生产环境在其之上叠加了额外安全层。因此 cloudflare-deploy SKILL 给出的决策树是95% 的用户应当直接使用 Wranglerwrangler dev内部即调用 workerd只有在自托管生产环境、嵌入 C 应用、自定义测试工具或调试 workerd 特有行为时才直接操作 workerd 二进制。workerd 的整体架构以 Capn Proto 配置文件workerd.capnp为入口向下展开为 Servicesworker/网络/磁盘/外部端点、SocketsHTTP/HTTPS 监听与 Extensions全局能力。本文聚焦其中的运行时 API 层即 Worker 代码里能调用的所有入口与接口。二、Worker 代码模型JS/TS2.1 ES Modules推荐入口Workerd 的 Worker 代码推荐使用 ES Modules 语法通过export default导出多个具名处理器每个处理器对应一种运行时事件。以下示例完整覆盖了全部入口api.md 原文export default { async fetch(request, env, ctx) { const value await env.KV.get(key); // Bindings in env const response await env.API.fetch(request); // Service binding ctx.waitUntil(logRequest(request)); // Background task return new Response(OK); }, async adminApi(request, env, ctx) { /* Named entrypoint */ }, async queue(batch, env, ctx) { /* Queue consumer */ }, async scheduled(event, env, ctx) { /* Cron handler */ } };逐行拆解这段代码就能理解 Workerd 运行时的核心参数约定fetch(request, env, ctx)HTTP 请求入口是绝大多数 Worker 的主入口。request是标准Request对象env承载所有绑定KV、R2、服务绑定、环境变量等ctx是ExecutionContext提供waitUntil()用于后台任务、passThroughOnException()用于异常时回源。env.KV.get(key)ES Modules 模式下所有绑定都挂在env上。这里的KV是在 workerd 配置capnp 或 wrangler 配置中声明的绑定名代码中通过env.绑定名访问。而旧式 Service Worker 语法中绑定则作为全局变量存在见 2.3。env.API.fetch(request)服务绑定Service Binding。它让当前 Worker 能以本地调用的性能把请求转发给另一个 Worker 服务是纳米服务架构的关键。ctx.waitUntil(logRequest(request))把异步后台任务挂到请求生命周期上响应返回后任务继续执行不会阻塞响应——适合埋点、日志、缓存预热等场景。adminApi具名入口Named Entrypoint。一个 Worker 可以导出多个入口外部服务绑定可以通过entrypoint指定调用哪一个配置方式见configuration.md 的服务绑定小节。queue(batch, env, ctx)队列消费者入口处理 Cloudflare Queues 投递的消息批次。scheduled(event, env, ctx)定时任务Cron入口由调度事件触发。2.2 TypeScript 类型生成与手写Workerd/Workers 生态强烈推荐为env定义类型以获得完整的 IDE 提示与编译期检查。文档给出了两条路径路径一由wrangler.toml自动生成推荐wrangler types # Output: worker-configuration.d.ts该命令读取 wrangler 配置文件中的绑定声明生成worker-configuration.d.ts。绑定变更后重新执行即可同步类型。关于类型生成的完整工作流含安装 wrangler、查看生成结果等可参考 bindings/api.md。路径二手动声明Env接口interface Env { API: Fetcher; CACHE: KVNamespace; STORAGE: R2Bucket; ROOMS: DurableObjectNamespace; API_KEY: string; } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { return new Response(await env.CACHE.get(key)); } };注意不同类型绑定对应不同的 TS 类型服务绑定是FetcherKV 是KVNamespaceR2 是R2BucketDurable Object 是DurableObjectNamespace普通字符串变量如API_KEY直接是string。环境搭建两者都需要npm install -D cloudflare/workers-types// tsconfig.json {compilerOptions: {types: [cloudflare/workers-types]}}安装cloudflare/workers-types并提供标准 Workers API 类型Request、Response、ExecutionContext等wrangler types则补充你项目特有的绑定类型。运行时类型与构建期类型的分工可参考 bindings/api.md 的类型来源表。2.3 Service Worker 语法旧式在 ES Modules 普及之前Worker 使用 Service Worker 风格通过addEventListener注册fetch事件绑定直接作为全局变量访问addEventListener(fetch, event { event.respondWith(handleRequest(event.request)); }); async function handleRequest(request) { const value await KV.get(key); // Bindings as globals return new Response(OK); }这段代码展示了两个关键差异事件回调里必须调用event.respondWith()交出响应权且KV无需经过env直接是全局对象。文档与patterns.md 最佳实践均明确建议优先使用 ES Modules旧式语法仅用于维护遗留代码。2.4 Durable Objects有状态对象Durable ObjectsDO是 Workerd 提供的单实例有状态对象适合需要强一致状态、协调、实时场景。每个 DO 是一个导出类构造器接收state含持久化存储state.storage与envexport class Room { constructor(state, env) { this.state state; this.env env; } async fetch(request) { const url new URL(request.url); if (url.pathname /increment) { const value (await this.state.storage.get(counter)) || 0; await this.state.storage.put(counter, value 1); return new Response(String(value 1)); } return new Response(Not found, {status: 404}); } }state.storage.get/put提供持久化的键值存储自动保证同一时刻同一 DO 实例只处理一个请求避免并发写冲突。DO 的实例通过fetch()方法对外提供 HTTP 语义接口调用方用env.ROOMS.idFromName(...)get(id)获取 stub 后调用详见 bindings/api.md 的 Durable Objects 调用示例。要在 workerd 配置中启用 DO需要同时声明绑定durableObjectNamespace、命名空间durableObjectNamespaces与存储位置durableObjectStorage完整配置见configuration.md 的 DO 小节。2.5 服务间 RPC直接方法调用除了通过fetch()转发请求服务绑定还支持结构化 RPC——直接调用另一个服务的导出方法并拿到返回数据无需序列化成 HTTP// Caller: env.AUTH.validateToken(token) returns structured data const user await env.AUTH.validateToken(request.headers.get(Authorization)); // Callee: export methods that return data export default { async validateToken(token) { return {id: 123, name: Alice}; } };调用方把AUTH绑定当作一个本地对象直接调用方法validateToken返回的{id, name}对象会作为结构化数据传回调用方。这是纳米服务架构的核心开发体验服务之间以本地函数调用的方式协作同时保留进程/隔离边界。三、Web 平台 API 全景Workerd 实现了与浏览器/Cloudflare Workers 对齐的 Web 平台 API 子集开发者可直接复用 Web 生态的既有知识。文档将其分为以下几组API 分组包含接口典型用途Fetchfetch()、Request、Response、Headers发起到源站的子请求、构造响应StreamsReadableStream、WritableStream、TransformStream含字节流与 BYOB reader流式处理请求/响应体Web Cryptocrypto.subtleencrypt/decrypt/sign/verify、crypto.randomUUID()、crypto.getRandomValues()加密、签名、生成 UUIDEncodingTextEncoder、TextDecoder、atob()、btoa()文本与二进制互转Web StandardsURL、URLSearchParams、Blob、File、FormData、WebSocketURL 解析、表单处理、实时双向通信3.1 服务端事件流SSESSE 是单向服务器推送的标准方案。workerd 中可以利用TransformStream构造一个流式响应体配合text/event-stream内容类型即可// Server-side SSE const { readable, writable } new TransformStream(); const writer writable.getWriter(); writer.write(new TextEncoder().encode(data: Hello\n\n)); return new Response(readable, {headers: {Content-Type: text/event-stream}});注意 SSE 事件格式每行以data:开头事件之间以空行\n\n分隔。Response可以直接接收一个ReadableStream作为 body这是流式接口互通性的直接体现。3.2 HTMLRewriterHTML 解析与转换HTMLRewriter 是 Cloudflare 生态特有的流式 HTML 重写器允许你像用 jQuery 选择器一样对 HTML 元素做变换且以流式处理、开销极低。文档示例展示了链接改写 脚本移除的组合用法const response await fetch(https://example.com); return new HTMLRewriter() .on(a[href], { element(el) { el.setAttribute(href, /proxy?url${encodeURIComponent(el.getAttribute(href))}); } }) .on(script, { element(el) { el.remove(); } }) .transform(response);.on(selector, handlers)注册元素处理器element(el)回调中可读写属性、增删内容。典型场景包括 A/B 测试注入、分析脚本注入、链接重写HTTPS 升级、代理包装、敏感脚本移除等详见 workers/api.md 的 HTMLRewriter 小节。3.3 TCP Sockets实验性connect()提供原始 TCP 能力可绕过 HTTP 层直接与任意主机通信。文档给出一个极简的手工 HTTP GET示例const socket await connect({ hostname: example.com, port: 80 }); const writer socket.writable.getWriter(); await writer.write(new TextEncoder().encode(GET / HTTP/1.1\r\n\r\n)); const reader socket.readable.getReader(); const { value } await reader.read(); return new Response(value);socket.writable/socket.readable复用了 Streams 标准接口写入请求、读取响应。需注意该能力在文档中标注为Experimental正式使用前应确认当前 compatibility date 下的可用性。3.4 Performance 与 Consoleperformance.now()、performance.timeOrigin精确计时与基准测试。setTimeout()、setInterval()、queueMicrotask()定时与微任务调度。console.log()、console.error()、console.warn()结构化日志配合 workerd 的--verbose与logging配置输出到标准输出/错误流见configuration.md 日志小节。3.5 Node.js 兼容nodejs_compatflagWorkerd 提供了 Node.js 兼容层通过 compatibility flag 开启后即可import部分node:模块import { Buffer } from node:buffer; import { randomBytes } from node:crypto; const buf Buffer.from(Hello); const random randomBytes(16);可用模块node:buffer、node:crypto、node:stream、node:util、node:events、node:assert、node:path、node:querystring、node:url。不可用模块涉及文件系统与网络服务端node:fs、node:http、node:net、node:child_process。这一点与 workerd 的安全模型一致Worker 是无文件系统、无任意网络监听的运行时需要文件或服务端能力时应改用 KV/R2/外部服务绑定。开启方式是在 capnp 配置的compatibilityFlags中加入nodejs_compat见configuration.md 兼容性小节。四、CLI 命令workerd 提供四个核心 CLI 子命令api.md 原文workerd serve config.capnp [constantName] # Start server workerd serve config.capnp --socket-addr http*:3000 --verbose workerd compile config.capnp constantName -o binary # Compile to binary workerd test config.capnp [--test-onlytest.js] # Run tests逐个说明workerd serve按 capnp 配置文件启动服务器。constantName是配置文件中定义的 Config 常量名省略时取默认--socket-addr http*:3000覆盖某个 socket 的监听地址*:3000表示监听所有网卡的 3000 端口--verbose输出详细日志便于排错。workerd compile把配置与嵌入的模块编译为单一二进制-o binary指定输出路径。编译产物可直接执行启动更快、部署更简单生产部署首选详见 patterns.md 的生产部署小节。workerd test运行配置中声明的测试模块--test-onlytest.js指定只跑某个测试文件。测试文件必须出现在配置的modules [...]中。配套的校验手段capnp compile -I. config.capnp可对配置文件做语法与 schema 校验见 gotchas.md 的构建问题systemd 场景下还可用--socket-fd配合 socket 激活见 patterns.md 的 systemd 示例。五、Wrangler 集成与开发工作流对绝大多数开发者日常开发不应直接操作 workerd 二进制而是通过 Wranglerwrangler dev # Uses workerd internally wrangler types # Generate TypeScript types from wrangler.tomlwrangler dev内部启动 workerd 作为本地运行时提供热重载与自动配置读取是本地开发的首选。wrangler types与 2.2 节衔接从 wrangler 配置生成类型定义。wrangler deploy则将同一份代码部署到 Cloudflare 生产环境。在使用任何部署命令wrangler deploy、wrangler pages deploy、npm run deploy之前SKILL.md 的认证章节 要求先执行npx wrangler whoami确认已登录CI/CD 场景通过CLOUDFLARE_API_TOKEN环境变量认证。若你需要绕过 HTTP 层做测试或嵌入Wrangler 还提供了 Node.js 编程接口startWorker以真实本地绑定启动 Worker 做集成测试getPlatformProxy在 Node.js 中直接模拟绑定做单元测试详见 wrangler/api.md而 miniflare 则是在 workerd 沙箱上实现的本地模拟器无需联网即可测试 KV、DO、R2、D1、WebSocket、Queues 等完整能力。六、绑定如何进入env与配置文件的衔接API 文档中的env.KV、env.API、env.CACHE等绑定名并非凭空而来而是由 workerd 的 capnp 配置声明。理解这一层才能把 2.1 节的代码真正跑起来。下面是一个最小化的完整配置configuration.md 基础结构using Workerd import /workerd/workerd.capnp; const config :Workerd.Config ( services [(name main, worker .mainWorker)], sockets [(name http, address *:8080, http (), service main)] ); const mainWorker :Workerd.Worker ( modules [(name index.js, esModule embed src/index.js)], compatibilityDate 2024-01-15, bindings [...] );其中bindings决定env上有哪些键基本类型(name API_KEY, text secret)映射为env.API_KEY字符串json会解析为对象data为ArrayBufferfromEnvironment从系统环境变量取值。服务绑定(name AUTH, service auth-worker)映射为env.AUTHFetcher可配合entrypoint指向具名入口props注入ctx.props。存储绑定kvNamespace→KVNamespace、r2Bucket→R2Bucket、durableObjectNamespace→DurableObjectNamespace、memoryCache提供进程内缓存可设maxKeys/maxValueSize上限。其他queue→ 队列、analyticsEngine→ 分析、cryptoKey→ 密钥绑定、wrapped→ 包装绑定。因此调试绑定找不到类错误时按 gotchas.md 的排查步骤 在代码里打印Object.keys(env)即可核对配置名与代码访问名是否一致。开发阶段还可以通过Remote Bindings让本地 workerd 直连生产环境的 KV/R2/DO 资源需要accountId、namespaceId/bucketName/scriptName与 API Token见 configuration.md 远程绑定章节。七、编写 Worker 代码的最佳实践与常见陷阱结合 patterns.md 的最佳实践清单 与 gotchas.md 的排错指南与 API 层直接相关的要点如下优先 ES Modules 而非 Service Worker 语法绑定显式挂在env上类型安全且职责清晰避免全局命名空间污染。永远设置compatibilityDate这是 workerd 的功能门控。缺失会直接报 Missing compatibility date日期决定哪些 API 可用升级日期前务必先本地测试。后台任务用ctx.waitUntil()绝不await阻塞把日志、埋点等放到waitUntil中响应即刻返回workers/api.md 亦强调此点。错误处理用 try/catch 包裹捕获后记录console.error并返回 5xx避免未处理异常导致请求失败export default { async fetch(request, env, ctx) { try { return await handleRequest(request, env); } catch (error) { console.error(Request failed, error); return new Response(Internal Error, {status: 500}); } } };绑定类型别混用DO 必须用durableObjectNamespace而非serviceJSON 要用json 而非text 后者只是字符串不会解析。模块名与导入路径必须一致配置中name index.js使用简单名embed用相对路径嵌入二者不要混写成name src/index.js。安全基线密钥用fromEnvironment从环境变量注入而非硬编码在text绑定网络访问收敛为allow [public]或指定主机避免*crypto 密钥默认extractable false。生产部署前把配置编译为二进制workerd compile并固定 workerd 版本与 compatibility date 的匹配关系。八、延伸阅读workerd/configuration.mdcapnp 配置语法、services/sockets/bindings 全量字段、远程绑定与参数继承。workerd/patterns.md多服务架构、反向代理、Hono/itty-router 框架集成、Docker/systemd 部署。workerd/gotchas.md常见错误、性能问题、安全与兼容性陷阱的排查手册。workers/api.mdWorkers 运行时 API 补充Cache API、WebSocket Hibernation、D1 Session 等。bindings/api.md绑定类型对照表与类型生成工作流。miniflare/README.md 与 wrangler/api.md本地测试与编程式启动 Worker 的方案。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Workerd 运行时 API 实战指南：从 Worker 入口、Web 平台 API 到 CLI 与 Wrangler 集成
Workerd 运行时 API 实战指南从 Worker 入口、Web 平台 API 到 CLI 与 Wrangler 集成【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 Cloudflare Deploy 技能库skills/.curated/cloudflare-deploy中的 Workerd API 文档 为骨架系统讲解 Workerd 运行时的 Worker 代码模型ES Modules / Service Worker / Durable Objects / 服务间 RPC、内置 Web 平台 API 全集、CLI 命令以及 Wrangler 集成方式。读完本文你将能直接编写可运行的 Workerd Worker 代码、为绑定生成 TypeScript 类型并把本地开发、测试与生产部署串成一条完整链路。一、背景Workerd 是什么以及 API 文档的适用范围Workerd 是基于 V8 的 JS/Wasm 运行时也是 Cloudflare Workers 的底层引擎。正如 Workerd 运行时总览 所述它可以作为应用服务器、开发工具或 HTTP 反向代理使用核心特性包括基于标准的 Fetch API / Web Crypto / Streams / WebSocket、通过服务绑定实现纳米服务式本地调用、以及通过显式绑定实现能力安全防止 SSRF。需要特别注意的是官方安全提醒workerd 不是加固型沙箱切勿运行不可信代码。它面向的是本地/自托管部署你自己的代码场景Cloudflare 生产环境在其之上叠加了额外安全层。因此 cloudflare-deploy SKILL 给出的决策树是95% 的用户应当直接使用 Wranglerwrangler dev内部即调用 workerd只有在自托管生产环境、嵌入 C 应用、自定义测试工具或调试 workerd 特有行为时才直接操作 workerd 二进制。workerd 的整体架构以 Capn Proto 配置文件workerd.capnp为入口向下展开为 Servicesworker/网络/磁盘/外部端点、SocketsHTTP/HTTPS 监听与 Extensions全局能力。本文聚焦其中的运行时 API 层即 Worker 代码里能调用的所有入口与接口。二、Worker 代码模型JS/TS2.1 ES Modules推荐入口Workerd 的 Worker 代码推荐使用 ES Modules 语法通过export default导出多个具名处理器每个处理器对应一种运行时事件。以下示例完整覆盖了全部入口api.md 原文export default { async fetch(request, env, ctx) { const value await env.KV.get(key); // Bindings in env const response await env.API.fetch(request); // Service binding ctx.waitUntil(logRequest(request)); // Background task return new Response(OK); }, async adminApi(request, env, ctx) { /* Named entrypoint */ }, async queue(batch, env, ctx) { /* Queue consumer */ }, async scheduled(event, env, ctx) { /* Cron handler */ } };逐行拆解这段代码就能理解 Workerd 运行时的核心参数约定fetch(request, env, ctx)HTTP 请求入口是绝大多数 Worker 的主入口。request是标准Request对象env承载所有绑定KV、R2、服务绑定、环境变量等ctx是ExecutionContext提供waitUntil()用于后台任务、passThroughOnException()用于异常时回源。env.KV.get(key)ES Modules 模式下所有绑定都挂在env上。这里的KV是在 workerd 配置capnp 或 wrangler 配置中声明的绑定名代码中通过env.绑定名访问。而旧式 Service Worker 语法中绑定则作为全局变量存在见 2.3。env.API.fetch(request)服务绑定Service Binding。它让当前 Worker 能以本地调用的性能把请求转发给另一个 Worker 服务是纳米服务架构的关键。ctx.waitUntil(logRequest(request))把异步后台任务挂到请求生命周期上响应返回后任务继续执行不会阻塞响应——适合埋点、日志、缓存预热等场景。adminApi具名入口Named Entrypoint。一个 Worker 可以导出多个入口外部服务绑定可以通过entrypoint指定调用哪一个配置方式见configuration.md 的服务绑定小节。queue(batch, env, ctx)队列消费者入口处理 Cloudflare Queues 投递的消息批次。scheduled(event, env, ctx)定时任务Cron入口由调度事件触发。2.2 TypeScript 类型生成与手写Workerd/Workers 生态强烈推荐为env定义类型以获得完整的 IDE 提示与编译期检查。文档给出了两条路径路径一由wrangler.toml自动生成推荐wrangler types # Output: worker-configuration.d.ts该命令读取 wrangler 配置文件中的绑定声明生成worker-configuration.d.ts。绑定变更后重新执行即可同步类型。关于类型生成的完整工作流含安装 wrangler、查看生成结果等可参考 bindings/api.md。路径二手动声明Env接口interface Env { API: Fetcher; CACHE: KVNamespace; STORAGE: R2Bucket; ROOMS: DurableObjectNamespace; API_KEY: string; } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { return new Response(await env.CACHE.get(key)); } };注意不同类型绑定对应不同的 TS 类型服务绑定是FetcherKV 是KVNamespaceR2 是R2BucketDurable Object 是DurableObjectNamespace普通字符串变量如API_KEY直接是string。环境搭建两者都需要npm install -D cloudflare/workers-types// tsconfig.json {compilerOptions: {types: [cloudflare/workers-types]}}安装cloudflare/workers-types并提供标准 Workers API 类型Request、Response、ExecutionContext等wrangler types则补充你项目特有的绑定类型。运行时类型与构建期类型的分工可参考 bindings/api.md 的类型来源表。2.3 Service Worker 语法旧式在 ES Modules 普及之前Worker 使用 Service Worker 风格通过addEventListener注册fetch事件绑定直接作为全局变量访问addEventListener(fetch, event { event.respondWith(handleRequest(event.request)); }); async function handleRequest(request) { const value await KV.get(key); // Bindings as globals return new Response(OK); }这段代码展示了两个关键差异事件回调里必须调用event.respondWith()交出响应权且KV无需经过env直接是全局对象。文档与patterns.md 最佳实践均明确建议优先使用 ES Modules旧式语法仅用于维护遗留代码。2.4 Durable Objects有状态对象Durable ObjectsDO是 Workerd 提供的单实例有状态对象适合需要强一致状态、协调、实时场景。每个 DO 是一个导出类构造器接收state含持久化存储state.storage与envexport class Room { constructor(state, env) { this.state state; this.env env; } async fetch(request) { const url new URL(request.url); if (url.pathname /increment) { const value (await this.state.storage.get(counter)) || 0; await this.state.storage.put(counter, value 1); return new Response(String(value 1)); } return new Response(Not found, {status: 404}); } }state.storage.get/put提供持久化的键值存储自动保证同一时刻同一 DO 实例只处理一个请求避免并发写冲突。DO 的实例通过fetch()方法对外提供 HTTP 语义接口调用方用env.ROOMS.idFromName(...)get(id)获取 stub 后调用详见 bindings/api.md 的 Durable Objects 调用示例。要在 workerd 配置中启用 DO需要同时声明绑定durableObjectNamespace、命名空间durableObjectNamespaces与存储位置durableObjectStorage完整配置见configuration.md 的 DO 小节。2.5 服务间 RPC直接方法调用除了通过fetch()转发请求服务绑定还支持结构化 RPC——直接调用另一个服务的导出方法并拿到返回数据无需序列化成 HTTP// Caller: env.AUTH.validateToken(token) returns structured data const user await env.AUTH.validateToken(request.headers.get(Authorization)); // Callee: export methods that return data export default { async validateToken(token) { return {id: 123, name: Alice}; } };调用方把AUTH绑定当作一个本地对象直接调用方法validateToken返回的{id, name}对象会作为结构化数据传回调用方。这是纳米服务架构的核心开发体验服务之间以本地函数调用的方式协作同时保留进程/隔离边界。三、Web 平台 API 全景Workerd 实现了与浏览器/Cloudflare Workers 对齐的 Web 平台 API 子集开发者可直接复用 Web 生态的既有知识。文档将其分为以下几组API 分组包含接口典型用途Fetchfetch()、Request、Response、Headers发起到源站的子请求、构造响应StreamsReadableStream、WritableStream、TransformStream含字节流与 BYOB reader流式处理请求/响应体Web Cryptocrypto.subtleencrypt/decrypt/sign/verify、crypto.randomUUID()、crypto.getRandomValues()加密、签名、生成 UUIDEncodingTextEncoder、TextDecoder、atob()、btoa()文本与二进制互转Web StandardsURL、URLSearchParams、Blob、File、FormData、WebSocketURL 解析、表单处理、实时双向通信3.1 服务端事件流SSESSE 是单向服务器推送的标准方案。workerd 中可以利用TransformStream构造一个流式响应体配合text/event-stream内容类型即可// Server-side SSE const { readable, writable } new TransformStream(); const writer writable.getWriter(); writer.write(new TextEncoder().encode(data: Hello\n\n)); return new Response(readable, {headers: {Content-Type: text/event-stream}});注意 SSE 事件格式每行以data:开头事件之间以空行\n\n分隔。Response可以直接接收一个ReadableStream作为 body这是流式接口互通性的直接体现。3.2 HTMLRewriterHTML 解析与转换HTMLRewriter 是 Cloudflare 生态特有的流式 HTML 重写器允许你像用 jQuery 选择器一样对 HTML 元素做变换且以流式处理、开销极低。文档示例展示了链接改写 脚本移除的组合用法const response await fetch(https://example.com); return new HTMLRewriter() .on(a[href], { element(el) { el.setAttribute(href, /proxy?url${encodeURIComponent(el.getAttribute(href))}); } }) .on(script, { element(el) { el.remove(); } }) .transform(response);.on(selector, handlers)注册元素处理器element(el)回调中可读写属性、增删内容。典型场景包括 A/B 测试注入、分析脚本注入、链接重写HTTPS 升级、代理包装、敏感脚本移除等详见 workers/api.md 的 HTMLRewriter 小节。3.3 TCP Sockets实验性connect()提供原始 TCP 能力可绕过 HTTP 层直接与任意主机通信。文档给出一个极简的手工 HTTP GET示例const socket await connect({ hostname: example.com, port: 80 }); const writer socket.writable.getWriter(); await writer.write(new TextEncoder().encode(GET / HTTP/1.1\r\n\r\n)); const reader socket.readable.getReader(); const { value } await reader.read(); return new Response(value);socket.writable/socket.readable复用了 Streams 标准接口写入请求、读取响应。需注意该能力在文档中标注为Experimental正式使用前应确认当前 compatibility date 下的可用性。3.4 Performance 与 Consoleperformance.now()、performance.timeOrigin精确计时与基准测试。setTimeout()、setInterval()、queueMicrotask()定时与微任务调度。console.log()、console.error()、console.warn()结构化日志配合 workerd 的--verbose与logging配置输出到标准输出/错误流见configuration.md 日志小节。3.5 Node.js 兼容nodejs_compatflagWorkerd 提供了 Node.js 兼容层通过 compatibility flag 开启后即可import部分node:模块import { Buffer } from node:buffer; import { randomBytes } from node:crypto; const buf Buffer.from(Hello); const random randomBytes(16);可用模块node:buffer、node:crypto、node:stream、node:util、node:events、node:assert、node:path、node:querystring、node:url。不可用模块涉及文件系统与网络服务端node:fs、node:http、node:net、node:child_process。这一点与 workerd 的安全模型一致Worker 是无文件系统、无任意网络监听的运行时需要文件或服务端能力时应改用 KV/R2/外部服务绑定。开启方式是在 capnp 配置的compatibilityFlags中加入nodejs_compat见configuration.md 兼容性小节。四、CLI 命令workerd 提供四个核心 CLI 子命令api.md 原文workerd serve config.capnp [constantName] # Start server workerd serve config.capnp --socket-addr http*:3000 --verbose workerd compile config.capnp constantName -o binary # Compile to binary workerd test config.capnp [--test-onlytest.js] # Run tests逐个说明workerd serve按 capnp 配置文件启动服务器。constantName是配置文件中定义的 Config 常量名省略时取默认--socket-addr http*:3000覆盖某个 socket 的监听地址*:3000表示监听所有网卡的 3000 端口--verbose输出详细日志便于排错。workerd compile把配置与嵌入的模块编译为单一二进制-o binary指定输出路径。编译产物可直接执行启动更快、部署更简单生产部署首选详见 patterns.md 的生产部署小节。workerd test运行配置中声明的测试模块--test-onlytest.js指定只跑某个测试文件。测试文件必须出现在配置的modules [...]中。配套的校验手段capnp compile -I. config.capnp可对配置文件做语法与 schema 校验见 gotchas.md 的构建问题systemd 场景下还可用--socket-fd配合 socket 激活见 patterns.md 的 systemd 示例。五、Wrangler 集成与开发工作流对绝大多数开发者日常开发不应直接操作 workerd 二进制而是通过 Wranglerwrangler dev # Uses workerd internally wrangler types # Generate TypeScript types from wrangler.tomlwrangler dev内部启动 workerd 作为本地运行时提供热重载与自动配置读取是本地开发的首选。wrangler types与 2.2 节衔接从 wrangler 配置生成类型定义。wrangler deploy则将同一份代码部署到 Cloudflare 生产环境。在使用任何部署命令wrangler deploy、wrangler pages deploy、npm run deploy之前SKILL.md 的认证章节 要求先执行npx wrangler whoami确认已登录CI/CD 场景通过CLOUDFLARE_API_TOKEN环境变量认证。若你需要绕过 HTTP 层做测试或嵌入Wrangler 还提供了 Node.js 编程接口startWorker以真实本地绑定启动 Worker 做集成测试getPlatformProxy在 Node.js 中直接模拟绑定做单元测试详见 wrangler/api.md而 miniflare 则是在 workerd 沙箱上实现的本地模拟器无需联网即可测试 KV、DO、R2、D1、WebSocket、Queues 等完整能力。六、绑定如何进入env与配置文件的衔接API 文档中的env.KV、env.API、env.CACHE等绑定名并非凭空而来而是由 workerd 的 capnp 配置声明。理解这一层才能把 2.1 节的代码真正跑起来。下面是一个最小化的完整配置configuration.md 基础结构using Workerd import /workerd/workerd.capnp; const config :Workerd.Config ( services [(name main, worker .mainWorker)], sockets [(name http, address *:8080, http (), service main)] ); const mainWorker :Workerd.Worker ( modules [(name index.js, esModule embed src/index.js)], compatibilityDate 2024-01-15, bindings [...] );其中bindings决定env上有哪些键基本类型(name API_KEY, text secret)映射为env.API_KEY字符串json会解析为对象data为ArrayBufferfromEnvironment从系统环境变量取值。服务绑定(name AUTH, service auth-worker)映射为env.AUTHFetcher可配合entrypoint指向具名入口props注入ctx.props。存储绑定kvNamespace→KVNamespace、r2Bucket→R2Bucket、durableObjectNamespace→DurableObjectNamespace、memoryCache提供进程内缓存可设maxKeys/maxValueSize上限。其他queue→ 队列、analyticsEngine→ 分析、cryptoKey→ 密钥绑定、wrapped→ 包装绑定。因此调试绑定找不到类错误时按 gotchas.md 的排查步骤 在代码里打印Object.keys(env)即可核对配置名与代码访问名是否一致。开发阶段还可以通过Remote Bindings让本地 workerd 直连生产环境的 KV/R2/DO 资源需要accountId、namespaceId/bucketName/scriptName与 API Token见 configuration.md 远程绑定章节。七、编写 Worker 代码的最佳实践与常见陷阱结合 patterns.md 的最佳实践清单 与 gotchas.md 的排错指南与 API 层直接相关的要点如下优先 ES Modules 而非 Service Worker 语法绑定显式挂在env上类型安全且职责清晰避免全局命名空间污染。永远设置compatibilityDate这是 workerd 的功能门控。缺失会直接报 Missing compatibility date日期决定哪些 API 可用升级日期前务必先本地测试。后台任务用ctx.waitUntil()绝不await阻塞把日志、埋点等放到waitUntil中响应即刻返回workers/api.md 亦强调此点。错误处理用 try/catch 包裹捕获后记录console.error并返回 5xx避免未处理异常导致请求失败export default { async fetch(request, env, ctx) { try { return await handleRequest(request, env); } catch (error) { console.error(Request failed, error); return new Response(Internal Error, {status: 500}); } } };绑定类型别混用DO 必须用durableObjectNamespace而非serviceJSON 要用json 而非text 后者只是字符串不会解析。模块名与导入路径必须一致配置中name index.js使用简单名embed用相对路径嵌入二者不要混写成name src/index.js。安全基线密钥用fromEnvironment从环境变量注入而非硬编码在text绑定网络访问收敛为allow [public]或指定主机避免*crypto 密钥默认extractable false。生产部署前把配置编译为二进制workerd compile并固定 workerd 版本与 compatibility date 的匹配关系。八、延伸阅读workerd/configuration.mdcapnp 配置语法、services/sockets/bindings 全量字段、远程绑定与参数继承。workerd/patterns.md多服务架构、反向代理、Hono/itty-router 框架集成、Docker/systemd 部署。workerd/gotchas.md常见错误、性能问题、安全与兼容性陷阱的排查手册。workers/api.mdWorkers 运行时 API 补充Cache API、WebSocket Hibernation、D1 Session 等。bindings/api.md绑定类型对照表与类型生成工作流。miniflare/README.md 与 wrangler/api.md本地测试与编程式启动 Worker 的方案。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考