内容分离
约 2180 字大约 7 分钟
2025-11-20
本指南详细说明如何在 Mizuki 中使用内容分离功能,包括基础配置、私有仓库、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模式切换
从本地切换到独立仓库
- 创建内容仓库 (参考 CONTENT_MIGRATION.md)
- 编辑
.env:ENABLE_CONTENT_SYNC=true CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git - 同步内容:
pnpm run sync-content
从独立仓库切换回本地
- 编辑
.env:ENABLE_CONTENT_SYNC=false - 直接开发:
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.pubGitHub:
- 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.git4. 测试连接
# 测试 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 文件不生效
检查清单:
文件位置正确 (项目根目录)
ls -la .env # Linux/Mac dir .env # Windows文件格式正确
# ✅ 正确 ENABLE_CONTENT_SYNC=true # ❌ 错误 (多余空格) ENABLE_CONTENT_SYNC = true # ❌ 错误 (不需要引号,除非值中有空格) ENABLE_CONTENT_SYNC="true"文件权限可读
chmod 644 .env # Linux/Mac运行检查命令
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 已正确添加
💡 最佳实践
新手建议
- 从本地模式开始 - 不需要额外配置,立即可用
- 内容稳定后再分离 - 等内容积累到一定程度
- 使用 SSH 方式 - 比 Token 更安全方便
进阶用户
- 使用独立仓库模式 - 清晰的版本控制
- 内容仓库添加 CI - 自动检查文章格式、图片优化等
- 分支管理 - main 分支用于生产,develop 用于预览
团队协作
- 统一环境变量 - 团队成员使用相同的配置
- 权限控制 - 内容仓库设置为私有,精细控制访问权限
- Git Hooks - 提交前检查文章格式、图片大小等
🤝 需要帮助?
- 查看 GitHub Issues
- 运行
pnpm run check-env检查配置
祝你使用愉快! 🎉