一句话理解#

GitHub Actions 是云端临时电脑；它把源码编译成 dist/，再让 Wrangler 上传 dist/ 到 Cloudflare Pages。

1
你在 Mac 修改博客
2
        |
3
        | git push origin main
4
        v
5
GitHub 仓库
6
        |
7
        | 触发 .github/workflows/deploy-pages.yml
8
        v
9
GitHub Actions Runner（临时 Linux）
10
  pnpm install --frozen-lockfile
11
  pnpm check
12
  pnpm build
13
        |
14
        | 上传 dist/
15
        v
16
Cloudflare Pages
17
        |
18
        +--> https://<项目名>.pages.dev
19
        |
20
        +--> https://enkiud.com

真实对象对照#

为什么不选“Connect to Git”#

Cloudflare Pages 还有一种 Git integration：Cloudflare 自己拉 GitHub 代码、自己构建。那确实更简单，但不是你要的“GitHub 自动打包，再部署到 Cloudflare”。

本章选择 Direct Upload + GitHub Actions，因此：

• 构建和检查日志都在 GitHub Actions。
• Cloudflare 只收到已经构建好的 dist/。
• 你可以先让 pnpm check 失败，阻止坏版本上线。
• 不要同时把同一个 Pages 项目设置成 Connect to Git，否则会有两套自动部署来源。

Cloudflare 当前文档明确说明：Direct Upload 与 Git integration 不能在同一项目中互相切换。新项目一开始就选对。

检查点#

• 我知道上传到 Cloudflare 的不是整个源码仓库，而是 dist/。
• 我知道 pnpm build 失败时，后面的上传步骤不会执行。
• 我知道本章创建的是 Direct Upload Pages 项目，不是 Connect to Git 项目。

你当前为什么不能直接把博客绑到根域名#

你之前的 Cloudflare Tunnel 日志里，TEI 的 Published application 使用过：

1
enkiud.com -> http://127.0.0.1:8080

一个 hostname 不能同时指向 Tunnel 和 Pages。若这个配置仍然存在，直接把 enkiud.com 绑定到 Pages 会冲突，或者博客 / TEI 其中一个无法访问。

正确的域名职责#

1
enkiud.com        -> Cloudflare Pages -> 个人博客
2
embed.enkiud.com  -> Cloudflare Tunnel -> Fedora TEI -> 127.0.0.1:8080

embed.enkiud.com 是单层子域名，专门给 Dify 调用向量模型；根域名留给博客。这样访问者和 Dify 的流量互不干扰。

在 Cloudflare Dashboard 修改 Tunnel 路由#

先在浏览器打开 Cloudflare Dashboard：

1. 进入 Networking -> Tunnels。

2. 打开你的 tei-fedora Tunnel。

3. 进入 Published applications。

4. 编辑原来 hostname 为 enkiud.com 的那一项。

5. hostname 改为：

   1
   embed.enkiud.com
   

6. Service 保持：

   1
   http://127.0.0.1:8080
   

7. 保存后，等待 Tunnel 配置同步。

验证 TEI 没有被改坏#

在 Fedora 上运行。不要把真实 Key 写进命令历史：

1
read -rsp 'TEI API Key: ' TEI_API_KEY
2
echo
3

4
curl https://embed.enkiud.com/info \
5
  -H "Authorization: Bearer $TEI_API_KEY"
6

7
unset TEI_API_KEY

预期：返回模型信息 JSON。之后到 Dify 的 Text Embedding Inference Provider，把服务器 URL 从 https://enkiud.com 改为：

1
https://embed.enkiud.com

检查点#

• https://embed.enkiud.com/info 能返回 TEI JSON。
• Dify 的 TEI Provider 已改为 https://embed.enkiud.com。
• enkiud.com 不再是 Tunnel 的 Published application hostname。

这一步会短暂改变 Dify 访问 TEI 的地址。先确认新地址成功，再继续绑定博客域名。

一句话理解#

GitHub Actions 会跑和你本机相同的两条质量命令；本机都过不了，云端也不会神奇地通过。

进入博客项目：

1
cd /Users/enkidu/personal-blog
2
pnpm check
3
pnpm build

当前项目应满足：

1
pnpm check  -> 0 errors, 0 warnings
2
pnpm build  -> 生成 dist/ 和 Pagefind 搜索索引

