事故是这样发生的:Worker 改了个小功能,我顺手在终端敲下 wrangler deploy,敲完才想起来——本地这份 wrangler.toml 刚刚为了调试,绑的还是测试环境的 KV,调试开关也没关。就这么十几秒,一份带着测试配置的代码堂而皇之上了生产。发现的时候冷汗都下来了,赶紧改回来重新发一遍。手动部署的问题从来不是命令难敲,而是人总会忘、总会累、总会在深夜里敲错那一下。这篇就把发布这件事从人手里拿走:代码推上 GitHub,剩下的交给流水线,你只需要看一眼绿色的对勾。
官方文档:https://developers.cloudflare.com/workers/ci-cd/
思路总览:从手敲命令到推代码即部署
自动部署的链路并不复杂,一共四步:本地照常开发调试;写完把代码 git push 到 GitHub;GitHub Actions 被这次推送触发,在云端的一台临时机器上拉下代码;最后由官方的 cloudflare/wrangler-action 调用 Wrangler,拿着预先存好的凭据把 Worker 发布到 Cloudflare。整条链路里没有你的电脑参与发布,本地关机了都不影响。
和手动部署摆在一起对比,差别一目了然:
| 对比项 | 手动 wrangler deploy | GitHub Actions 流水线 |
|---|---|---|
| 触发方式 | 人在本地终端敲命令 | push 到指定分支自动触发 |
| 发布环境 | 取决于本地当时开着哪份配置 | 由 workflow 文件写死,人改不了 |
| 用哪份代码 | 本地工作区,可能混着没提交的改动 | 仓库里那次提交,分毫不差 |
| 凭据存放 | 登录态存在本机 | 加密存放在仓库 Secrets |
| 出了问题 | 凭记忆回想刚才发了啥 | 每次运行都有日志和提交号可查 |
| 适合场景 | 一次性试验、临时调试 | 长期维护的正式项目 |
流水线最大的价值其实是最后两行:每次部署都精确对应一次 Git 提交,出了问题能查、能对、能退。至于是第一次接触 Workers 的朋友,建议先看 Workers 入门篇 把第一个 Worker 跑起来,再回来给它配上自动部署。
第一步:准备一个最小权限的 API Token
流水线要在云端替你发布 Worker,它手里必须有一张 Cloudflare 的「通行证」,这就是 API Token。注意不要图省事用 Global API Key,也不要随手给个管理员级别的大 Token——流水线只需要「发布 Worker」这一件事的权限,多给的每一分权限,都是泄露之后多赔出去的损失。
创建路径是:Cloudflare 控制台右上角头像 → My Profile → API Tokens → Create Token。在模板列表里直接选用 Edit Cloudflare Workers 这个现成模板,它预置了 Workers Scripts、Workers Routes、Workers KV 等发布 Worker 真正需要的编辑权限,范围刚好卡在 Workers 这一圈,不碰你的 DNS、不碰你的账单。创建时再顺手把 Account Resources 限定到目标账户,Token 生成后只显示一次,立刻复制保存。
WARNINGToken 的权限边界,就是这条流水线万一出事时的损失边界。绝对不要把 Token 明文写进 workflow 文件、代码或任何提交进仓库的地方——公开仓库里躺着的 Token 等于把发布权限送给了全世界,别人可以拿它往你的账户里发布任意 Worker。Token 只能进下一节讲的仓库 Secrets。
关于 Token 的创建细节、有效期管理和轮换方法,系列里的 API Token 与 DDNS 篇 已经讲过一整套,这里不重复,只强调一句:给流水线的 Token 要单独创建、单独命名(比如 github-actions-deploy),将来要吊销、要轮换,都不会误伤你其他用途的 Token。
第二步:把凭据存进仓库 Secrets
来到 GitHub 仓库页面,依次打开 Settings → Secrets and variables → Actions → New repository secret,添加两个条目:
| Secret 名称 | 填什么 | 从哪儿拿 |
|---|---|---|
CLOUDFLARE_API_TOKEN | 上一步创建的 API Token | 创建 Token 时显示的那一串 |
CLOUDFLARE_ACCOUNT_ID | 你的 Cloudflare 账户 ID | 控制台首页右侧栏,或域名概览页 |
Secrets 存进去之后会被加密,任何人都看不到原文,包括你自己——忘了只能删掉重建。workflow 文件里通过 ${{ secrets.CLOUDFLARE_API_TOKEN }} 这样的方式引用,运行时 GitHub 才会把值注入进去,日志里出现时也会被自动打码。Account ID 本身不算机密(它会出现在控制台网址里),放进 Secrets 纯粹是为了配置集中管理,日后换账户改一处即可。
第三步:写下完整的 workflow
在仓库根目录新建文件 .github/workflows/deploy.yml,内容如下。这份配置实现的是最常见的策略:代码推到 main 分支就自动部署到生产环境。
name: Deploy Worker
on: push: branches: - main
jobs: deploy: runs-on: ubuntu-latest name: Deploy to production steps: - name: Checkout uses: actions/checkout@v4
- name: Deploy with Wrangler uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}逐段拆开看:on.push.branches 限定只有 main 分支的推送才触发,避免你在别的分支上随手一推就上了生产;actions/checkout@v4 负责把这次提交的代码拉到运行器上;核心就是 cloudflare/wrangler-action@v3 这一步,它内部装好 Wrangler 并执行默认的 deploy 命令,apiToken 和 accountId 从 Secrets 里取。
文件提交进仓库后,随便往 main 推一次小改动,然后打开仓库的 Actions 标签页,就能看到这条流水线跑起来。全绿通过之后去访问你的 Worker 地址,新代码应该已经生效。整个过程里,本地连 Wrangler 都不用装。
有几个可选参数值得知道:wranglerVersion 可以锁定 Wrangler 的具体版本,避免上游大版本更新突然改变行为;command 可以换掉默认的 deploy,比如改成 versions upload 只上传新版本而不立即切流量;workingDirectory 则用于仓库里有多个项目、Worker 藏在子目录的情况。先从最小配置跑通,再按需加料。
第四步:多环境,预发和生产分开
只有一个环境时,任何改动都是直接见用户。项目稍微正经一点,就应该拆出预发(staging)环境:新代码先发到预发地址,自己点一遍确认没问题,再发生产。Wrangler 的环境机制正好为此而生,在 wrangler.toml 里这样写:
name = "my-worker"main = "src/index.js"compatibility_date = "2025-01-01"
[env.staging]name = "my-worker-staging"
[env.staging.vars]DEBUG = "true"API_BASE = "https://staging-api.example.com"
[env.production]name = "my-worker-production"
[env.production.vars]DEBUG = "false"API_BASE = "https://api.example.com"顶层配置是默认环境,[env.staging] 和 [env.production] 各自继承顶层、再覆盖自己的那部分。部署时靠 --env 区分:wrangler deploy --env staging 发预发,wrangler deploy --env production 发生产,两个环境是两个独立的 Worker,互不影响。
落到流水线上,推荐的分支策略是:develop 分支对应 staging,main 分支对应 production。workflow 稍作扩展,用两个 job 分别处理:
name: Deploy Worker
on: push: branches: - main - develop
jobs: deploy-staging: if: github.ref == 'refs/heads/develop' runs-on: ubuntu-latest name: Deploy to staging steps: - uses: actions/checkout@v4 - name: Deploy staging uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} command: deploy --env staging
deploy-production: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest name: Deploy to production steps: - uses: actions/checkout@v4 - name: Deploy production uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} command: deploy --env production日常开发往 develop 推,自动上预发;验证通过后把 develop 合并进 main,自动上生产。分支即环境,合并即发布,整个流程不需要任何人碰发布命令。这里有个最容易踩的坑:--env 后面写的名字必须和 wrangler.toml 里 [env.xxx] 的名字一字不差,写错了 Wrangler 会直接报错退出,流水线变红——倒也算一种保护。
第五步:密钥怎么办,两种注入方式要分清
先明确一条界线:数据库密码、第三方 API 密钥这类敏感值,永远不进 wrangler.toml 的 [vars]——那是明文,会跟着代码进仓库。敏感值在 Workers 里叫 Secret,通过加密通道单独管理,运行时以环境变量的形式出现在代码里。
手动管理的方式是在本地执行:
wrangler secret put API_KEY# 按提示粘贴密钥值,输入过程不回显
wrangler secret list# 查看已设置的 Secret 名称(只能看名字,看不到值)这种方式适合「设一次、很少动」的密钥:你在本地亲手录入,值不经过任何第三方系统。
另一种方式是让流水线在部署时顺带注入。wrangler-action 提供了 secrets 参数:把 Secret 的名字按行写进去,同时在 env 里把对应的仓库 Secret 传进来,Action 会在部署前后替你执行 wrangler secret put:
- name: Deploy with secrets uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} secrets: | API_KEY WEBHOOK_TOKEN env: API_KEY: ${{ secrets.API_KEY }} WEBHOOK_TOKEN: ${{ secrets.WEBHOOK_TOKEN }}两种方式的区别在于信任链:手动 secret put 时密钥只经过你的电脑和 Cloudflare;CI 注入则多经过 GitHub Secrets 这一环,好处是密钥的增改也纳入了仓库管理、换密钥不用等人开电脑。没有哪种绝对更好,个人项目手动设一次最省事,团队协作或密钥轮换频繁的项目走 CI 注入更顺。要注意 CI 注入只在流水线运行时生效,本地 wrangler dev 调试时读不到这些值,本地开发所需的变量请放在不提交的 .dev.vars 文件里。
另外提醒一句,部署和定时、存储这些运行时能力是两回事:给 Worker 加 Cron 定时触发或 KV 存储的配置方法,在 Workers 定时与 KV 篇 里,那些绑定写在 wrangler.toml 里,流水线部署时会自动一并生效,不用额外处理。
第六步:发错了怎么回滚
流水线再可靠,也挡不住代码本身有 bug——新版本上线后发现接口全挂,第一件事是回滚到上一个好版本,而不是急着改代码。Wrangler 内置了版本管理命令:
# 查看最近的部署记录,找到上一个正常版本的版本号wrangler deployments list
# 回滚到指定版本(不填版本号时会列出最近版本让你选)wrangler rollback回滚是把流量切回旧版本,秒级生效,不需要重新构建、更不需要重新走一遍流水线。等流量稳住之后,再慢慢定位 bug、修复、重新走 develop → main 的正常发布流程。也可以在 Cloudflare 控制台的 Worker 页面 → Deployments 里点选历史版本回滚,效果相同。养成一个习惯:每次生产发布后留意几分钟 Actions 日志和线上表现,真出问题时回滚永远是第一动作,复盘是第二动作。
顺带说一句:Pages 的自动部署更省事
如果你的项目是静态站点或全栈站点而不是纯 Worker,Cloudflare Pages 连这条流水线都不用你搭:在 Pages 里创建项目时直接连接 GitHub 仓库,之后每次 push 都自动构建部署,非生产分支还会生成独立的预览地址。两种方式没有高下之分,区别只在控制权:Pages 的 Git 直连是全自动托管,构建命令和环境变量在控制台里配;Workers 走 Actions 流水线,全部流程写在仓库的 YAML 里,能塞进测试、检查等任意步骤。选型细节可以看系列的 Pages 部署篇。
排障:流水线变红时先查这几处
日志报 Authentication error(错误码 10000)。 十有八九是 Token 的问题:用了只读模板(比如 Read All Resources)创建的 Token 能看不能写,部署必然失败。回到 Token 设置里确认用的是 Edit Cloudflare Workers 模板;顺带检查 Token 有没有过期、复制时有没有带上多余的空格。
日志报 No account id found。 这是 wrangler-action 的经典提示:accountId 没传对。要么仓库 Secrets 里 CLOUDFLARE_ACCOUNT_ID 压根没建,要么名字拼错导致 ${{ secrets.xxx }} 取了个空值。Secret 名称大小写敏感,一个字母都不能差;也可以把 account_id 直接写进 wrangler.toml 作为兜底。
部署成功了,但代码没更新。 先确认你推的分支对不对:workflow 只监听 main(和示例里的 develop),推到其他分支根本不会触发,Actions 页面里自然也找不到记录。再看 Actions 里那次运行拉取的提交号,是不是你以为的那一次。
报环境不存在或配置不生效。 对照第四节的坑:command 里的 --env staging 必须与 wrangler.toml 中的 [env.staging] 严格同名;另外注意,未写在任何 [env] 段里的顶层 [vars] 不会自动出现在具名环境中,具名环境要用到的变量要在各自的段里再声明一遍。
workflow 文件根本没被识别。 文件必须位于 .github/workflows/ 目录下、后缀是 .yml 或 .yaml,且已经提交到了仓库的默认分支。YAML 缩进错位也会导致整份文件被忽略,用编辑器的 YAML 校验先过一遍再提交。
小结
把这篇的动作连起来,就是一条完整的发布流水线:用 Edit Cloudflare Workers 模板创建最小权限 Token,存进仓库 Secrets;一份 deploy.yml 让 main 分支的每次推送都自动部署;develop 加 --env 分出预发和生产;密钥用 wrangler secret put 或 Action 的 secrets 参数注入,绝不进代码;真发错了,wrangler rollback 一键退回。搭好之后,发布就从一件需要集中精神的手工活,变成了一次普通的 git push。开头那种把测试配置发上生产的事故,不会再有第二次。