blog-code/docs/CONTENT_SEPARATION.md

Mizuki 内容分离完整指南

本指南详细说明如何在 Mizuki 中使用内容分离功能,包括基础配置、私有仓库、CI/CD 部署等所有场景。

📖 目录

• 快速开始
• ENABLE_CONTENT_SYNC 控制开关
• 配置方式
• 私有仓库
• CI/CD 部署
• 常用命令
• 故障排查

---

🚀 快速开始

新手推荐: 本地模式 (最简单)

不需要任何配置,直接开始使用:

# 克隆项目
git clone https://github.com/matsuzaka-yuki/Mizuki.git
cd Mizuki

# 安装依赖
pnpm install

# 直接开发
pnpm dev

内容存放在 src/content/ 和 public/images/ 目录,与代码一起管理。

进阶: 启用内容分离

如果需要将内容独立管理(多人协作、私有内容、独立版本控制),按以下步骤配置:

# 1. 创建 .env 文件
cp .env.example .env

# 2. 编辑 .env,启用内容分离
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

# 3. 同步内容
pnpm run sync-content

# 4. 启动开发
pnpm dev

---

🎛️ ENABLE_CONTENT_SYNC 控制开关

功能说明

ENABLE_CONTENT_SYNC 是一个一键开关,控制是否启用内容分离功能。

值	说明	适用场景
false 或未设置	禁用内容分离 (默认)	新手、个人博客、内容较少
true	启用内容分离	团队协作、私有内容、大量文章

配置位置

在项目根目录的 .env 文件中:

# 禁用内容分离 (使用本地内容)
ENABLE_CONTENT_SYNC=false

# 或启用内容分离 (从远程仓库同步)
ENABLE_CONTENT_SYNC=true

使用场景对比

场景 1: 本地模式 (推荐新手)

特点:

• ✅ 无需额外配置
• ✅ 内容和代码一起管理
• ✅ 适合个人博客、小型项目

配置:

# .env (或不创建 .env 文件)
ENABLE_CONTENT_SYNC=false

工作流程:

# 直接编辑 src/content/ 下的文章
pnpm dev

# 提交时一起提交代码和内容
git add .
git commit -m "Update content"
git push

场景 2: 独立仓库（分离）模式

特点:

• ✅ 内容独立仓库管理
• ✅ 支持私有内容仓库
• ✅ 多人协作方便
• ✅ 独立的内容版本控制

配置:

# .env
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

工作流程:

# 自动同步内容后启动
pnpm dev

# 内容在独立仓库编辑
cd /path/to/Mizuki-Content
# 编辑文章
git add .
git commit -m "Update article"
git push

模式切换

从本地切换到独立仓库

1. 创建内容仓库 (参考 CONTENT_MIGRATION.md)
2. 编辑 .env:

   ENABLE_CONTENT_SYNC=true
   CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
   

3. 同步内容: pnpm run sync-content

从独立仓库切换回本地

1. 编辑 .env:

   ENABLE_CONTENT_SYNC=false
   

2. 直接开发: pnpm dev

---

⚙️ 配置方式

环境变量说明

在 .env 文件中配置:

# ============================================
# 功能开关
# ============================================

# 是否启用内容分离功能
# false = 使用本地内容 (推荐新手)
# true = 从远程仓库同步内容
ENABLE_CONTENT_SYNC=false

# ============================================
# 内容仓库配置 (仅当 ENABLE_CONTENT_SYNC=true 时需要)
# ============================================

# 内容仓库地址
# 支持 HTTPS 和 SSH 方式
# 公开仓库: https://github.com/username/repo.git
# 私有仓库 (SSH): git@github.com:username/repo.git
# 私有仓库 (Token): https://TOKEN@github.com/username/repo.git
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

# 内容目录路径 (默认 ./content 一般无需改动)
CONTENT_DIR=./content

配置示例

示例 1: 完全本地 (最简单)

# .env
ENABLE_CONTENT_SYNC=false

或者不创建 .env 文件,直接使用本地内容。

示例 2: 公开仓库 (HTTPS)

# .env
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

示例 3: 私有仓库 (SSH)

# .env
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git

---

🔄 自动构建触发 (内容更新时)

问题

启用内容分离后，默认只有代码仓库更新会触发部署，内容仓库更新不会自动触发。

解决方案

推荐使用 Repository Dispatch，5 步快速配置，适用所有部署平台。

详细步骤请查看:

• 自动构建触发快速参考 - 最简洁的配置指南 ⭐
• 部署文档 - 完整说明 - 包含多种方案
• 内容仓库配置指南 - 工作流详细说明

---

🔐 私有仓库配置

完全支持私有内容仓库! 推荐使用 SSH 方式,安全且方便。

方案 A: SSH 密钥 (推荐)

1. 生成 SSH 密钥

# 推荐使用 Ed25519
ssh-keygen -t ed25519 -C "your_email@example.com"

# 或使用 RSA
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

按提示操作,默认保存到 ~/.ssh/id_ed25519。

2. 添加公钥到 Git 平台

# 查看公钥
cat ~/.ssh/id_ed25519.pub

# Windows PowerShell
Get-Content ~/.ssh/id_ed25519.pub

GitHub:

• Settings → SSH and GPG keys → New SSH key
• 粘贴公钥内容

GitLab:

• Preferences → SSH Keys → Add new key

Gitee:

• 设置 → SSH 公钥 → 添加公钥

3. 配置 Mizuki

在 .env 文件中使用 SSH URL:

ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git

4. 测试连接

# 测试 GitHub 连接
ssh -T git@github.com

