使用 Pulumi 部署 Cloudflare Workers 的常见陷阱与排查实战:autoskills cloudflare-deploy 技能参考解读
使用 Pulumi 部署 Cloudflare Workers 的常见陷阱与排查实战:autoskills cloudflare-deploy 技能参考解读
Pulumi 是 autoskills 技能注册表中 cloudflare-deploy 技能推荐的三种基础设施即代码(IaC)方案之一(另见 terraform 与 REST API),本文围绕 Pulumi 排障文档 展开,系统梳理使用 @pulumi/cloudflare(v6.x)部署 Workers、D1、KV、R2 等资源时最高频的 9 类报错、6 条最佳实践与平台限额。读完本文,你将掌握"先构建再部署、绑定名严格一致、用 dependsOn 编排迁移、以 VERSION 绑定强制更新"等一整套可复制的排障与部署模式。
本文定位:一份可照着操作的 Pulumi 排障手册
该文档位于技能注册表 packages/autoskills/skills-registry/cloudflare-deploy/references/pulumi/gotchas.md,是 Pulumi 参考四件套的最后一环。按 Pulumi README 给出的推荐阅读顺序,它应在以下场景被打开:
| 顺序 | 文件 | 适用场景 |
|---|---|---|
| 1 | configuration.md | 首次配置、资源参数参考(Workers/KV/D1/R2/Queues/Pages) |
| 2 | patterns.md | 复杂应用架构、多环境、组件化资源 |
| 3 | api.md | Outputs、依赖、导入、动态 Provider 等进阶能力 |
| 4 | gotchas.md(本文主体) | 调试、部署失败、限额核对 |
简言之:configuration.md 教你怎么"写对",patterns.md 教你怎么"写漂亮",api.md 教你怎么"写高级",而 gotchas.md 负责在你"写挂了"之后把你捞回来。
一、常见错误速查与解决方案
以下按文档顺序逐条展开,每条都遵循「现象 → 根因 → 修复」三段式,代码可直接复制到你的 Pulumi 项目中使用。
1. "No bundler/build step"——Pulumi 直接上传原始代码
现象:Worker 部署后运行报错 Cannot use import statement outside a module。
根因:Pulumi 的 WorkerScript 资源不做代码打包,它把 content 字段里你提供的文件内容原样上传。如果直接把未编译的 TypeScript 源码喂给它,Cloudflare 运行时自然无法处理 import 语句。
修复:在 Pulumi 部署之前先完成构建,并把产物读入 content:
// WRONG: Pulumi won't bundle this
const worker = new cloudflare.WorkerScript("worker", {
content: fs.readFileSync("./src/index.ts", "utf8"), // Raw TS file
});
// RIGHT: Build first, then deploy
import * as command from "@pulumi/command";
const build = new command.local.Command("build", {
create: "npm run build",
dir: "./worker",
});
const worker = new cloudflare.WorkerScript("worker", {
content: build.stdout.apply(() => fs.readFileSync("./worker/dist/index.js", "utf8")),
}, {dependsOn: [build]});
这里有两个关键点值得展开:
command.local.Command是 Pulumi 官方@pulumi/command包提供的本地命令执行资源,create中的npm run build会在pulumi up时于dir指定目录执行;dependsOn: [build]显式声明 Worker 依赖构建任务,确保content读取时dist/index.js已存在。在 patterns.md 的 "Build + Deploy Pattern" 一节中,同一模式被整理为可直接复用的骨架,CI 中也建议保留独立的构建步骤。
2. "wrangler.toml not consumed"——配置漂移
现象:本地 wrangler dev 一切正常,pulumi up 部署却失败或行为不一致。
根因:Pulumi 完全忽略 wrangler.toml,它只认 Pulumi 资源里的显式参数。也就是说,两套配置必须手动保持同步,否则就会出现"本地能跑、线上不对"的漂移问题。
修复:推荐以 Pulumi 配置为唯一事实来源(single source of truth),用 command.local.Command 反向生成 wrangler.toml,让本地开发环境与生产部署共用同一套绑定配置:
// Pattern: Export Pulumi config to wrangler.toml
const workerConfig = {
name: "my-worker",
compatibilityDate: "2025-01-01",
compatibilityFlags: ["nodejs_compat"],
};
new command.local.Command("generate-wrangler", {
create: pulumi.interpolate`cat > wrangler.toml <<EOF
name = "${workerConfig.name}"
compatibility_date = "${workerConfig.compatibilityDate}"
compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}
EOF`,
});
patterns.md 的 "Wrangler.toml Generation" 一节给出了更完整的版本:先创建 KV、D1、R2 资源,再把 kv_namespaces、d1_databases、r2_buckets 段一并写入 wrangler.toml,并用 dependsOn: [kv, db, bucket] 保证生成时机正确,最后 Worker 再 dependsOn: [wranglerGen] 等待配置文件落盘。这样 wrangler dev 与生产使用完全一致的绑定,从机制上杜绝配置漂移。如果团队以 wrangler.toml 为事实来源,也可以反向在 Pulumi 中读取该文件(文档称之为 "reverse direction" 替代方案)。
3. "False no-changes detection"——内容 SHA 未变化导致误判"无变更"
现象:Worker 代码明明更新了,pulumi up 却提示 "no changes",线上没有新部署。
根因:Pulumi 对 content 做哈希比对,如果本次改动只是空白符、注释等不影响哈希的内容(或部署逻辑未真正变更 content),引擎会判定资源无变化而跳过。
修复:向 Worker 注入一个随时间变化的 VERSION 明文绑定,强制每次部署产生新的 diff:
const version = Date.now().toString();
const worker = new cloudflare.WorkerScript("worker", {
content: code,
plainTextBindings: [{name: "VERSION", text: version}], // Forces new deployment
});
该方案在 patterns.md 中被命名为 "Content SHA Pattern (Force Updates)"。除了时间戳,也可以使用构建产物的内容哈希(如 git rev-parse HEAD 或产物文件 SHA-256),语义更清晰——只有"真正的代码变更"才会触发重新部署,时间戳则保证每次 up 都产生新版本,适合希望每次部署都有可追溯版本号的场景。
4. "D1 migrations don't run on pulumi up"——数据库迁移不会自动执行
现象:D1 数据库创建成功,但表结构从未被应用。
根因:cloudflare.D1Database 资源只负责在 Cloudflare 侧创建数据库实例,不执行任何 SQL 迁移。schema 必须由你来跑。
修复:用 command.local.Command 调用 wrangler d1 execute,并用 dependsOn 串联"建库 → 迁移 → 部署 Worker"三者的顺序:
const db = new cloudflare.D1Database("db", {accountId, name: "mydb"});
// Run migrations after DB created
const migration = new command.local.Command("migrate", {
create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
}, {dependsOn: [db]});
// Worker depends on migrations
const worker = new cloudflare.WorkerScript("worker", {
d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
}, {dependsOn: [migration]});
这里 db.id / db.name 是 Pulumi Output,pulumi.interpolate 会在值解析后拼入命令,天然形成隐式依赖;dependsOn 则是显式声明顺序。两类依赖的具体语义可参见 api.md 的 "Resource Dependencies" 一节。对于不在 Provider 覆盖范围内的自定义操作(例如对 D1 执行任意 SQL),api.md 还提供了 pulumi.dynamic.ResourceProvider 自定义动态 Provider 的完整实现,可直接调用 Cloudflare REST API。
5. "Missing required property 'accountId'"
现象:报错 Error: Missing required property 'accountId'。
根因:绝大多数 Cloudflare 资源(Workers、KV、D1、R2、Queue 等)都要求显式提供 accountId,而配置里缺了它。
修复:把 accountId 写入 stack 配置文件(注意是 Pulumi.<stack>.yaml,<stack> 替换为你实际使用的栈名,如 dev、prod):
# Pulumi.<stack>.yaml
config:
cloudflare:accountId: "abc123..."
然后在代码中通过 pulumi.Config 读取:
const accountId = new pulumi.Config("cloudflare").require("accountId");
README.md 的 Setup 一节还展示了 Pulumi.yaml 中如何用环境变量引用 API Token(cloudflare:apiToken: ${CLOUDFLARE_API_TOKEN}),以及 Provider 资源的三种认证方式(API Token / 传统 API Key / API User Service Key),其中 API Token 是官方推荐的认证方式。
6. "Binding name mismatch"——绑定名不一致
现象:Worker 运行时报 env.MY_KV is undefined。
根因:Pulumi 资源里声明的绑定名与 Worker 代码中 env 对象上访问的属性名不一致。绑定名是大小写敏感的,MY_KV 与 my_kv 是两个完全不同的名字。
修复:让两处的名字逐字符一致:
// Pulumi
kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}]
// Worker code
export default { async fetch(request, env) { await env.MY_KV.get("key"); }}
这条规则适用于所有绑定类型:KV(kvNamespaceBindings)、R2(r2BucketBindings)、D1(d1DatabaseBindings)、Queue(queueBindings)、Service(serviceBindings)、明文/密文变量(plainTextBindings / secretTextBindings)等。完整字段清单可对照 configuration.md 的 WorkerScript 配置示例,其中还包括 v6.x 新增的 analyticsEngineBindings、browserBinding(Browser Rendering)、aiBinding(Workers AI)与 hyperdriveBindings。
7. "API token permissions insufficient"——Token 权限不足
现象:报错 Error: authentication error (10000)。
根因:所用 API Token 缺少目标资源所需权限,被 Cloudflare API 拒绝。
修复:为 Token 授予所需权限,至少包括:
Account.Workers Scripts:Edit(编辑 Worker 脚本)Account.Account Settings:Read(读取账户设置)
权限集应遵循最小授权原则,按实际管理的资源类型(KV、D1、R2、DNS 等)逐步追加对应权限,不要为了省事直接给"全部账户权限"。
8. "Resource not found after import"——导入后资源异常
现象:通过 pulumi import 导入的已有资源,在下次 pulumi up 时被标记为"有变更"。
根因:导入后 Pulumi 状态(state)中记录的属性与实际云端资源存在差异,即"状态漂移"——Pulumi 认为它管理的资源与真实配置不一致。
修复:先核对导入语法与资源标识格式,再通过 pulumi preview 观察差异,让 Pulumi 代码与实际资源逐项对齐:
pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
pulumi preview # If shows changes, adjust Pulumi code to match actual resource
重点检查属性名与类型是否完全一致(例如 name vs title、字符串 vs 数组、可选字段是否被隐式补全)。api.md 的 "Import Existing Resources" 一节给出了 KV、R2、D1、DNS 等其他资源的导入语法(如 pulumi import cloudflare:index/r2Bucket:R2Bucket my-bucket <account_id>/<bucket_name>),可一并参考。
9. "v6.x Worker versioning confusion"——版本化部署三件套 vs 自动版本化
现象:Worker 已部署,但线上流量没有打到新版本。
根因:@pulumi/cloudflare v6.x 引入了一套新的版本化资源模型——由 Worker(版本容器)+ WorkerVersion(不可变版本)+ WorkersDeployment(带流量切分的部署)三个资源协同工作。如果混用或只创建了其中部分资源,流量可能不会路由到预期版本。
修复:两种模式按需选择:
// SIMPLE: WorkerScript auto-versions (default behavior)
const worker = new cloudflare.WorkerScript("worker", {
accountId, name: "my-worker", content: code,
});
// ADVANCED: Manual versioning for gradual rollouts (v6.x)
const worker = new cloudflare.Worker("worker", {accountId, name: "my-worker"});
const version = new cloudflare.WorkerVersion("v1", {
accountId, workerId: worker.id, content: code, compatibilityDate: "2025-01-01",
});
const deployment = new cloudflare.WorkersDeployment("prod", {
accountId, workerId: worker.id, versionId: version.id,
});
决策标准在 configuration.md 与 patterns.md 中表述一致:
- 大多数应用:直接用
WorkerScript,它自带自动版本化,一份资源搞定; - 蓝绿部署、金丝雀发布、渐进式灰度:用三件套。特别是
WorkersDeployment.versions支持按百分比切分流量,例如金丝雀 10% 新版本 + 90% 旧版本:
const deployment = new cloudflare.WorkersDeployment("canary", {
accountId, workerId: worker.id,
versions: [{versionId: v2.id, percentage: 10}, {versionId: v1.id, percentage: 90}],
kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
});
注意绑定(bindings)在版本化模型下配置在 WorkersDeployment 层,而不是 WorkerVersion 层,这也是容易踩坑的地方。
二、最佳实践清单
文档总结的 6 条最佳实践,几乎每一条都能在配套参考里找到更完整的展开,这里逐条给出落地要点:
- 始终设置
compatibilityDate——锁定 Worker 运行时行为,防止 Cloudflare 平台侧行为变更悄悄破坏线上功能。在WorkerScript与WorkerVersion上都要设置。 - 先构建再部署——Pulumi 不做打包,务必用
command.local.Command或 CI 构建步骤产出dist产物后再读入content(见上文第 1 条)。 - 绑定名严格匹配——大小写敏感,Pulumi 声明与 Worker 代码
env.*访问必须逐字符一致(见上文第 6 条)。 - 用
dependsOn编排迁移——确保 D1 迁移在 Worker 部署之前完成(见上文第 4 条)。 - 为 Worker 内容加版本——用
VERSION绑定(时间戳或内容哈希)强制内容变更触发重新部署(见上文第 3 条)。 - 密钥存入 stack 配置——用
pulumi config set --secret存储 API 密钥,避免明文写进代码或仓库。对应地,代码侧用config.requireSecret("apiKey")读取,再经secretTextBindings注入 Worker;这样密钥会以加密形式保存在 Pulumi 状态中,详见 api.md 的 "Secrets Management" 一节。
三、平台限额参考
排障时先对照限额表,很多"看起来是代码问题"的现象实际是命中了平台配额。以下数据来自参考文档,均以当前 Cloudflare 平台公开限额为准:
| 资源 | 限额 | 说明 |
|---|---|---|
| Worker 脚本大小 | 10 MB | 含全部依赖,压缩后计算 |
| Worker CPU 时间 | 50ms(免费)/ 30s(付费) | 按每次请求计 |
| KV 键数量 | 不限 | 写 1000 ops/秒,读 100k ops/秒 |
| R2 存储 | 不限 | A 类操作 100 万次/月免费,B 类 1000 万次/月免费 |
| D1 数据库 | 每账户 50,000 个 | 免费版每账户 10 个,每个 5 GB |
| Queues | 每账户 10,000 个 | 免费版 100 万 ops/天 |
| Pages 项目 | 每账户 500 个 | 免费版 100 个项目 |
| API 请求 | 视套餐而定 | 免费版约 1200 次/5 分钟 |
需要强调的是:限额是动态变化的,且不同套餐差异显著。部署前应到 Cloudflare 控制台或官方文档核对当前套餐下的最新数值,本文表格仅作快速参考。涉及免费版与付费版的差异项,建议优先以实际账号的套餐信息为准。
四、关联阅读与进一步排查
本排障手册不是孤立文档,它是 autoskills 技能注册表 cloudflare-deploy 技能中 Pulumi 参考的组成部分。当遇到本文未覆盖的问题时,按以下顺序深入:
- Pulumi README——Provider 概述、认证方式、核心资源类型清单与阅读顺序;
- configuration.md——Workers/KV/D1/R2/Queues/Pages/DNS 的完整资源配置示例、v6.x 资产目录(
assets.path)与版本化部署参数; - patterns.md——组件化资源、全栈 Worker 应用、多环境、队列处理、Service Binding 微服务、事件驱动架构与金丝雀灰度示例;
- api.md——Outputs 导出、隐式/显式依赖、动态 Provider、数据源、资源导入、密钥管理与 Transform 模式;
- SKILL.md——cloudflare-deploy 技能的决策树,帮助判断某个需求该用 Workers、Pages、D1、Queues 还是其他平台服务,以及部署前必须先执行
npx wrangler whoami验证认证; - wrangler 参考——若更倾向 CLI 方式部署,或需要在沙箱受限时以
sandbox_permissions=require_escalated重试网络请求。
此外,文档原 "Resources" 一节提到的 Pulumi Registry、Pulumi API Docs 与 Cloudflare 官方文档,均可在 Pulumi 与 Cloudflare 的官方网站按包名 @pulumi/cloudflare 检索获取,作为本地参考之外的权威补充。
总结:Pulumi 部署 Cloudflare 的绝大多数故障,都逃不出"没打包、配置没同步、绑定名不一致、依赖顺序没排、权限不足、版本化模型用错"这几类根因。把本文的 9 条排障路径和 6 条最佳实践固化成你的部署前检查清单,即可把 pulumi up 从"试错现场"变成"一次通过"。