Mobile wallpaper 1Mobile wallpaper 2Mobile wallpaper 3Mobile wallpaper 4Mobile wallpaper 5Mobile wallpaper 6
1003 字
5 分钟
mizuki 内容分离 & 自动构建部署

🚀 Astro 博客全自动化部署指南 (双活/多活架构)#

核心目标

  1. 代码开源 (your-username.github.io),但内容私有 (Mizuki-Content)。
  2. 内容驱动:在私有仓库写文章,推送后自动触发主仓库构建。
  3. 多端同步:一次构建,同时发布到 GitHub Pages 和 Cloudflare Pages (及 Vercel)。

🛠️ 第一步:准备“万能钥匙” (Token)#

这是打通两个仓库权限的关键。

  1. 生成 Token
    • GitHub 头像 -> Settings -> Developer settings -> Personal access tokens (Classic)。
    • Scopes (权限):必须勾选 ✅ repo (Full control of private repositories)。
    • 复制生成的字符串 (例如 ghp_xxxx)。
  2. 存入 Secrets
    • 主仓库 (your-username.github.io) -> Settings -> Secrets -> Actions -> 新建 DISPATCH_TOKEN
    • 内容仓库 (Mizuki-Content) -> Settings -> Secrets -> Actions -> 新建 DISPATCH_TOKEN
    • 注:两个仓库填同一个 Token。

🔗 第二步:建立子模块关联#

在本地电脑操作,将私有内容仓库挂载到主仓库。

Bash

# 1. 确保 .gitignore 没有忽略 'content' 文件夹 (如果有,先删掉那一行)
# ⚠️ 错误提示:之前如果脚本生成过 content 文件夹,需先物理删除它,并清除 git 缓存。
# 2. 添加子模块 (使用你的私有仓库地址)
git submodule add https://github.com/your-username/Mizuki-Content.git content
# 3. 提交变更
git add .
git commit -m "feat: add content submodule"
git push

📡 第三步:配置“发信端” (内容仓库)#

告诉内容仓库:“我一更新,就去喊主仓库干活。”

Mizuki-Content/.github/workflows/trigger.yml 写入:

YAML

name: Trigger Main Repo Build
on:
push:
branches: [ main ] # ⚠️ 注意确认分支名是 main 还是 master
jobs:
trigger:
runs-on: ubuntu-latest
steps:
- name: Trigger repository dispatch
uses: peter-evans/repository-dispatch@v3
with:
token: ${{ secrets.DISPATCH_TOKEN }}
repository: your-username/repo # 你的主仓库
event-type: content-updated # 发送的信号暗号

🏗️ 第四步:配置“接收与构建端” (主仓库)#

告诉主仓库:“收到信号后,用 Token 拉取最新私有内容,构建并发布。”

your-username.github.io/.github/workflows/deploy.yml 写入:

YAML

name: Deploy to GitHub & Cloudflare
on:
push:
branches: [ main ]
repository_dispatch:
types: [ content-updated ] # 👈 监听来自内容仓库的信号
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
deployments: write
jobs:
build:
runs-on: ubuntu-latest
steps:
# 1. 检出代码 (关键:带权限、拉取子模块)
- name: Checkout Source Code
uses: actions/checkout@v4
with:
token: ${{ secrets.DISPATCH_TOKEN }} # ⚠️ 必须用 PAT,否则拉不到私有库
submodules: recursive
fetch-depth: 0
# 2. 强制同步最新内容 (关键:解决“不更新”问题)
- name: Force Update Content Submodule
run: |
git submodule update --remote --merge
- name: Install Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install pnpm
uses: pnpm/action-setup@v4
with:
version: 9
- name: Install Dependencies
run: pnpm install --frozen-lockfile
- name: Build Site
run: pnpm build
# 3. 上传构建产物 (dist)
- name: Upload build artifact
uses: actions/upload-artifact@v4
with:
name: dist-files
path: ./dist
# --- 部署任务区域 ---
# 部署到 GitHub Pages
deploy-github:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/download-artifact@v4
with: { name: dist-files, path: ./dist }
- uses: actions/upload-pages-artifact@v3
with: { path: ./dist }
- id: deployment
uses: actions/deploy-pages@v4
# 部署到 Cloudflare Pages
deploy-cloudflare:
needs: build
runs-on: ubuntu-latest
permissions:
contents: read
deployments: write
steps:
- uses: actions/download-artifact@v4
with: { name: dist-files, path: ./dist }
- uses: cloudflare/pages-action@v1
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
projectName: my-blog # ⚠️ Cloudflare 上的项目名
directory: ./dist
gitHubToken: ${{ secrets.GITHUB_TOKEN }}

☁️ 第五步:平台侧配置 (Cloudflare Pages)#

为了防止 Cloudflare 自己乱跑构建导致失败:

  1. 进入 Cloudflare Dashboard -> Pages -> Settings -> Builds & deployments。
  2. Build command: 填写 exit 0 (直接成功,不构建)。
  3. Build output directory: 填写 dist
  4. 提示:Cloudflare 后台的构建日志报错可以忽略,只要 GitHub Actions 全绿即可。

📝 避坑与错误总结 (Tips)#

  1. ❌ 错误:Repository not found
    • 原因:使用了默认的 GITHUB_TOKEN,它没有权限拉取其他私有仓库。
    • 修正:必须在 checkout 步骤使用 token: ${{ secrets.DISPATCH_TOKEN }}
  2. ❌ 错误:博客内容不更新
    • 原因git submodule 默认锁定在旧版本的 commit 上。
    • 修正:必须在 deploy.yml 构建前执行 git submodule update --remote --merge
  3. ❌ 错误:Cloudflare 报错 dist: not found 或构建失败
    • 原因:CF 试图运行 pnpm build 但环境不对,或者试图把 dist 当命令运行。
    • 修正:将 CF 后台构建命令改为 exit 0,让 GitHub Actions 负责把文件推过去。
  4. ❌ 错误:无法添加 submodule
    • 原因.gitignore 文件里写了 content,导致 Git 忽略了该文件夹。
    • 修正:从 .gitignore 中移除 content
mizuki 内容分离 & 自动构建部署
https://hcl55.github.io/posts/mizuki-content/
作者
雪银星月
发布于
2025-12-19
许可协议
CC BY-NC-SA 4.0

部分信息可能已经过时

封面
Sample Song
Sample Artist
封面
Sample Song
Sample Artist
0:00 / 0:00