BoLei space

deploy-workflow

10 min read

Cloudflare + GitHub：网站部署与数据仓库工作流

这份文档只讲怎么把一个网站部署到 Cloudflare，并把可写数据放进 GitHub 私有仓库。按顺序做，不要跳步。

配套演示项目：examples/glow-clock/（辉光管时钟）。第一次走通时，就用这个项目当「代码仓库」里的源码。时钟本身不重要，它只是让你把整条流水线跑通的样本。

做完你应有：

东西作用可见性
GitHub 仓库 glow-clock网站源码公开或私有
GitHub 仓库 glow-clock-data运行时写入的 JSON必须私有
Cloudflare Worker glow-clock对外的网站—
GitHub Actions推 main 即部署—

数据和源码必须分开。源码一公开，数据仓库如果混在里面也会公开。

0. 硬规则（后面所有翻车都来自违反这些）

  1. GitHub Actions 的 Variable 名不能以 GITHUB_ 开头。
    写 DATA_REPO，不要写 GITHUB_DATA_REPO。报错原文：Variable name cannot start with "GITHUB_" prefix.
  2. GitHub Actions 里不要用 Secret 名 GITHUB_TOKEN。
    系统已占用。你的 PAT 必须叫 DATA_GITHUB_TOKEN。
    在 wrangler-action 里写 secrets: GITHUB_TOKEN 会失败：Failed to upload secrets.
  3. Worker 运行时的密钥在 Cloudflare 控制台配，不要靠 Actions 去 secret put。
  4. 环境变量在 Settings → Variables and Secrets，不在 Bindings。
    Bindings 里的 D1 / KV / Secrets Store 都不是这条工作流要的。
  5. 改了变量必须再部署一次（重新跑 Actions 最稳）。只保存在页面上、不部署，网站仍是旧环境。
  6. 代码里同时读两套名字，部署时同时写入两套，避免新旧脚本不一致：
    DATA_REPO 与 GITHUB_DATA_REPO，DATA_BRANCH 与 GITHUB_DATA_BRANCH。
  7. 黄色 Node.js 20 is deprecated 可以忽略，不是失败原因。
  8. 数据仓库新建时必须勾选 README，否则没有 main 分支，GitHub Contents API 写不进去。

1. 记下 GitHub 用户名

头像 → Your profile。地址栏 https://github.com/某某某 的 某某某 就是用户名。
下文所有 你的用户名/glow-clock-data 都换成它。

2. 建数据仓库（私有）

  1. 打开 https://github.com/new
  2. Repository name：glow-clock-data
  3. 选 Private
  4. 勾选 Add a README file
  5. Create repository

此时没有 data/ 文件夹是正常的。网站第一次成功保存配置后才会出现 data/clock.json。

3. Fine-grained PAT（只能开数据仓库）

  1. GitHub → Settings → 最底部 Developer settings
  2. Personal access tokens → Fine-grained tokens → Generate new token
  3. 按表填：
栏值
Token nameglow-clock-data
Expiration90 days 或更长
Resource owner你的账号
Repository accessOnly select repositories → 只勾 glow-clock-data
Permissions → ContentsRead and write
  1. Generate，立刻复制 github_pat_… 到记事本。关掉页面就没了。
  2. 不要把 PAT 提交进代码仓库，不要发到聊天。

这串 PAT 后面填 两次：GitHub Actions Secret DATA_GITHUB_TOKEN，以及 Cloudflare Worker Secret GITHUB_TOKEN（Cloudflare 允许这个名字）。

4. 建代码仓库并放入演示源码

4-A 解压 / 拷贝源码

演示目录是 examples/glow-clock/。上传到 GitHub 时，仓库根目录就要能看到这些文件（不要多套一层文件夹）：

package.json
wrangler.jsonc
src/worker.js
public/index.html
public/styles.css
public/clock.js
.github/workflows/deploy.yml

不要上传 node_modules。本演示没有 lock 文件，也不需要 npm ci。

4-B 建空仓库

https://github.com/new

栏值
Repository nameglow-clock
README / .gitignore / license全部不要勾、不要选

Create repository。下一页是空的 Quick setup。

4-C 用 GitHub Desktop 上传（推荐，新手只走这一条）

  1. 安装 https://desktop.github.com，登录同一账号
  2. File → New Repository
    • Local path 选中能直接看到 wrangler.jsonc 的那一层
    • 不要勾 README
  3. Summary 填 first upload → Commit to main
  4. Publish repository，名称 glow-clock
  5. 浏览器打开 https://github.com/你的用户名/glow-clock

验收：必须点得开 .github/workflows/deploy.yml。网页拖文件经常漏掉隐藏目录 .github，所以不要用网页上传当主路径。

命令行备选：

cd 能看到wrangler.jsonc的目录
git init
git add .
git commit -m "glow-clock"
git branch -M main
git remote add origin https://github.com/你的用户名/glow-clock.git
git push -u origin main

密码处填第 3 步 PAT，不是 GitHub 登录密码。

5. 打开 Actions

代码仓库顶栏 Actions。若出现 enable workflows，点允许。
左侧应有 Deploy glow-clock to Cloudflare。先不要 Run。

6. Actions Secrets（3 条，名字一字不差）

路径：glow-clock → Settings → Secrets and variables → Actions → New repository secret

Name值
CLOUDFLARE_API_TOKEN第 7 步
CLOUDFLARE_ACCOUNT_ID第 7 步
DATA_GITHUB_TOKEN第 3 步整串 github_pat_…