# 测试 GitLab 连接
ssh -T git@gitlab.com

# 同步内容
pnpm run sync-content

方案 B: HTTPS + Personal Access Token

1. 生成 Token

GitHub:

• Settings → Developer settings → Personal access tokens → Generate new token
• 权限: 勾选 repo (完整访问)

GitLab:

• Preferences → Access Tokens
• Scopes: read_repository

Gitee:

• 设置 → 私人令牌 → 生成新令牌
• 权限: projects (读取)

2. 配置 .env

ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://YOUR_TOKEN@github.com/your-username/Mizuki-Content-Private.git

⚠️ 安全提示:

• 不要将 .env 提交到 Git! (已在 .gitignore 中)
• Token 具有完整权限,请妥善保管

---

🌐 CI/CD 部署

快速配置

所有部署平台都使用相同的自动同步机制:

• ✅ pnpm build 执行前自动运行 prebuild 钩子
• ✅ 根据 ENABLE_CONTENT_SYNC 决定是否同步内容
• ✅ 同步失败不会中断构建,回退到本地内容

只需配置环境变量,无需修改构建命令!

环境变量配置

在部署平台添加以下环境变量:

变量名	值	说明
ENABLE_CONTENT_SYNC	true	启用内容分离
CONTENT_REPO_URL	仓库地址	内容仓库的 URL

支持的平台

• ✅ GitHub Pages - 使用 GitHub Actions
• ✅ Vercel - 环境变量配置
• ✅ Netlify - 环境变量配置
• ✅ Cloudflare Pages - 环境变量配置

详细配置指南

不同平台的具体配置步骤、私有仓库认证、故障排查等详细信息，请查看：

📖 部署指南 - 完整的部署文档，包含：

• GitHub Pages 自动部署配置
• Vercel 部署详细步骤
• Netlify 部署配置
• Cloudflare Pages 部署
• 私有仓库认证配置
• 常见问题故障排查

---

📋 常用命令

命令	说明
pnpm run init-content	运行交互式初始化向导
pnpm run sync-content	手动同步内容仓库
pnpm run check-env	检查环境变量配置
pnpm dev	启动开发服务器 (自动同步)
pnpm build	构建项目 (自动同步)

自动同步时机

当 ENABLE_CONTENT_SYNC=true 时,以下命令会自动同步内容:

• pnpm dev - 开发前自动同步
• pnpm build - 构建前自动同步

同步失败不会中断开发,会显示警告并继续。

---

🔍 故障排查

问题 1: 提示 "未启用内容分离功能"

原因: ENABLE_CONTENT_SYNC 未设置或设置为 false。

解决:

# 检查 .env 文件
cat .env

# 确认有以下配置
ENABLE_CONTENT_SYNC=true

问题 2: 提示 "未设置 CONTENT_REPO_URL"

原因: 启用了内容分离但未配置仓库地址。

解决:

# 在 .env 中添加
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

问题 3: 私有仓库认证失败

SSH 方式:

# 测试 SSH 连接
ssh -T git@github.com

# 应该看到: Hi username! You've successfully authenticated...

如果失败,检查:

• SSH 密钥是否生成: ls ~/.ssh/
• 公钥是否添加到 GitHub
• SSH agent 是否运行: ssh-add -l

HTTPS + Token 方式:

• 检查 Token 是否有效
• 检查 Token 权限是否正确 (repo 权限)
• 确认 URL 格式: https://TOKEN@github.com/user/repo.git

问题 4: .env 文件不生效

检查清单:

1. 文件位置正确 (项目根目录)

   ls -la .env  # Linux/Mac
   dir .env     # Windows
   

2. 文件格式正确

   # ✅ 正确
   ENABLE_CONTENT_SYNC=true
   
   # ❌ 错误 (多余空格)
   ENABLE_CONTENT_SYNC = true
   
   # ❌ 错误 (不需要引号,除非值中有空格)
   ENABLE_CONTENT_SYNC="true"
   

3. 文件权限可读

   chmod 644 .env  # Linux/Mac
   

4. 运行检查命令

   pnpm run check-env
   

问题 5: 内容同步失败

# 手动同步内容
pnpm run sync-content

# 检查内容目录
ls -la content/

# 手动克隆内容仓库
git clone https://github.com/your-username/Mizuki-Content.git content

问题 6: 部署时内容未同步

Vercel/Netlify:

• 确认环境变量已添加
• 检查构建日志,查看同步步骤是否执行
• 确认 Token 在部署环境有效

GitHub Actions:

• 检查工作流配置
• 查看 Actions 运行日志
• 确认 Secrets 已正确添加

---

💡 最佳实践

新手建议

1. 从本地模式开始 - 不需要额外配置,立即可用
2. 内容稳定后再分离 - 等内容积累到一定程度
3. 使用 SSH 方式 - 比 Token 更安全方便

进阶用户

1. 使用独立仓库模式 - 清晰的版本控制
2. 内容仓库添加 CI - 自动检查文章格式、图片优化等
3. 分支管理 - main 分支用于生产,develop 用于预览

团队协作

1. 统一环境变量 - 团队成员使用相同的配置
2. 权限控制 - 内容仓库设置为私有,精细控制访问权限
3. Git Hooks - 提交前检查文章格式、图片大小等

---

📚 相关文档

• 内容迁移指南 - 如何从单仓库迁移到分离模式
• 内容仓库结构 - 内容仓库的推荐结构
• 主 README - 项目总体说明

---

🤝 需要帮助?

• 查看 GitHub Issues
• 阅读 完整文档
• 运行 pnpm run check-env 检查配置

祝你使用愉快! 🎉