Cloudflare Containers Wrangler 配置完全指南wrangler.jsonc / wrangler.toml、实例类型与 Container 类属性详解【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare Containers 允许你把 Docker 化的现有应用Node.js、Python 或任意自定义二进制直接运行在 Workers 平台上每个容器本质是一个带持久身份的 Durable Object。本文以本仓库 containers 参考文档 为骨架完整讲解 Wrangler 侧的全部配置维度两种配置文件格式、预定义/自定义实例类型、账户级资源上限、Container 类属性、运行时环境变量以及镜像部署模型并补充源码级佐证帮助你一次性配出一个可部署、可运维的容器 Worker 项目。注意Cloudflare Containers 目前处于beta阶段API 可能在没有通知的情况下变更、无 SLA 保证且初始仅支持部分区域。生产使用前务必做好 API 变更预案见 README。核心概念先理解“容器 Durable Object”在动手配置前先建立两个关键认知出自 containers/README.md每个容器都是一个 Durable Object拥有持久身份通过env.BINDING.getByName(id)或env.BINDING.getRandom()访问。因此配置中 Durable Objects 绑定与迁移migrations是必需项而不是可选项。身份持久、磁盘易失容器 ID 在停止后仍保留但磁盘每次停止都会重置。需要持久化的数据必须写入 Durable Object 存储this.ctx.storage这直接决定了后续配置中sleepAfter、镜像管理等设计取向。Wrangler 基本容器配置wrangler.jsonc原文档给出的最小可用配置骨架如下{ name: my-worker, main: src/index.ts, compatibility_date: 2026-01-10, containers: [ { class_name: MyContainer, image: ./Dockerfile, // Path to Dockerfile or directory with Dockerfile instance_type: standard-1, // Predefined or custom (see below) max_instances: 10 } ], durable_objects: { bindings: [ { name: MY_CONTAINER, class_name: MyContainer } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyContainer] // Must use new_sqlite_classes } ] }关键配置项要求配置项作用注意事项imageDockerfile 路径或包含 Dockerfile 的目录路径支持相对路径例如./Dockerfileclass_name容器类名必须与源码中export class MyContainer extends Container的导出名完全一致max_instances该容器允许的最大并发实例数与 api.md 中的getByName(id)/getRandom()配合决定并发上限durable_objects.bindings将容器类绑定为环境变量name是代码里env.MY_CONTAINER中的键名class_name指向容器类migrations声明容器类的持久状态迁移必须使用new_sqlite_classes而非new_classes因为容器作为 Durable Object 使用 SQLite 持久状态两个最容易踩坑的点Durable Objects 绑定与 migrations 缺一不可——缺失任何一个env.MY_CONTAINER都将不可用部署也会失败。migrations 必须用new_sqlite_classes——这是容器场景的强制要求直接沿用普通 Durable Object 的new_classes不会生效。每个迁移需带唯一tag如v1。实例类型配置预定义实例类型原文档提供了 6 种预定义规格直接通过instance_type字段引用TypevCPUMemoryDisklite1/16256 MiB2 GBbasic1/41 GiB4 GBstandard-11/24 GiB8 GBstandard-216 GiB12 GBstandard-328 GiB16 GBstandard-4412 GiB20 GB使用示例{ containers: [ { class_name: MyContainer, image: ./Dockerfile, instance_type: standard-2 // Use predefined type } ] }选择建议lite/basic适合轻量 API有状态会话、WebSocket 或内存敏感任务建议standard-2及以上standard-44 vCPU / 12 GiB / 20 GB是预定义规格中的上限。若应用超出lite的 256 MiB 内存会触发“Container memory exceeded”错误应改用更大规格或自定义实例类型见下节错误处理细节见 gotchas.md。自定义实例类型2026 年 1 月新增特性当预定义规格不满足需求时可用instance_type_custom精确指定资源{ containers: [ { class_name: MyContainer, image: ./Dockerfile, instance_type_custom: { vcpu: 2, // 1-4 vCPU memory_mib: 8192, // 512-12288 MiB (up to 12 GiB) disk_mib: 16384 // 2048-20480 MiB (up to 20 GB) } } ] }自定义类型硬性约束必须同时满足每个 vCPU 至少配 3 GiB 内存即 vCPU 与内存存在绑定下限每 1 GiB 内存最多配 2 GB 磁盘单容器上限4 vCPU、12 GiB 内存、20 GB 磁盘。因此在自定义时并非所有组合都合法。例如vcpu: 2时memory_mib不得低于 61442 × 3 GiBmemory_mib: 81928 GiB时disk_mib不得超过 163848 × 2 GB。超限组合会在部署校验阶段被拒绝。账户级资源限制所有容器共享账户级配额配置多个容器时需整体规划原文档表格完整保留ResourceLimitNotesTotal memory (all containers)400 GiBAcross all running containersTotal vCPU (all containers)100Across all running containersTotal disk (all containers)2 TBAcross all running containersImage storage per account50 GBStored container images当并发实例数 × 单实例规格逼近上述总量时会触发 gotchas.md 中描述的“No container instance available”错误——此时需要下调实例规格、缩减max_instances或联系 Cloudflare 支持申请扩容。max_instances的实际可用值也因此受限于账户剩余配额而非配置项本身。Container 类属性运行时的行为配置实例类型决定“多大”而 Container 类的属性决定“怎么跑”。这些属性定义在export class MyContainer extends Container中类型来自cloudflare/containers包import { Container } from cloudflare/containers; export class MyContainer extends Container { // Port Configuration defaultPort 8080; // Default port for fetch() calls requiredPorts [8080, 9090]; // Ports to wait for in startAndWaitForPorts() // Lifecycle sleepAfter 30m; // Inactivity timeout (5m, 30m, 2h, etc.) // Network enableInternet true; // Allow outbound internet access // Health Check pingEndpoint /health; // Health check endpoint path // Environment envVars { // Environment variables passed to container NODE_ENV: production, LOG_LEVEL: info }; // Startup entrypoint [/bin/start.sh]; // Override image entrypoint (optional) }各属性详解含与 API 的联动关系defaultPort调用container.fetch()且未显式指定端口时使用的端口。未设置时回退到端口 33。它与 api.md 中startAndWaitForPorts()的端口解析顺序显式 ports →requiredPorts→defaultPort→ 33直接相关。requiredPortsstartAndWaitForPorts()必须等到这些端口都开始监听才会返回。若未设置defaultPort数组第一个端口会成为默认端口。多端口服务如 HTTP gRPC metrics可参考 patterns.md 中配合switchPort()的多端口路由写法。sleepAfter空闲超时时长字符串如5m、30m、2h。容器在该时段无请求后停止每次请求都会重置计时器。这是“用资源换冷启动”的平衡杠杆设置太短会让有状态会话频繁冷启动冷启动约 2-3 秒设置太长则持续占用账户配额。停止前可借助 api.md 的onActivityExpired()钩子返回true保持存活如仍有 WebSocket 连接。enableInternet布尔值。为true时容器可发起出站 HTTP/TCP 请求。默认关闭需要访问外部 API 时务必显式开启。pingEndpoint健康检查路径如/health。该端点应返回 2xx 状态码。envVars传给容器的环境变量对象。与运行时自动注入的系统变量做合并且同名冲突时以自定义envVars为准见下节。entrypoint字符串数组覆盖镜像的CMD/ENTRYPOINT。可选若镜像默认入口正确则无需设置。设置错误是“Container start timeout”的常见原因之一gotchas.md。运行时自动注入的环境变量Cloudflare 会向容器自动注入以下系统环境变量无需手动配置VariableDescriptionCLOUDFLARE_APPLICATION_IDWorker application IDCLOUDFLARE_COUNTRY_A2Two-letter country code of request originCLOUDFLARE_LOCATIONCloudflare data center locationCLOUDFLARE_REGIONRegion identifierCLOUDFLARE_DURABLE_OBJECT_IDContainers Durable Object ID合并规则Container 类中自定义的envVars与上述运行时变量合并后一并注入容器同名时自定义值覆盖运行时值。这在调试多区域部署时尤其有用——应用可通过CLOUDFLARE_COUNTRY_A2/CLOUDFLARE_LOCATION感知请求来源而CLOUDFLARE_DURABLE_OBJECT_ID可让容器进程感知自己的持久身份。镜像管理与部署模型容器应用的镜像分发与普通 Worker 的代码分发有本质差异理解这点才能正确设计上线流程镜像预取pre-fetch镜像在部署前会被预取到所有全球节点从而保证快速冷启动典型 2-3 秒。这也是镜像存储计入账户配额50 GB的原因。滚动部署rolling deploys与 Workers 的“瞬时生效”不同容器部署是逐步滚动的——旧版本在滚动期间继续运行。发布节奏与回滚窗口需要按滚动模型规划。临时磁盘ephemeral disk容器磁盘是临时的每次停止都会重置。持久化必须依赖 Durable Object 存储this.ctx.storage不能假设文件系统在重启后保留。相关持久化与优雅停机实践见 patterns.md 与 gotchas.md。wrangler.toml 格式偏好 TOML 的团队可用等价配置name my-worker main src/index.ts compatibility_date 2026-01-10 [[containers]] class_name MyContainer image ./Dockerfile instance_type standard-2 max_instances 10 [[durable_objects.bindings]] name MY_CONTAINER class_name MyContainer [[migrations]] tag v1 new_sqlite_classes [MyContainer]两种格式完全等价wrangler.jsonc与wrangler.toml均受支持。原文档建议优先使用wrangler.jsonc因为它支持注释如每个字段的取值说明且 IDE 提示更好——这对于containers、durable_objects、migrations三段相互关联的配置尤其重要注释能显著降低后续维护成本。配置与运行 API 的联动要点配置文件只完成“声明”真正让容器跑起来还需运行期 API 的正确配合。以下是配置项与 api.md 中 API 的几个关键联动可作为配置完成后的自检清单max_instances× 路由方式getByName(id)做会话亲和每个用户固定实例、getRandom()做负载均衡。无自动扩缩容负载分配完全由 Worker 侧代码决定详见 patterns.md。requiredPorts×startAndWaitForPorts()启动后必须等待端口就绪再转发请求。若直接用start()进程启动即返回8 秒超时再fetch()会遇到 “connection refused”推荐startAndWaitForPorts()端口就绪返回20 秒超时gotchas.md。sleepAfter×onActivityExpired()空闲超时按“请求活动”计算而非“内部工作”。长任务期间应通过定期写入this.ctx.storage续期防止容器中途停止gotchas.md。优雅停机窗口收到 SIGTERM 后有15 分钟缓冲期之后 SIGKILL期间可关闭连接、落盘状态配合onStop()钩子实现优雅停机。延伸阅读containers 参考文档总览核心概念、路由决策树、Quick StartContainer 类 API启动方法、通信、生命周期钩子、调度常见错误与限制超时、内存超限、WebSocket 陷阱路由 / WebSocket / 优雅停机 / 队列与 Workflow 集成模式cloudflare-deploy Skill 总览产品决策树与部署前置检查【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare Containers Wrangler 配置完全指南：wrangler.jsonc / wrangler.toml、实例类型与 Container 类属性详解
Cloudflare Containers Wrangler 配置完全指南wrangler.jsonc / wrangler.toml、实例类型与 Container 类属性详解【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare Containers 允许你把 Docker 化的现有应用Node.js、Python 或任意自定义二进制直接运行在 Workers 平台上每个容器本质是一个带持久身份的 Durable Object。本文以本仓库 containers 参考文档 为骨架完整讲解 Wrangler 侧的全部配置维度两种配置文件格式、预定义/自定义实例类型、账户级资源上限、Container 类属性、运行时环境变量以及镜像部署模型并补充源码级佐证帮助你一次性配出一个可部署、可运维的容器 Worker 项目。注意Cloudflare Containers 目前处于beta阶段API 可能在没有通知的情况下变更、无 SLA 保证且初始仅支持部分区域。生产使用前务必做好 API 变更预案见 README。核心概念先理解“容器 Durable Object”在动手配置前先建立两个关键认知出自 containers/README.md每个容器都是一个 Durable Object拥有持久身份通过env.BINDING.getByName(id)或env.BINDING.getRandom()访问。因此配置中 Durable Objects 绑定与迁移migrations是必需项而不是可选项。身份持久、磁盘易失容器 ID 在停止后仍保留但磁盘每次停止都会重置。需要持久化的数据必须写入 Durable Object 存储this.ctx.storage这直接决定了后续配置中sleepAfter、镜像管理等设计取向。Wrangler 基本容器配置wrangler.jsonc原文档给出的最小可用配置骨架如下{ name: my-worker, main: src/index.ts, compatibility_date: 2026-01-10, containers: [ { class_name: MyContainer, image: ./Dockerfile, // Path to Dockerfile or directory with Dockerfile instance_type: standard-1, // Predefined or custom (see below) max_instances: 10 } ], durable_objects: { bindings: [ { name: MY_CONTAINER, class_name: MyContainer } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyContainer] // Must use new_sqlite_classes } ] }关键配置项要求配置项作用注意事项imageDockerfile 路径或包含 Dockerfile 的目录路径支持相对路径例如./Dockerfileclass_name容器类名必须与源码中export class MyContainer extends Container的导出名完全一致max_instances该容器允许的最大并发实例数与 api.md 中的getByName(id)/getRandom()配合决定并发上限durable_objects.bindings将容器类绑定为环境变量name是代码里env.MY_CONTAINER中的键名class_name指向容器类migrations声明容器类的持久状态迁移必须使用new_sqlite_classes而非new_classes因为容器作为 Durable Object 使用 SQLite 持久状态两个最容易踩坑的点Durable Objects 绑定与 migrations 缺一不可——缺失任何一个env.MY_CONTAINER都将不可用部署也会失败。migrations 必须用new_sqlite_classes——这是容器场景的强制要求直接沿用普通 Durable Object 的new_classes不会生效。每个迁移需带唯一tag如v1。实例类型配置预定义实例类型原文档提供了 6 种预定义规格直接通过instance_type字段引用TypevCPUMemoryDisklite1/16256 MiB2 GBbasic1/41 GiB4 GBstandard-11/24 GiB8 GBstandard-216 GiB12 GBstandard-328 GiB16 GBstandard-4412 GiB20 GB使用示例{ containers: [ { class_name: MyContainer, image: ./Dockerfile, instance_type: standard-2 // Use predefined type } ] }选择建议lite/basic适合轻量 API有状态会话、WebSocket 或内存敏感任务建议standard-2及以上standard-44 vCPU / 12 GiB / 20 GB是预定义规格中的上限。若应用超出lite的 256 MiB 内存会触发“Container memory exceeded”错误应改用更大规格或自定义实例类型见下节错误处理细节见 gotchas.md。自定义实例类型2026 年 1 月新增特性当预定义规格不满足需求时可用instance_type_custom精确指定资源{ containers: [ { class_name: MyContainer, image: ./Dockerfile, instance_type_custom: { vcpu: 2, // 1-4 vCPU memory_mib: 8192, // 512-12288 MiB (up to 12 GiB) disk_mib: 16384 // 2048-20480 MiB (up to 20 GB) } } ] }自定义类型硬性约束必须同时满足每个 vCPU 至少配 3 GiB 内存即 vCPU 与内存存在绑定下限每 1 GiB 内存最多配 2 GB 磁盘单容器上限4 vCPU、12 GiB 内存、20 GB 磁盘。因此在自定义时并非所有组合都合法。例如vcpu: 2时memory_mib不得低于 61442 × 3 GiBmemory_mib: 81928 GiB时disk_mib不得超过 163848 × 2 GB。超限组合会在部署校验阶段被拒绝。账户级资源限制所有容器共享账户级配额配置多个容器时需整体规划原文档表格完整保留ResourceLimitNotesTotal memory (all containers)400 GiBAcross all running containersTotal vCPU (all containers)100Across all running containersTotal disk (all containers)2 TBAcross all running containersImage storage per account50 GBStored container images当并发实例数 × 单实例规格逼近上述总量时会触发 gotchas.md 中描述的“No container instance available”错误——此时需要下调实例规格、缩减max_instances或联系 Cloudflare 支持申请扩容。max_instances的实际可用值也因此受限于账户剩余配额而非配置项本身。Container 类属性运行时的行为配置实例类型决定“多大”而 Container 类的属性决定“怎么跑”。这些属性定义在export class MyContainer extends Container中类型来自cloudflare/containers包import { Container } from cloudflare/containers; export class MyContainer extends Container { // Port Configuration defaultPort 8080; // Default port for fetch() calls requiredPorts [8080, 9090]; // Ports to wait for in startAndWaitForPorts() // Lifecycle sleepAfter 30m; // Inactivity timeout (5m, 30m, 2h, etc.) // Network enableInternet true; // Allow outbound internet access // Health Check pingEndpoint /health; // Health check endpoint path // Environment envVars { // Environment variables passed to container NODE_ENV: production, LOG_LEVEL: info }; // Startup entrypoint [/bin/start.sh]; // Override image entrypoint (optional) }各属性详解含与 API 的联动关系defaultPort调用container.fetch()且未显式指定端口时使用的端口。未设置时回退到端口 33。它与 api.md 中startAndWaitForPorts()的端口解析顺序显式 ports →requiredPorts→defaultPort→ 33直接相关。requiredPortsstartAndWaitForPorts()必须等到这些端口都开始监听才会返回。若未设置defaultPort数组第一个端口会成为默认端口。多端口服务如 HTTP gRPC metrics可参考 patterns.md 中配合switchPort()的多端口路由写法。sleepAfter空闲超时时长字符串如5m、30m、2h。容器在该时段无请求后停止每次请求都会重置计时器。这是“用资源换冷启动”的平衡杠杆设置太短会让有状态会话频繁冷启动冷启动约 2-3 秒设置太长则持续占用账户配额。停止前可借助 api.md 的onActivityExpired()钩子返回true保持存活如仍有 WebSocket 连接。enableInternet布尔值。为true时容器可发起出站 HTTP/TCP 请求。默认关闭需要访问外部 API 时务必显式开启。pingEndpoint健康检查路径如/health。该端点应返回 2xx 状态码。envVars传给容器的环境变量对象。与运行时自动注入的系统变量做合并且同名冲突时以自定义envVars为准见下节。entrypoint字符串数组覆盖镜像的CMD/ENTRYPOINT。可选若镜像默认入口正确则无需设置。设置错误是“Container start timeout”的常见原因之一gotchas.md。运行时自动注入的环境变量Cloudflare 会向容器自动注入以下系统环境变量无需手动配置VariableDescriptionCLOUDFLARE_APPLICATION_IDWorker application IDCLOUDFLARE_COUNTRY_A2Two-letter country code of request originCLOUDFLARE_LOCATIONCloudflare data center locationCLOUDFLARE_REGIONRegion identifierCLOUDFLARE_DURABLE_OBJECT_IDContainers Durable Object ID合并规则Container 类中自定义的envVars与上述运行时变量合并后一并注入容器同名时自定义值覆盖运行时值。这在调试多区域部署时尤其有用——应用可通过CLOUDFLARE_COUNTRY_A2/CLOUDFLARE_LOCATION感知请求来源而CLOUDFLARE_DURABLE_OBJECT_ID可让容器进程感知自己的持久身份。镜像管理与部署模型容器应用的镜像分发与普通 Worker 的代码分发有本质差异理解这点才能正确设计上线流程镜像预取pre-fetch镜像在部署前会被预取到所有全球节点从而保证快速冷启动典型 2-3 秒。这也是镜像存储计入账户配额50 GB的原因。滚动部署rolling deploys与 Workers 的“瞬时生效”不同容器部署是逐步滚动的——旧版本在滚动期间继续运行。发布节奏与回滚窗口需要按滚动模型规划。临时磁盘ephemeral disk容器磁盘是临时的每次停止都会重置。持久化必须依赖 Durable Object 存储this.ctx.storage不能假设文件系统在重启后保留。相关持久化与优雅停机实践见 patterns.md 与 gotchas.md。wrangler.toml 格式偏好 TOML 的团队可用等价配置name my-worker main src/index.ts compatibility_date 2026-01-10 [[containers]] class_name MyContainer image ./Dockerfile instance_type standard-2 max_instances 10 [[durable_objects.bindings]] name MY_CONTAINER class_name MyContainer [[migrations]] tag v1 new_sqlite_classes [MyContainer]两种格式完全等价wrangler.jsonc与wrangler.toml均受支持。原文档建议优先使用wrangler.jsonc因为它支持注释如每个字段的取值说明且 IDE 提示更好——这对于containers、durable_objects、migrations三段相互关联的配置尤其重要注释能显著降低后续维护成本。配置与运行 API 的联动要点配置文件只完成“声明”真正让容器跑起来还需运行期 API 的正确配合。以下是配置项与 api.md 中 API 的几个关键联动可作为配置完成后的自检清单max_instances× 路由方式getByName(id)做会话亲和每个用户固定实例、getRandom()做负载均衡。无自动扩缩容负载分配完全由 Worker 侧代码决定详见 patterns.md。requiredPorts×startAndWaitForPorts()启动后必须等待端口就绪再转发请求。若直接用start()进程启动即返回8 秒超时再fetch()会遇到 “connection refused”推荐startAndWaitForPorts()端口就绪返回20 秒超时gotchas.md。sleepAfter×onActivityExpired()空闲超时按“请求活动”计算而非“内部工作”。长任务期间应通过定期写入this.ctx.storage续期防止容器中途停止gotchas.md。优雅停机窗口收到 SIGTERM 后有15 分钟缓冲期之后 SIGKILL期间可关闭连接、落盘状态配合onStop()钩子实现优雅停机。延伸阅读containers 参考文档总览核心概念、路由决策树、Quick StartContainer 类 API启动方法、通信、生命周期钩子、调度常见错误与限制超时、内存超限、WebSocket 陷阱路由 / WebSocket / 优雅停机 / 队列与 Workflow 集成模式cloudflare-deploy Skill 总览产品决策树与部署前置检查【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考