禁止把第三条起名为 GITHUB_TOKEN。

7. Cloudflare API Token 与 Account ID

  1. dash.cloudflare.com → 头像 → My Profile → API Tokens
  2. Create Token → 模板 Edit Cloudflare Workers → Create Token → 复制
  3. 填回 CLOUDFLARE_API_TOKEN
  4. Account ID：Workers 和 Pages 右侧 Overview 的 32 位字符，填回 CLOUDFLARE_ACCOUNT_ID

8. Actions Variables（不是 Secret）

同一页切到 Variables → New repository variable。

NameValue
DATA_REPO你的用户名/glow-clock-data
DATA_BRANCHmain

不要 https://，不要 .git，中间是斜杠。
不要命名为 GITHUB_DATA_REPO。

部署脚本会把 DATA_REPO 同时写进 Worker 的 DATA_REPO 和 GITHUB_DATA_REPO，这样无论代码读哪一个都能连上。

9. 第一次部署

Actions → Deploy glow-clock to Cloudflare → Run workflow → main。
等绿勾。黄字 Node.js 20 忽略。

成功后 Cloudflare → Workers 和 Pages 出现 Worker glow-clock。

10. Cloudflare 上的运行时变量

打开 Worker glow-clock：

  1. 顶栏点 Settings（不要点 Bindings 去加 D1）
  2. 找 Variables and Secrets / Runtime variables and secrets
  3. 确认或添加：
TypeNameValue
SecretGITHUB_TOKEN第 3 步 github_pat_…
TextDATA_REPO你的用户名/glow-clock-data
TextDATA_BRANCHmain
TextGITHUB_DATA_REPO与 DATA_REPO 相同（兼容旧代码）
  1. 控制台经常找不到 Save / Deploy。不要在 Bindings 里乱加东西。
    改完后回到 GitHub Actions 再 Run workflow 一次，新版本会带上 --var。
  2. Cloudflare 允许变量名 GITHUB_TOKEN；GitHub Actions 不允许。两处名字本来就可以不同。

11. 验收

  1. Worker 右上角 Visit，Ctrl+Shift+R 强制刷新
  2. 应看到辉光管时钟；副标题类似「数据仓库 你的用户名/glow-clock-data」
  3. 改时区，点「保存到数据仓库」
  4. 打开 https://github.com/你的用户名/glow-clock-data，刷新，应有 data/clock.json

两样都有，工作流才算打通。下次换别的网站，只换代码仓库里的源码，第 2–11 步的账号、Token、命名规则全部照抄。

以后日常

事做法
改网站推 glow-clock 的 main，Actions 自动部署
改数据网站里操作，或看数据仓库的 commit
PAT 过期第 3 步再生成；更新 Actions 的 DATA_GITHUB_TOKEN 和 Cloudflare 的 GITHUB_TOKEN，再跑一次 Actions
绑域名Worker → Domains

若网站需要 npm run build（本演示不需要）

在 Actions 里、wrangler 之前插入：

      - uses: actions/setup-node@v5
        with:
          node-version: "22"
          cache: npm
      - run: npm install
      - run: npm run build
        env:
          NITRO_PRESET: cloudflare_module   # 仅当项目用 Nitro / TanStack Start

注意：

  • 用 npm install，不要用 npm ci，除非你能保证 package-lock.json 与 package.json 完全同步。不同步会报 ajv@… does not satisfy。
  • Nitro 产物的 wrangler 配置在 .output/server/wrangler.json，部署命令加：
    --config .output/server/wrangler.json
  • 根目录自己写的 wrangler.jsonc 若没有 main 字段，直接 wrangler deploy 会失败。

故障对照

现象原因处理
Variable name cannot start with GITHUB_Actions Variable 起名违规改成 DATA_REPO / DATA_BRANCH
Failed to upload secretswrangler-action 用了 GITHUB_TOKEN删掉 secrets: 段；Token 只放 Cloudflare
npm ci / lock file not in synclock 过期本地 npm install 后提交 lock；或改用 npm install
网站提示未配置 GITHUB_DATA_REPO代码只认旧名字--var 同时写 DATA_REPO 与 GITHUB_DATA_REPO
Visit 仍是旧提示改了变量没重新部署再跑 Actions，强制刷新
Bindings 里在加 D1走错入口Cancel，去 Settings → Variables
找不到 Save and deploy新版控制台按钮不明显不要找；用 Actions 再部署
数据仓库没有 data/网站没连上，或还没点保存先看 Visit 页是否「已连接」，再点保存
Token 无效 / 找不到仓库PAT 没勾中数据仓库，或 DATA_REPO 写错重做第 3、8、10 步
网页上传后没有 .github隐藏目录没带上用 GitHub Desktop；或网页 Create new file，路径填 .github/workflows/deploy.yml
Node.js 20 is deprecated警告忽略

演示项目读哪些环境变量

examples/glow-clock/src/worker.js：

用途依次尝试
PATDATA_GITHUB_TOKEN，然后 GITHUB_TOKEN
仓库DATA_REPO，然后 GITHUB_DATA_REPO
分支DATA_BRANCH，然后 GITHUB_DATA_BRANCH，默认 main

写入路径：数据仓库里的 data/clock.json。

部署文件：examples/glow-clock/.github/workflows/deploy.yml。以后新项目可以整文件复制，只改 Worker 名称 wrangler.jsonc 里的 name。

Graph View