dist/ 是什么#

dist/ 是 Astro 构建后的发布目录。里面有浏览器真正需要的 HTML、CSS、JavaScript、图片和 Pagefind 搜索文件。

它是可再生产物：每次 pnpm build 都会重新生成。因此：

• 上传时传 dist/。
• 不要手动编辑 dist/。
• 不要把 dist/ 提交到 Git。

Fuwari 的 .gitignore 应已忽略它。检查：

1
git status --short

预期：构建后不应看到一大批 dist/ 文件。

1. 在 GitHub 创建空仓库#

浏览器进入 GitHub，点击右上角 + -> New repository：

创建后，GitHub 会显示一个仓库地址，例如：

1
[email protected]:你的用户名/personal-blog.git

2. 在本机提交并推送#

先确认当前分支是 main：

1
cd /Users/enkidu/personal-blog
2
git branch --show-current

预期输出：

1
main

然后执行下面命令。把仓库地址换成 GitHub 刚才给你的 SSH 地址：

1
git add -A
2
git commit -m "feat: publish Fuwari learning blog"
3
git remote add origin [email protected]:你的用户名/personal-blog.git
4
git push -u origin main

常见坑#

检查点#

在 GitHub 仓库网页刷新后，应能看到：

• src/、public/、package.json、pnpm-lock.yaml。
• 65 篇博客文章位于 src/content/posts/。
• 没有 .env、API Key、node_modules/ 或 dist/。

一句话理解#

Pages 项目是 Cloudflare 记录部署、生成 pages.dev 地址、绑定自定义域名的容器。它不是 GitHub 仓库本身。

本章使用项目名：

1
enkidu-blog

对应的初始地址会是：

1
https://enkidu-blog.pages.dev

用 Wrangler 创建空项目（推荐）#

这条命令只创建 Cloudflare Pages 项目，不会上传博客。首次会打开浏览器要求你登录 Cloudflare 并授权 Wrangler。

1
cd /Users/enkidu/personal-blog
2
pnpm dlx wrangler pages project create enkidu-blog --production-branch main

成功后，在 Cloudflare Dashboard 的 Workers & Pages 中能看到 enkidu-blog。

确认项目存在：

1
pnpm dlx wrangler pages project list

为什么此处不是 Dashboard 的“Connect to Git”#

不要点：

1
Create application -> Pages -> Connect to Git

那会创建 Cloudflare 自己构建源码的 Git integration 项目，和本章的 GitHub Actions 构建链路不是同一个模式。

如果你偏要在 Dashboard 创建 Direct Upload 项目，也应选择类似：

1
Create application -> Get started -> Drag and drop your files

但你不需要真的拖拽 dist/。创建好项目后，后续第一次发布交给 GitHub Actions。

检查点#

• Cloudflare Dashboard 的 Workers & Pages 列表中有 enkidu-blog。
• 它是 Direct Upload 项目，不是 Connect to Git 项目。
• 生产分支是 main。

心智模型#

API Token 是 GitHub Actions 代表你调用 Cloudflare Pages API 的临时通行证。它不是 Cloudflare 登录密码，也不是 TEI API Key。

在 Cloudflare Dashboard 操作#

1. 右上角头像 -> My Profile -> API Tokens。

2. 点击 Create Token。

3. 在 Custom Token 下点击 Get started。

4. Token name 填：

github-actions-pages-enkiud-blog

1
5. 在 Permissions 新增一条：
2

