1003 字
5 分钟
mizuki 内容分离 & 自动构建部署
🚀 Astro 博客全自动化部署指南 (双活/多活架构)
核心目标:
- 代码开源 (
your-username.github.io),但内容私有 (Mizuki-Content)。 - 内容驱动:在私有仓库写文章,推送后自动触发主仓库构建。
- 多端同步:一次构建,同时发布到 GitHub Pages 和 Cloudflare Pages (及 Vercel)。
🛠️ 第一步:准备“万能钥匙” (Token)
这是打通两个仓库权限的关键。
- 生成 Token:
- GitHub 头像 -> Settings -> Developer settings -> Personal access tokens (Classic)。
- Scopes (权限):必须勾选 ✅ repo (Full control of private repositories)。
- 复制生成的字符串 (例如
ghp_xxxx)。
- 存入 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 自己乱跑构建导致失败:
- 进入 Cloudflare Dashboard -> Pages -> Settings -> Builds & deployments。
- Build command: 填写
exit 0(直接成功,不构建)。 - Build output directory: 填写
dist。 - 提示:Cloudflare 后台的构建日志报错可以忽略,只要 GitHub Actions 全绿即可。
📝 避坑与错误总结 (Tips)
- ❌ 错误:Repository not found
- 原因:使用了默认的
GITHUB_TOKEN,它没有权限拉取其他私有仓库。 - 修正:必须在
checkout步骤使用token: ${{ secrets.DISPATCH_TOKEN }}。
- 原因:使用了默认的
- ❌ 错误:博客内容不更新
- 原因:
git submodule默认锁定在旧版本的 commit 上。 - 修正:必须在
deploy.yml构建前执行git submodule update --remote --merge。
- 原因:
- ❌ 错误:Cloudflare 报错 dist: not found 或构建失败
- 原因:CF 试图运行
pnpm build但环境不对,或者试图把dist当命令运行。 - 修正:将 CF 后台构建命令改为
exit 0,让 GitHub Actions 负责把文件推过去。
- 原因:CF 试图运行
- ❌ 错误:无法添加 submodule
- 原因:
.gitignore文件里写了content,导致 Git 忽略了该文件夹。 - 修正:从
.gitignore中移除content。
- 原因:
mizuki 内容分离 & 自动构建部署
https://hcl55.github.io/posts/mizuki-content/ 部分信息可能已经过时









