使用 Pulumi 部署 Cloudflare Workers 的常见陷阱与排查实战:autoskills cloudflare-deploy 技能参考解读

原创2026-10-09 21:28:001,888 阅读

使用 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 条最佳实践,几乎每一条都能在配套参考里找到更完整的展开,这里逐条给出落地要点:

  1. 始终设置 compatibilityDate——锁定 Worker 运行时行为,防止 Cloudflare 平台侧行为变更悄悄破坏线上功能。在 WorkerScript 与 WorkerVersion 上都要设置。
  2. 先构建再部署——Pulumi 不做打包,务必用 command.local.Command 或 CI 构建步骤产出 dist 产物后再读入 content(见上文第 1 条)。
  3. 绑定名严格匹配——大小写敏感,Pulumi 声明与 Worker 代码 env.* 访问必须逐字符一致(见上文第 6 条)。
  4. 用 dependsOn 编排迁移——确保 D1 迁移在 Worker 部署之前完成(见上文第 4 条)。
  5. 为 Worker 内容加版本——用 VERSION 绑定(时间戳或内容哈希)强制内容变更触发重新部署(见上文第 3 条)。
  6. 密钥存入 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 从"试错现场"变成"一次通过"。

登录后查看全文
autoskills