企业官网建设流程全解析

Cloudflare Containers Wrangler 配置完全指南：wrangler.jsonc / wrangler.toml、实例类型与 Container 类属性详解

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

Cloudflare 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 } ] }

关键配置项要求

两个最容易踩坑的点：

1. Durable Objects 绑定与 migrations 缺一不可——缺失任何一个，env.MY_CONTAINER都将不可用，部署也会失败。
2. migrations 必须用new_sqlite_classes——这是容器场景的强制要求，直接沿用普通 Durable Object 的new_classes不会生效。每个迁移需带唯一tag（如v1）。

实例类型配置

预定义实例类型

原文档提供了 6 种预定义规格，直接通过instance_type字段引用：

使用示例：

{ "containers": [ { "class_name": "MyContainer", "image": "./Dockerfile", "instance_type": "standard-2" // Use predefined type } ] }

选择建议：lite/basic适合轻量 API；有状态会话、WebSocket 或内存敏感任务建议standard-2及以上；standard-4（4 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不得低于 6144（2 × 3 GiB）；memory_mib: 8192（8 GiB）时disk_mib不得超过 16384（8 × 2 GB）。超限组合会在部署校验阶段被拒绝。

账户级资源限制

所有容器共享账户级配额，配置多个容器时需整体规划（原文档表格完整保留）：

当并发实例数 × 单实例规格逼近上述总量时，会触发 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）直接相关。

• requiredPorts：startAndWaitForPorts()必须等到这些端口都开始监听才会返回。若未设置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 会向容器自动注入以下系统环境变量，无需手动配置：

合并规则：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 的几个关键联动，可作为配置完成后的自检清单：

1. max_instances× 路由方式：getByName(id)做会话亲和（每个用户固定实例）、getRandom()做负载均衡。无自动扩缩容，负载分配完全由 Worker 侧代码决定（详见 patterns.md）。
2. requiredPorts×startAndWaitForPorts()：启动后必须等待端口就绪再转发请求。若直接用start()（进程启动即返回，8 秒超时）再fetch()，会遇到 “connection refused”；推荐startAndWaitForPorts()（端口就绪返回，20 秒超时）（gotchas.md）。
3. sleepAfter×onActivityExpired()：空闲超时按“请求活动”计算而非“内部工作”。长任务期间应通过定期写入this.ctx.storage续期，防止容器中途停止（gotchas.md）。
4. 优雅停机窗口：收到 SIGTERM 后有15 分钟缓冲期（之后 SIGKILL），期间可关闭连接、落盘状态，配合onStop()钩子实现优雅停机。

延伸阅读

• containers 参考文档总览（核心概念、路由决策树、Quick Start）
• Container 类 API（启动方法、通信、生命周期钩子、调度）
• 常见错误与限制（超时、内存超限、WebSocket 陷阱）
• 路由 / WebSocket / 优雅停机 / 队列与 Workflow 集成模式
• cloudflare-deploy Skill 总览（产品决策树与部署前置检查）

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