Cloudflare Containers 容器类 API 完整指南路由、启动、通信与生命周期钩子实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以 Cloudflare Containers 的Container 类 API为核心系统讲解容器 Worker 的类属性配置、getByName()/getRandom()路由模型、start()/startAndWaitForPorts()启动方法、fetch()/containerFetch()/TCP 通信方式以及onStart/onStop/onError/onActivityExpired生命周期钩子、定时调度与状态检查等完整 API 面。读完本文你将能直接上手编写、部署并调试一个运行在 Cloudflare Workers 平台上的容器化应用并避开 WebSocket 静默失败、端口未就绪、活动超时等高频坑点。本文依据仓库中 containers/api.md 及同目录下的配套参考文档展开并结合 Durable Objects API 进行源码级佐证。前置说明Cloudflare Containers 目前处于beta阶段见 containers/README.mdAPI 可能随时变更、无 SLA 保证、初始仅限部分区域自定义实例类型于 2026 年 1 月新增。编写代码时请为 API 变化预留迁移空间并在生产环境前充分测试。一、Container 类全景属性、绑定与生命周期模型1.1 最小容器类骨架每个容器都是一个继承自cloudflare/containers包中Container基类的导出类。以下代码是 api.md 给出的完整类骨架包含全部可配置属性与可覆写生命周期方法import { Container } from cloudflare/containers; export class MyContainer extends Container { defaultPort 8080; // fetch() 使用的默认端口 requiredPorts [8080]; // startAndWaitForPorts() 等待就绪的端口列表 sleepAfter 30m; // 无活动自动休眠超时 enableInternet true; // 是否允许出站网络访问 pingEndpoint /health; // 健康检查端点路径 envVars {}; // 注入容器的环境变量 entrypoint []; // 覆盖镜像默认入口命令可选 onStart() { /* 容器进程已启动 */ } onStop() { /* 容器即将停止 */ } onError(error: Error) { /* 容器出错 */ } onActivityExpired(): boolean { /* 超时回调返回 true 保持存活 */ } async alarm() { /* 定时任务 */ } }1.2 类属性逐一详解结合 containers/configuration.md 中对属性的官方说明各属性的行为如下属性类型/示例行为说明defaultPort8080调用container.fetch()且未显式指定端口时使用的端口未设置时回退到端口 33requiredPorts[8080, 9090]startAndWaitForPorts()返回前必须处于监听状态的端口数组若未设置defaultPort数组首端口将作为默认端口sleepAfter5m、30m、2h无活动后的休眠超时时长字符串每次请求都会重置该计时器enableInternettrue布尔值为true时容器可发起出站 HTTP/TCP 请求pingEndpoint/health健康检查使用的路径应返回 2xx 状态码envVars{ NODE_ENV: production }注入容器的环境变量对象与运行时提供变量合并entrypoint[/bin/start.sh]字符串数组覆写镜像的 CMD/ENTRYPOINT可选1.3 运行时自动注入的环境变量除自定义envVars外Cloudflare 会自动向容器注入以下变量来自 containers/configuration.md变量说明CLOUDFLARE_APPLICATION_IDWorker 应用 IDCLOUDFLARE_COUNTRY_A2请求来源的两字母国家代码CLOUDFLARE_LOCATIONCloudflare 数据中心位置CLOUDFLARE_REGION区域标识符CLOUDFLARE_DURABLE_OBJECT_ID容器的 Durable Object ID自定义envVars与这些运行时变量合并若命名冲突自定义变量优先。1.4 容器即 Durable Object理解 Container API 的关键前提见 containers/README.md 的 Core Concepts每个容器都是一个具有持久身份的 Durable Object通过getByName(id)或getRandom()访问。这意味着容器的核心行为继承自 Durable Object 语义——例如this.ctxDurable Object 状态上下文提供的blockConcurrencyWhile()、存储访问等能力都可用详见 durable-objects/api.md。部署层面有三个核心特征必须牢记镜像预取镜像会在部署前预取到全球所有位置因此典型冷启动仅需 2~3 秒滚动部署与 Workers 的即时生效不同容器部署采用滚动策略旧版本会在新版本上线过程中继续运行持久身份、临时磁盘容器 ID 持久保留但磁盘在停止时重置持久化数据必须使用 Durable Object 存储this.ctx.storage。1.5 Wrangler 配置要点要在wrangler.jsonc或wrangler.toml中启用容器必须同时配置containers数组、Durable Objects 绑定与迁移迁移必须使用new_sqlite_classes详见 containers/configuration.md{ name: my-worker, main: src/index.ts, compatibility_date: 2026-01-10, containers: [ { class_name: MyContainer, // 必须与导出的 Container 类名一致 image: ./Dockerfile, // Dockerfile 路径或含 Dockerfile 的目录 instance_type: standard-1, // 预定义或自定义实例类型 max_instances: 10 // 最大并发容器实例数 } ], durable_objects: { bindings: [ { name: MY_CONTAINER, class_name: MyContainer } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyContainer] } ] }常用实例类型见下表另有instance_type_custom可自定义 1~4 vCPU、512~12288 MiB 内存、2048~20480 MiB 磁盘约束为每 vCPU 至少 3 GiB 内存、每 1 GiB 内存至多 2 GB 磁盘类型vCPU内存磁盘lite1/16256 MiB2 GBbasic1/41 GiB4 GBstandard-11/24 GiB8 GBstandard-216 GiB12 GBstandard-328 GiB16 GBstandard-4412 GiB20 GB二、路由模型getByName()与getRandom()容器作为 Durable Object通过绑定对象的两个方法路由到具体实例见 api.md 的 Routing 小节getByName(id)—— 按名称取具名实例用于会话亲和session affinity、按用户隔离状态例如env.MY_CONTAINER.getByName(user-123)getRandom()—— 取随机实例用于无状态服务的负载均衡例如env.MY_CONTAINER.getRandom()。const container env.MY_CONTAINER.getByName(user-123); const container env.MY_CONTAINER.getRandom();containers/README.md 给出了路由决策树可据此选择策略同一用户/会话 → 同一容器getByName(sessionId)会话亲和无状态、需分摊负载getRandom()负载均衡每个任务一个容器getByName(jobId) 显式生命周期管理全局单实例getByName(singleton)。注意容器不支持自动伸缩负载均衡需通过getRandom()手动实现见 containers/gotchas.md 的 Beta Caveats。三、启动方法start()、startAndWaitForPorts()与waitForPort()3.1start()—— 基础启动8 秒超时start()在进程启动时即返回而非端口就绪时。适合 fire-and-forget 场景await container.start(); await container.start({ envVars: { KEY: value } });⚠️ 若在start()后立即发起请求极可能遇到 connection refused——因为此时进程已启动但端口尚未监听。这正是 containers/gotchas.md 中 startAndWaitForPorts() vs start() 一节强调的坑。3.2startAndWaitForPorts()—— 推荐方式20 秒超时startAndWaitForPorts()在端口开始监听后才返回因此是所有 HTTP/TCP 请求前的首选启动方式await container.startAndWaitForPorts(); // 使用 requiredPorts await container.startAndWaitForPorts({ ports: [8080, 9090] }); await container.startAndWaitForPorts({ ports: [8080], startOptions: { envVars: { KEY: value } } });端口解析优先级来自 api.md显式传入的 ports → requiredPorts → defaultPort → 端口 33即显式传入的ports优先未传时按requiredPorts→defaultPort→ 33 的次序取默认端口。3.3waitForPort()—— 等待指定端口若已启动但需要等待某个特定端口就绪可单独使用await container.waitForPort(8080); await container.waitForPort(8080, { timeout: 30000 }); // 30 秒超时四、通信方式fetch()、containerFetch()、TCP 与switchPort()4.1fetch()—— 支持 WebSocket 升级推荐fetch()支持完整 HTTP 语义并支持 WebSocket 升级可传入Request对象或 URL 字符串// ✅ 支持 WebSocket 升级 const response await container.fetch(request); const response await container.fetch(http://container/api, { method: POST, body: JSON.stringify({ data: value }) });4.2containerFetch()—— 仅 HTTP不支持 WebSocket// ❌ 不支持 WebSocket const response await container.containerFetch(request);⚠️ 关键警告api.md 与 containers/gotchas.md 反复强调containerFetch()不支持 WebSocket 升级用它转发 WebSocket 请求会导致静默失败连接建立失败且无报错。任何 WebSocket 场景一律使用fetch()// ❌ WRONG return container.containerFetch(request); // ✅ CORRECT return container.fetch(request);4.3 TCP 直连容器通过ctx.container.getTcpPort()获得 TCP 端口对象再建立连接并做流式双向转发const port this.ctx.container.getTcpPort(8080); const conn port.connect(); await conn.opened; if (request.body) await request.body.pipeTo(conn.writable); return new Response(conn.readable);该模式适合非 HTTP 协议gRPC、数据库协议等的双向流透传。4.4switchPort()—— 切换默认端口switchPort()会改变后续fetch()所使用的默认端口适合多协议/多端口路由this.switchPort(8081); // 后续 fetch() 使用该端口containers/patterns.md 中的多端口路由示例展示了其典型用法按请求路径分发到不同端口如/grpc→ 8081、/metrics→ 9090。五、生命周期钩子onStart、onStop、onError、onActivityExpired所有生命周期钩子都在blockConcurrencyWhile中执行见 api.md期间不处理任何并发请求——因此钩子必须保持轻量、避免长时间操作否则容器会表现为无响应详见 containers/gotchas.md 的 Lifecycle Hooks Block Requests。5.1onStart()—— 容器进程启动时进程启动时调用此时端口可能尚未就绪运行在blockConcurrencyWhile中期间无并发请求onStart() { console.log(Container starting); }5.2onStop()—— 收到 SIGTERM 时收到 SIGTERM 时调用距 SIGKILL 强制终止有 15 分钟宽限期用于优雅关闭onStop() { // 保存状态、关闭连接、冲刷日志 }containers/patterns.md 的优雅关闭示例会在onStop()中主动关闭所有 WebSocket 连接并写入关闭时间戳同时配合onActivityExpired()在有存活连接时拒绝休眠。5.3onError()—— 崩溃或启动失败时容器崩溃或启动失败时调用onError(error: Error) { console.error(Container error:, error); }5.4onActivityExpired()——sleepAfter超时时达到sleepAfter超时阈值时调用返回true保持存活返回false允许停止onActivityExpired(): boolean { if (this.hasActiveConnections()) return true; // 保持存活 return false; // 允许停止 }典型用法是结合 WebSocket 连接集合做有连接则不睡的判断。六、定时调度schedule()与alarm()容器类支持基于 Durable Object Alarm 的定时任务见 api.md 的 Scheduling 小节。schedule()是封装的调度助手alarm()是调度触发时的回调export class ScheduledContainer extends Container { async fetch(request: Request) { await this.schedule(Date.now() 60000); // 1 分钟后 await this.schedule(2026-01-28T00:00:00Z); // 绝对 ISO 时间 return new Response(Scheduled); } async alarm() { // 调度触发时调用SQLite 支撑重启后依然生效 } }⚠️ 关键警告使用schedule()助手时不要直接覆写alarm()的实现逻辑来绕过它——因为schedule()内部正是通过 alarm 机制实现的见 containers/gotchas.md 的 Dont Override alarm() When Using schedule()。正确的做法是用schedule()设定时间点用alarm()处理到期的任务。七、状态检查getState()与ctx.container.running7.1 外部状态检查 ——getState()从 Worker 侧容器外部查询状态const state await container.getState(); // state.status: starting | running | stopping | stopped状态机取值与 README 描述的生命周期冷启动 → running →sleepAfter超时 → stopped一致。7.2 内部状态检查 ——ctx.container.running在容器类内部用上下文判断export class MyContainer extends Container { async fetch(request: Request) { if (this.ctx.container.running) { /* 容器正在运行 */ } } }⚠️ 使用边界外部检查用getState()内部检查用ctx.container.running二者不可互换。八、实战模式与最佳实践8.1 路由与 WebSocket 转发模式以下三个高频模式均来自 containers/patterns.md可直接落地会话亲和有状态——用户会话、WebSocket、有状态游戏、按用户缓存export class SessionBackend extends Container { defaultPort 3000; sleepAfter 30m; } export default { async fetch(request: Request, env: Env) { const sessionId request.headers.get(X-Session-ID) || crypto.randomUUID(); const container env.SESSION_BACKEND.getByName(sessionId); await container.startAndWaitForPorts(); return container.fetch(request); } };WebSocket 转发——必须先startAndWaitForPorts()再必须用fetch()而非containerFetch()export default { async fetch(request: Request, env: Env) { if (request.headers.get(Upgrade) websocket) { const sessionId request.headers.get(X-Session-ID) || crypto.randomUUID(); const container env.WS_BACKEND.getByName(sessionId); await container.startAndWaitForPorts(); return container.fetch(request); // ⚠️ MUST use fetch(), not containerFetch() } return new Response(Not a WebSocket request, { status: 400 }); } };并发安全启动——用blockConcurrencyWhile防止并发初始化竞态这正是 containers/gotchas.md 中 blockConcurrencyWhile for Startup 一节的解法export class SafeContainer extends Container { private initialized false; async fetch(request: Request) { await this.ctx.blockConcurrencyWhile(async () { if (!this.initialized) { await this.startAndWaitForPorts(); this.initialized true; } }); return super.fetch(request); } }8.2 长任务活动超时续期sleepAfter基于请求活动而非内部工作计时。长任务期间容器可能被休眠解法是周期性触碰存储来续期详见 containers/gotchas.mdexport class LongRunningContainer extends Container { sleepAfter 5m; async processLongJob(data: unknown) { const interval setInterval(() { this.ctx.storage.put(keepalive, Date.now()); }, 60000); try { await this.doLongWork(data); } finally { clearInterval(interval); } } }8.3 与 Workflow、Queue 集成容器可以无缝接入 Cloudflare Workflows 做多步骤编排containers/patterns.mdimport { WorkflowEntrypoint } from cloudflare:workers; export class ProcessingWorkflow extends WorkflowEntrypoint { async run(event, step) { const container this.env.PROCESSOR.getByName(event.payload.jobId); await step.do(start, async () { await container.startAndWaitForPorts(); }); const result await step.do(process, async () { return container.fetch(/process, { method: POST, body: JSON.stringify(event.payload.data) }).then(r r.json()); }); return result; } }也可作为 Queue 消费者处理异步任务按msg.ack()/msg.retry()控制消息结果。8.4 高频报错排查速查以下错误及解法整理自 containers/gotchas.md 的 Common Errors 一节错误原因解法Container start timeoutstart()超 8s /startAndWaitForPorts()超 20s优化镜像更小基础镜像、更少层核对entrypoint确认应用监听正确端口必要时增大超时Port not available端口就绪前就调用了fetch()改用startAndWaitForPorts()Container memory exceeded内存超过实例类型上限换更大实例类型standard-2/3/4或自定义instance_type_custom优化内存占用Max instances reachedmax_instances槽位占满调大max_instances设置合理sleepAfter用getRandom()分摊排查实例泄漏No container instance available达到账户容量上限检查账户限额复核各容器实例类型联系 Cloudflare 支持8.5 最佳实践清单按 containers/gotchas.md 的 Best Practices 汇总默认使用startAndWaitForPorts()—— 杜绝端口错误设置合理的sleepAfter—— 在资源占用与冷启动之间取得平衡WebSocket 用fetch()—— 绝不用containerFetch()为重启而设计—— 磁盘是临时的实现优雅关闭监控资源—— 保持在账户限额内全账户总计400 GiB 内存 / 100 vCPU / 2 TB 磁盘镜像存储每账户 50 GB保持钩子轻量—— 它们运行在blockConcurrencyWhile中长任务续期活动—— 周期性写存储防止超时休眠。九、小结Container 类 API 的要点可以浓缩为一句话心法路由选实例getByName/getRandom、启动等端口startAndWaitForPorts、WebSocket 走fetch()、状态持久用 DO 存储、钩子务必轻量。配合 containers/configuration.md 完成 Wrangler 配置、containers/patterns.md 挑选路由模式、containers/gotchas.md 排查故障即可在 beta 阶段稳定落地容器化应用。由于容器本质是 Durable Object其底层并发与存储语义可继续深入 durable-objects/api.md 研读。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Containers 容器类 API 完整指南：路由、启动、通信与生命周期钩子实战
Cloudflare Containers 容器类 API 完整指南路由、启动、通信与生命周期钩子实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以 Cloudflare Containers 的Container 类 API为核心系统讲解容器 Worker 的类属性配置、getByName()/getRandom()路由模型、start()/startAndWaitForPorts()启动方法、fetch()/containerFetch()/TCP 通信方式以及onStart/onStop/onError/onActivityExpired生命周期钩子、定时调度与状态检查等完整 API 面。读完本文你将能直接上手编写、部署并调试一个运行在 Cloudflare Workers 平台上的容器化应用并避开 WebSocket 静默失败、端口未就绪、活动超时等高频坑点。本文依据仓库中 containers/api.md 及同目录下的配套参考文档展开并结合 Durable Objects API 进行源码级佐证。前置说明Cloudflare Containers 目前处于beta阶段见 containers/README.mdAPI 可能随时变更、无 SLA 保证、初始仅限部分区域自定义实例类型于 2026 年 1 月新增。编写代码时请为 API 变化预留迁移空间并在生产环境前充分测试。一、Container 类全景属性、绑定与生命周期模型1.1 最小容器类骨架每个容器都是一个继承自cloudflare/containers包中Container基类的导出类。以下代码是 api.md 给出的完整类骨架包含全部可配置属性与可覆写生命周期方法import { Container } from cloudflare/containers; export class MyContainer extends Container { defaultPort 8080; // fetch() 使用的默认端口 requiredPorts [8080]; // startAndWaitForPorts() 等待就绪的端口列表 sleepAfter 30m; // 无活动自动休眠超时 enableInternet true; // 是否允许出站网络访问 pingEndpoint /health; // 健康检查端点路径 envVars {}; // 注入容器的环境变量 entrypoint []; // 覆盖镜像默认入口命令可选 onStart() { /* 容器进程已启动 */ } onStop() { /* 容器即将停止 */ } onError(error: Error) { /* 容器出错 */ } onActivityExpired(): boolean { /* 超时回调返回 true 保持存活 */ } async alarm() { /* 定时任务 */ } }1.2 类属性逐一详解结合 containers/configuration.md 中对属性的官方说明各属性的行为如下属性类型/示例行为说明defaultPort8080调用container.fetch()且未显式指定端口时使用的端口未设置时回退到端口 33requiredPorts[8080, 9090]startAndWaitForPorts()返回前必须处于监听状态的端口数组若未设置defaultPort数组首端口将作为默认端口sleepAfter5m、30m、2h无活动后的休眠超时时长字符串每次请求都会重置该计时器enableInternettrue布尔值为true时容器可发起出站 HTTP/TCP 请求pingEndpoint/health健康检查使用的路径应返回 2xx 状态码envVars{ NODE_ENV: production }注入容器的环境变量对象与运行时提供变量合并entrypoint[/bin/start.sh]字符串数组覆写镜像的 CMD/ENTRYPOINT可选1.3 运行时自动注入的环境变量除自定义envVars外Cloudflare 会自动向容器注入以下变量来自 containers/configuration.md变量说明CLOUDFLARE_APPLICATION_IDWorker 应用 IDCLOUDFLARE_COUNTRY_A2请求来源的两字母国家代码CLOUDFLARE_LOCATIONCloudflare 数据中心位置CLOUDFLARE_REGION区域标识符CLOUDFLARE_DURABLE_OBJECT_ID容器的 Durable Object ID自定义envVars与这些运行时变量合并若命名冲突自定义变量优先。1.4 容器即 Durable Object理解 Container API 的关键前提见 containers/README.md 的 Core Concepts每个容器都是一个具有持久身份的 Durable Object通过getByName(id)或getRandom()访问。这意味着容器的核心行为继承自 Durable Object 语义——例如this.ctxDurable Object 状态上下文提供的blockConcurrencyWhile()、存储访问等能力都可用详见 durable-objects/api.md。部署层面有三个核心特征必须牢记镜像预取镜像会在部署前预取到全球所有位置因此典型冷启动仅需 2~3 秒滚动部署与 Workers 的即时生效不同容器部署采用滚动策略旧版本会在新版本上线过程中继续运行持久身份、临时磁盘容器 ID 持久保留但磁盘在停止时重置持久化数据必须使用 Durable Object 存储this.ctx.storage。1.5 Wrangler 配置要点要在wrangler.jsonc或wrangler.toml中启用容器必须同时配置containers数组、Durable Objects 绑定与迁移迁移必须使用new_sqlite_classes详见 containers/configuration.md{ name: my-worker, main: src/index.ts, compatibility_date: 2026-01-10, containers: [ { class_name: MyContainer, // 必须与导出的 Container 类名一致 image: ./Dockerfile, // Dockerfile 路径或含 Dockerfile 的目录 instance_type: standard-1, // 预定义或自定义实例类型 max_instances: 10 // 最大并发容器实例数 } ], durable_objects: { bindings: [ { name: MY_CONTAINER, class_name: MyContainer } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyContainer] } ] }常用实例类型见下表另有instance_type_custom可自定义 1~4 vCPU、512~12288 MiB 内存、2048~20480 MiB 磁盘约束为每 vCPU 至少 3 GiB 内存、每 1 GiB 内存至多 2 GB 磁盘类型vCPU内存磁盘lite1/16256 MiB2 GBbasic1/41 GiB4 GBstandard-11/24 GiB8 GBstandard-216 GiB12 GBstandard-328 GiB16 GBstandard-4412 GiB20 GB二、路由模型getByName()与getRandom()容器作为 Durable Object通过绑定对象的两个方法路由到具体实例见 api.md 的 Routing 小节getByName(id)—— 按名称取具名实例用于会话亲和session affinity、按用户隔离状态例如env.MY_CONTAINER.getByName(user-123)getRandom()—— 取随机实例用于无状态服务的负载均衡例如env.MY_CONTAINER.getRandom()。const container env.MY_CONTAINER.getByName(user-123); const container env.MY_CONTAINER.getRandom();containers/README.md 给出了路由决策树可据此选择策略同一用户/会话 → 同一容器getByName(sessionId)会话亲和无状态、需分摊负载getRandom()负载均衡每个任务一个容器getByName(jobId) 显式生命周期管理全局单实例getByName(singleton)。注意容器不支持自动伸缩负载均衡需通过getRandom()手动实现见 containers/gotchas.md 的 Beta Caveats。三、启动方法start()、startAndWaitForPorts()与waitForPort()3.1start()—— 基础启动8 秒超时start()在进程启动时即返回而非端口就绪时。适合 fire-and-forget 场景await container.start(); await container.start({ envVars: { KEY: value } });⚠️ 若在start()后立即发起请求极可能遇到 connection refused——因为此时进程已启动但端口尚未监听。这正是 containers/gotchas.md 中 startAndWaitForPorts() vs start() 一节强调的坑。3.2startAndWaitForPorts()—— 推荐方式20 秒超时startAndWaitForPorts()在端口开始监听后才返回因此是所有 HTTP/TCP 请求前的首选启动方式await container.startAndWaitForPorts(); // 使用 requiredPorts await container.startAndWaitForPorts({ ports: [8080, 9090] }); await container.startAndWaitForPorts({ ports: [8080], startOptions: { envVars: { KEY: value } } });端口解析优先级来自 api.md显式传入的 ports → requiredPorts → defaultPort → 端口 33即显式传入的ports优先未传时按requiredPorts→defaultPort→ 33 的次序取默认端口。3.3waitForPort()—— 等待指定端口若已启动但需要等待某个特定端口就绪可单独使用await container.waitForPort(8080); await container.waitForPort(8080, { timeout: 30000 }); // 30 秒超时四、通信方式fetch()、containerFetch()、TCP 与switchPort()4.1fetch()—— 支持 WebSocket 升级推荐fetch()支持完整 HTTP 语义并支持 WebSocket 升级可传入Request对象或 URL 字符串// ✅ 支持 WebSocket 升级 const response await container.fetch(request); const response await container.fetch(http://container/api, { method: POST, body: JSON.stringify({ data: value }) });4.2containerFetch()—— 仅 HTTP不支持 WebSocket// ❌ 不支持 WebSocket const response await container.containerFetch(request);⚠️ 关键警告api.md 与 containers/gotchas.md 反复强调containerFetch()不支持 WebSocket 升级用它转发 WebSocket 请求会导致静默失败连接建立失败且无报错。任何 WebSocket 场景一律使用fetch()// ❌ WRONG return container.containerFetch(request); // ✅ CORRECT return container.fetch(request);4.3 TCP 直连容器通过ctx.container.getTcpPort()获得 TCP 端口对象再建立连接并做流式双向转发const port this.ctx.container.getTcpPort(8080); const conn port.connect(); await conn.opened; if (request.body) await request.body.pipeTo(conn.writable); return new Response(conn.readable);该模式适合非 HTTP 协议gRPC、数据库协议等的双向流透传。4.4switchPort()—— 切换默认端口switchPort()会改变后续fetch()所使用的默认端口适合多协议/多端口路由this.switchPort(8081); // 后续 fetch() 使用该端口containers/patterns.md 中的多端口路由示例展示了其典型用法按请求路径分发到不同端口如/grpc→ 8081、/metrics→ 9090。五、生命周期钩子onStart、onStop、onError、onActivityExpired所有生命周期钩子都在blockConcurrencyWhile中执行见 api.md期间不处理任何并发请求——因此钩子必须保持轻量、避免长时间操作否则容器会表现为无响应详见 containers/gotchas.md 的 Lifecycle Hooks Block Requests。5.1onStart()—— 容器进程启动时进程启动时调用此时端口可能尚未就绪运行在blockConcurrencyWhile中期间无并发请求onStart() { console.log(Container starting); }5.2onStop()—— 收到 SIGTERM 时收到 SIGTERM 时调用距 SIGKILL 强制终止有 15 分钟宽限期用于优雅关闭onStop() { // 保存状态、关闭连接、冲刷日志 }containers/patterns.md 的优雅关闭示例会在onStop()中主动关闭所有 WebSocket 连接并写入关闭时间戳同时配合onActivityExpired()在有存活连接时拒绝休眠。5.3onError()—— 崩溃或启动失败时容器崩溃或启动失败时调用onError(error: Error) { console.error(Container error:, error); }5.4onActivityExpired()——sleepAfter超时时达到sleepAfter超时阈值时调用返回true保持存活返回false允许停止onActivityExpired(): boolean { if (this.hasActiveConnections()) return true; // 保持存活 return false; // 允许停止 }典型用法是结合 WebSocket 连接集合做有连接则不睡的判断。六、定时调度schedule()与alarm()容器类支持基于 Durable Object Alarm 的定时任务见 api.md 的 Scheduling 小节。schedule()是封装的调度助手alarm()是调度触发时的回调export class ScheduledContainer extends Container { async fetch(request: Request) { await this.schedule(Date.now() 60000); // 1 分钟后 await this.schedule(2026-01-28T00:00:00Z); // 绝对 ISO 时间 return new Response(Scheduled); } async alarm() { // 调度触发时调用SQLite 支撑重启后依然生效 } }⚠️ 关键警告使用schedule()助手时不要直接覆写alarm()的实现逻辑来绕过它——因为schedule()内部正是通过 alarm 机制实现的见 containers/gotchas.md 的 Dont Override alarm() When Using schedule()。正确的做法是用schedule()设定时间点用alarm()处理到期的任务。七、状态检查getState()与ctx.container.running7.1 外部状态检查 ——getState()从 Worker 侧容器外部查询状态const state await container.getState(); // state.status: starting | running | stopping | stopped状态机取值与 README 描述的生命周期冷启动 → running →sleepAfter超时 → stopped一致。7.2 内部状态检查 ——ctx.container.running在容器类内部用上下文判断export class MyContainer extends Container { async fetch(request: Request) { if (this.ctx.container.running) { /* 容器正在运行 */ } } }⚠️ 使用边界外部检查用getState()内部检查用ctx.container.running二者不可互换。八、实战模式与最佳实践8.1 路由与 WebSocket 转发模式以下三个高频模式均来自 containers/patterns.md可直接落地会话亲和有状态——用户会话、WebSocket、有状态游戏、按用户缓存export class SessionBackend extends Container { defaultPort 3000; sleepAfter 30m; } export default { async fetch(request: Request, env: Env) { const sessionId request.headers.get(X-Session-ID) || crypto.randomUUID(); const container env.SESSION_BACKEND.getByName(sessionId); await container.startAndWaitForPorts(); return container.fetch(request); } };WebSocket 转发——必须先startAndWaitForPorts()再必须用fetch()而非containerFetch()export default { async fetch(request: Request, env: Env) { if (request.headers.get(Upgrade) websocket) { const sessionId request.headers.get(X-Session-ID) || crypto.randomUUID(); const container env.WS_BACKEND.getByName(sessionId); await container.startAndWaitForPorts(); return container.fetch(request); // ⚠️ MUST use fetch(), not containerFetch() } return new Response(Not a WebSocket request, { status: 400 }); } };并发安全启动——用blockConcurrencyWhile防止并发初始化竞态这正是 containers/gotchas.md 中 blockConcurrencyWhile for Startup 一节的解法export class SafeContainer extends Container { private initialized false; async fetch(request: Request) { await this.ctx.blockConcurrencyWhile(async () { if (!this.initialized) { await this.startAndWaitForPorts(); this.initialized true; } }); return super.fetch(request); } }8.2 长任务活动超时续期sleepAfter基于请求活动而非内部工作计时。长任务期间容器可能被休眠解法是周期性触碰存储来续期详见 containers/gotchas.mdexport class LongRunningContainer extends Container { sleepAfter 5m; async processLongJob(data: unknown) { const interval setInterval(() { this.ctx.storage.put(keepalive, Date.now()); }, 60000); try { await this.doLongWork(data); } finally { clearInterval(interval); } } }8.3 与 Workflow、Queue 集成容器可以无缝接入 Cloudflare Workflows 做多步骤编排containers/patterns.mdimport { WorkflowEntrypoint } from cloudflare:workers; export class ProcessingWorkflow extends WorkflowEntrypoint { async run(event, step) { const container this.env.PROCESSOR.getByName(event.payload.jobId); await step.do(start, async () { await container.startAndWaitForPorts(); }); const result await step.do(process, async () { return container.fetch(/process, { method: POST, body: JSON.stringify(event.payload.data) }).then(r r.json()); }); return result; } }也可作为 Queue 消费者处理异步任务按msg.ack()/msg.retry()控制消息结果。8.4 高频报错排查速查以下错误及解法整理自 containers/gotchas.md 的 Common Errors 一节错误原因解法Container start timeoutstart()超 8s /startAndWaitForPorts()超 20s优化镜像更小基础镜像、更少层核对entrypoint确认应用监听正确端口必要时增大超时Port not available端口就绪前就调用了fetch()改用startAndWaitForPorts()Container memory exceeded内存超过实例类型上限换更大实例类型standard-2/3/4或自定义instance_type_custom优化内存占用Max instances reachedmax_instances槽位占满调大max_instances设置合理sleepAfter用getRandom()分摊排查实例泄漏No container instance available达到账户容量上限检查账户限额复核各容器实例类型联系 Cloudflare 支持8.5 最佳实践清单按 containers/gotchas.md 的 Best Practices 汇总默认使用startAndWaitForPorts()—— 杜绝端口错误设置合理的sleepAfter—— 在资源占用与冷启动之间取得平衡WebSocket 用fetch()—— 绝不用containerFetch()为重启而设计—— 磁盘是临时的实现优雅关闭监控资源—— 保持在账户限额内全账户总计400 GiB 内存 / 100 vCPU / 2 TB 磁盘镜像存储每账户 50 GB保持钩子轻量—— 它们运行在blockConcurrencyWhile中长任务续期活动—— 周期性写存储防止超时休眠。九、小结Container 类 API 的要点可以浓缩为一句话心法路由选实例getByName/getRandom、启动等端口startAndWaitForPorts、WebSocket 走fetch()、状态持久用 DO 存储、钩子务必轻量。配合 containers/configuration.md 完成 Wrangler 配置、containers/patterns.md 挑选路由模式、containers/gotchas.md 排查故障即可在 beta 阶段稳定落地容器化应用。由于容器本质是 Durable Object其底层并发与存储语义可继续深入 durable-objects/api.md 研读。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考