3
```text
4
Account -> Cloudflare Pages -> Edit

6. Account Resources 选择你的 Cloudflare 账户；不要选不相关账户。
7. 点击 Continue to summary -> Create Token。
8. 复制 Token。它只显示这一次。

不要使用 Global API Key，也不要把 Token 放进 .env、Markdown、截图、聊天记录或 Git 提交。GitHub Secrets 才是它应在的位置。

找到 Account ID#

打开 Cloudflare 中的 enkiud.com Zone Overview，右侧 API 区域可以找到 Account ID。

Account ID 不是秘密，但本章仍把它放进 GitHub Secret，避免工作流里混入账户配置值。

检查点#

• Token 权限只有账户级 Cloudflare Pages: Edit。
• 我已安全保存 Token，但没有把它放进任何 Git 文件。
• 我已复制 Account ID。

真实对象#

secrets.CLOUDFLARE_API_TOKEN 不是变量名字符串，而是 GitHub 在工作流运行时才注入的真实凭据。仓库文件里只会保存这个引用，不会保存 Token 本身。

在 GitHub 仓库网页：

1. 进入 Settings -> Secrets and variables -> Actions。
2. 点击 New repository secret。
3. 创建下面两个 Secret：

保存后 GitHub 只显示 Secret 名字，不再显示值，这是正常的安全行为。

检查点#

仓库的 Actions secrets 列表中应正好看到：

1
CLOUDFLARE_ACCOUNT_ID
2
CLOUDFLARE_API_TOKEN

看不到值不代表没保存；GitHub 故意不让你再次查看。

在哪里创建#

在博客项目中新建：

1
/Users/enkidu/personal-blog/.github/workflows/deploy-pages.yml

粘贴以下内容。只需要修改一处：--project-name=enkidu-blog。若你第五关使用了不同项目名，就同步改成那个名字。

1
name: Deploy Astro blog to Cloudflare Pages
2

3
on:
4
  push:
5
    branches:
6
      - main
7
  workflow_dispatch:
8

9
concurrency:
10
  group: cloudflare-pages-production
11
  cancel-in-progress: true
12

13
permissions:
14
  contents: read
15
  deployments: write
16

17
jobs:
18
  deploy:
19
    name: Check, build, and deploy
20
    runs-on: ubuntu-latest
21

22
    steps:
23
      - name: Get source code
24
        uses: actions/checkout@v6
25

26
      - name: Set up pnpm
27
        uses: pnpm/action-setup@v4
28
        with:
29
          version: 11
30

31
      - name: Set up Node.js
32
        uses: actions/setup-node@v6
33
        with:
34
          node-version: 24
35
          cache: pnpm
36
          cache-dependency-path: pnpm-lock.yaml
37

38
      - name: Install dependencies
39
        run: pnpm install --frozen-lockfile
40

41
      - name: Check Astro types
42
        run: pnpm check
43

44
      - name: Build static site
45
        run: pnpm build
46

47
      - name: Upload dist to Cloudflare Pages
48
        id: deploy
49
        uses: cloudflare/wrangler-action@v3
50
        with:
51
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
52
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
53
          command: pages deploy dist --project-name=enkidu-blog --branch=main
54
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
55

56
      - name: Show deployment URL
57
        run: echo "${{ steps.deploy.outputs.deployment-url }}"

逐段解释#

为什么 dist/ 不需要 GitHub Artifact#

Artifact 是 GitHub Actions 在不同 job 之间传文件的机制。本工作流只有一个 deploy job：构建和上传都发生在同一台 Runner 上，所以直接把刚生成的 dist/ 交给 Wrangler 最简单。

以后若拆成 test、build、deploy 三个 job，才需要上传/下载 Artifact。当前不需要先学这个复杂度。

检查点#

• 工作流文件路径必须是 .github/workflows/deploy-pages.yml，不是项目根目录。
• project-name 与 Cloudflare Pages 项目名一致。
• YAML 里只出现 secrets.CLOUDFLARE_API_TOKEN，没有真实 Token。

最小排错表#

最终检查点#

1
https://enkiud.com                 -> Fuwari 博客首页
2
https://enkiud.com/archive/        -> 文章归档
3
https://enkiud.com/posts/course-30/ -> 一篇学习文章
4
https://embed.enkiud.com/info      -> TEI JSON（需要 Bearer Token）

最短流程#

你只需要在博客项目里修改 Markdown，然后：

1
cd /Users/enkidu/personal-blog
2
pnpm check
3
pnpm build
4
git add src/content/posts
5
git commit -m "docs: add learning note"
6
git push

推送到 main 后：

1
GitHub Actions 自动检查 -> 自动构建 -> 自动上传 -> enkiud.com 更新

一个很实用的发布习惯#

每次准备上线前，先本机跑：

1
pnpm check && pnpm build

这样错误会在你的 Mac 上出现，而不是等 GitHub Runner 跑完一轮才发现。GitHub Actions 仍保留同样的检查，是为了防止“忘记本地验证”的提交直接上线。