111

docs/AUTO_BUILD_TRIGGER.md

@@ -0,0 +1,125 @@
+# 内容仓库更新自动触发构建 - 快速参考
+
+## 🎯 问题
+
+启用内容分离后,内容仓库 (Mizuki-Content) 更新不会自动触发代码仓库 (Mizuki) 的重新部署。
+
+## ✅ 解决方案 (推荐)
+
+使用 **Repository Dispatch** 让内容更新时自动触发构建,适用于所有部署平台。
+
+---
+
+## 📝 5 步快速配置
+
+### Step 1: 创建 GitHub Token
+
+访问: https://github.com/settings/tokens
+
+- 点击 **Generate new token (classic)**
+- Note: `Mizuki Content Trigger`
+- Scopes: 勾选 ✅ `repo`
+- 点击生成并**复制 Token** ⚠️ (只显示一次)
+
+### Step 2: 添加 Secret
+
+在**内容仓库** (Mizuki-Content):
+
+Settings → Secrets and variables → Actions → New repository secret
+
+- Name: `DISPATCH_TOKEN`
+- Secret: 粘贴刚才的 Token
+
+### Step 3: 修改触发器配置
+
+编辑内容仓库的 `.github/workflows/trigger-build.yml`
+
+找到第 27 行,修改为你的代码仓库:
+
+```yaml
+repository: your-username/Mizuki  # 改为你的
+```
+
+例如: `matsuzaka-yuki/Mizuki`
+
+### Step 4: 更新代码仓库工作流
+
+编辑**代码仓库**的 `.github/workflows/deploy.yml`
+
+在 `on:` 部分添加:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+  repository_dispatch:  # 👈 添加这个
+    types:
+      - content-updated
+  workflow_dispatch:
+```
+
+### Step 5: 测试
+
+在内容仓库推送一次:
+
+```bash
+git add .
+git commit -m "test: trigger build"
+git push
+```
+
+查看:
+1. 内容仓库 Actions - 确认触发器运行
+2. 代码仓库 Actions - 确认部署被触发
+
+---
+
+## 🔍 故障排查
+
+### Token 问题
+
+**错误**: `Bad credentials`
+
+**解决**:
+- 确认 Token 复制完整
+- 确认 Token 有 `repo` 权限
+- 重新生成 Token
+
+### 仓库名称问题
+
+**错误**: `Not Found`
+
+**解决**:
+- 确认格式: `owner/repo` (用斜杠分隔)
+- 确认拼写正确
+- 示例: `matsuzaka-yuki/Mizuki`
+
+### 代码仓库未触发
+
+**检查**:
+- [ ] `.github/workflows/deploy.yml` 包含 `repository_dispatch`
+- [ ] Event type 为 `content-updated`
+- [ ] 代码仓库 Actions 已启用
+
+---
+
+## 📚 详细文档
+
+需要更多配置选项? 查看:
+- [部署指南 - 完整说明](./DEPLOYMENT.md#内容仓库更新触发构建) - 包含 Webhook、定时构建等其他方案
+- [内容仓库配置指南](../Mizuki-Content/.github/workflows/README.md) - 工作流详细说明
+
+---
+
+## 💡 提示
+
+配置成功后:
+- ✅ 内容仓库每次推送都会自动触发部署
+- ✅ 可在 Actions 页面查看触发历史
+- ✅ 支持手动触发 (workflow_dispatch)
+
+---
+
+**配置时间**: 约 5 分钟  
+**一次配置,长期有效** ✨

docs/CONTENT_REPOSITORY.md

@@ -0,0 +1,255 @@
+# Mizuki 内容仓库结构说明
+
+本文档说明如何创建和组织 Mizuki 博客的内容仓库。
+
+## 📁 推荐的目录结构
+
+```
+Mizuki-Content/
+├── posts/              # 博客文章
+│   ├── post-1.md
+│   ├── post-2.md
+│   └── my-article/
+│       ├── index.md
+│       └── cover.jpg
+├── spec/               # 特殊页面
+│   ├── about.md
+│   └── friends.md
+├── data/               # 数据文件
+│   ├── anime.ts
+│   ├── projects.ts
+│   ├── skills.ts
+│   └── timeline.ts
+├── images/             # 图片资源
+│   ├── albums/         # 相册图片
+│   ├── diary/          # 日记图片
+│   └── posts/          # 文章图片
+└── README.md
+```
+
+## 🚀 快速开始
+
+### 1. 创建新的内容仓库
+
+```bash
+# 创建新仓库
+mkdir Mizuki-Content
+cd Mizuki-Content
+git init
+
+# 创建基本目录结构
+mkdir -p posts spec data images/albums images/diary images/posts
+
+# 创建 README
+echo "# Mizuki 博客内容" > README.md
+```
+
+### 2. 从现有 Mizuki 项目迁移内容
+
+如果你已经有一个 Mizuki 项目,可以将内容迁移到新仓库:
+
+```bash
+# 在 Mizuki 项目根目录执行
+cd /path/to/Mizuki
+
+# 复制内容到新仓库
+cp -r src/content/posts/* /path/to/Mizuki-Content/posts/
+cp -r src/content/spec/* /path/to/Mizuki-Content/spec/
+cp -r src/data/* /path/to/Mizuki-Content/data/
+cp -r public/images/* /path/to/Mizuki-Content/images/
+```
+
+### 3. 提交到 Git
+
+```bash
+cd /path/to/Mizuki-Content
+
+git add .
+git commit -m "Initial commit: Add blog content"
+
+# 添加远程仓库并推送
+git remote add origin https://github.com/your-username/Mizuki-Content.git
+git branch -M main
+git push -u origin main
+```
+
+## 🔗 连接到 Mizuki 代码仓库
+
+### 方式一: Git Submodule (推荐)
+
+在 Mizuki 代码仓库中:
+
+```bash
+cd /path/to/Mizuki
+
+# 添加内容仓库作为 submodule
+git submodule add https://github.com/your-username/Mizuki-Content.git content
+
+# 提交 submodule 配置
+git add .gitmodules content
+git commit -m "Add content repository as submodule"
+git push
+```
+
+配置环境变量 `.env`:
+
+```bash
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=true
+```
+
+### 方式二: 独立仓库模式
+
+配置环境变量 `.env`:
+
+```bash
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+CONTENT_DIR=./content
+USE_SUBMODULE=false
+```
+
+然后运行同步:
+
+```bash
+pnpm run sync-content
+```
+
+## 📝 内容编写指南
+
+### 文章前言 (Frontmatter)
+
+每篇文章都应该包含以下前言:
+
+```yaml
+---
+title: 文章标题
+published: 2024-01-01
+description: 文章描述
+image: ./cover.jpg
+tags: [标签1, 标签2]
+category: 分类
+draft: false
+pinned: false
+lang: zh-CN
+---
+```
+
+### 目录组织
+
+- **单文件文章**: 直接在 `posts/` 目录下创建 `.md` 文件
+- **包含图片的文章**: 创建文件夹,将 `index.md` 和图片放在一起
+
+示例:
+```
+posts/
+├── simple-post.md                    # 简单文章
+└── complex-post/                     # 复杂文章
+    ├── index.md                      # 文章内容
+    ├── cover.jpg                     # 封面图
+    └── diagram.png                   # 文章中的图片
+```
+
+## 🔄 更新工作流
+
+### 本地开发
+
+1. 修改内容仓库中的文件
+2. 提交并推送更改
+3. 在代码仓库中同步内容:
+   ```bash
+   cd /path/to/Mizuki
+   pnpm run sync-content
+   ```
+
+### 使用 Submodule 时
+
+```bash
+# 更新 submodule
+cd /path/to/Mizuki
+git submodule update --remote --merge
+
+# 或者使用同步脚本
+pnpm run sync-content
+```
+
+### 部署时自动同步
+
+在 CI/CD 配置中添加:
+
+```yaml
+- name: Sync Content
+  run: pnpm run sync-content
+  env:
+    CONTENT_REPO_URL: ${{ secrets.CONTENT_REPO_URL }}
+    USE_SUBMODULE: true
+```
+
+## 📦 数据文件说明
+
+### anime.ts
+番剧数据配置,包含你观看的动画列表。
+
+### projects.ts
+项目展示数据,展示你的作品集。
+
+### skills.ts
+技能数据,展示你的技术栈。
+
+### timeline.ts
+时间线数据,记录重要事件。
+
+## 🎨 图片管理
+
+### 目录说明
+
+- `images/albums/`: 相册页面的图片
+- `images/diary/`: 日记页面的图片  
+- `images/posts/`: 文章中引用的公共图片
+
+### 图片引用
+
+在文章中引用图片:
+
+```markdown
+<!-- 相对路径 (推荐) -->
+![描述](./image.jpg)
+
+<!-- 公共图片目录 -->
+![描述](/images/posts/image.jpg)
+```
+
+## ⚠️ 注意事项
+
+1. **不要**在内容仓库中包含代码文件
+2. **保持**目录结构与主仓库一致
+3. **定期**备份重要内容
+4. **使用** Git LFS 管理大型图片文件(可选)
+
+## 🔐 私有内容仓库
+
+如果你的内容仓库是私有的，需要配置访问权限。详细的配置方法请参考：
+
+- [内容分离完整指南 - 私有仓库配置](./CONTENT_SEPARATION.md#-私有仓库配置)
+- [部署指南](./DEPLOYMENT.md) - 各平台的私有仓库部署配置
+
+### 快速参考
+
+**本地开发**: 推荐使用 SSH 密钥
+```bash
+CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
+USE_SUBMODULE=true
+```
+
+**CI/CD 部署**: 根据平台选择
+- GitHub Actions: 使用 `GITHUB_TOKEN` (同账号) 或 SSH 密钥
+- Vercel/Netlify: 授权访问或使用 Token
+
+## 📚 参考资源
+
+- [Git Submodule 文档](https://git-scm.com/book/zh/v2/Git-%E5%B7%A5%E5%85%B7-%E5%AD%90%E6%A8%A1%E5%9D%97)
+- [Mizuki 文档](https://docs.mizuki.mysqil.com/)
+- [Astro Content Collections](https://docs.astro.build/zh-cn/guides/content-collections/)
+
+---
+
+💡 **提示**: 建议先在本地测试内容同步流程,确保一切正常后再配置自动化部署。

docs/CONTENT_SEPARATION.md

@@ -0,0 +1,525 @@
+# Mizuki 内容分离完整指南
+
+本指南详细说明如何在 Mizuki 中使用内容分离功能,包括基础配置、私有仓库、CI/CD 部署等所有场景。
+
+## 📖 目录
+
+- [快速开始](#-快速开始)
+- [ENABLE_CONTENT_SYNC 控制开关](#-enable_content_sync-控制开关)
+- [配置方式](#-配置方式)
+- [私有仓库](#-私有仓库配置)
+- [CI/CD 部署](#-cicd-部署)
+- [常用命令](#-常用命令)
+- [故障排查](#-故障排查)
+
+---
+
+## 🚀 快速开始
+
+### 新手推荐: 本地模式 (最简单)
+
+**不需要任何配置**,直接开始使用:
+
+```bash
+# 克隆项目
+git clone https://github.com/matsuzaka-yuki/Mizuki.git
+cd Mizuki
+
+# 安装依赖
+pnpm install
+
+# 直接开发
+pnpm dev
+```
+
+内容存放在 `src/content/` 和 `public/images/` 目录,与代码一起管理。
+
+### 进阶: 启用内容分离
+
+如果需要将内容独立管理(多人协作、私有内容、独立版本控制),按以下步骤配置:
+
+```bash
+# 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` 文件中:
+
+```bash
+# 禁用内容分离 (使用本地内容)
+ENABLE_CONTENT_SYNC=false
+
+# 或启用内容分离 (从远程仓库同步)
+ENABLE_CONTENT_SYNC=true
+```
+
+### 使用场景对比
+
+#### 场景 1: 本地模式 (推荐新手)
+
+**特点**:
+- ✅ 无需额外配置
+- ✅ 内容和代码一起管理
+- ✅ 适合个人博客、小型项目
+
+**配置**:
+```bash
+# .env (或不创建 .env 文件)
+ENABLE_CONTENT_SYNC=false
+```
+
+**工作流程**:
+```bash
+# 直接编辑 src/content/ 下的文章
+pnpm dev
+
+# 提交时一起提交代码和内容
+git add .
+git commit -m "Update content"
+git push
+```
+
+#### 场景 2: 独立仓库（分离）模式
+
+**特点**:
+- ✅ 内容独立仓库管理
+- ✅ 支持私有内容仓库
+- ✅ 多人协作方便
+- ✅ 独立的内容版本控制
+
+**配置**:
+```bash
+# .env
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+```
+
+**工作流程**:
+```bash
+# 自动同步内容后启动
+pnpm dev
+
+# 内容在独立仓库编辑
+cd /path/to/Mizuki-Content
+# 编辑文章
+git add .
+git commit -m "Update article"
+git push
+```
+
+### 模式切换
+
+#### 从本地切换到独立仓库
+
+1. 创建内容仓库 (参考 [CONTENT_MIGRATION.md](./CONTENT_MIGRATION.md))
+2. 编辑 `.env`:
+   ```bash
+   ENABLE_CONTENT_SYNC=true
+   CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+   ```
+3. 同步内容: `pnpm run sync-content`
+
+#### 从独立仓库切换回本地
+
+1. 编辑 `.env`:
+   ```bash
+   ENABLE_CONTENT_SYNC=false
+   ```
+2. 直接开发: `pnpm dev`
+
+---
+
+## ⚙️ 配置方式
+
+### 环境变量说明
+
+在 `.env` 文件中配置:
+
+```bash
+# ============================================
+# 功能开关
+# ============================================
+
+# 是否启用内容分离功能
+# 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: 完全本地 (最简单)
+
+```bash
+# .env
+ENABLE_CONTENT_SYNC=false
+```
+
+或者**不创建 `.env` 文件**,直接使用本地内容。
+
+#### 示例 2: 公开仓库 (HTTPS)
+
+```bash
+# .env
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+```
+
+#### 示例 3: 私有仓库 (SSH)
+
+```bash
+# .env
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
+```
+
+---
+
+## 🔄 自动构建触发 (内容更新时)
+
+### 问题
+
+启用内容分离后，默认只有代码仓库更新会触发部署，内容仓库更新**不会**自动触发。
+
+### 解决方案
+
+**推荐使用 Repository Dispatch**，5 步快速配置，适用所有部署平台。
+
+详细步骤请查看:
+- **[自动构建触发快速参考](./AUTO_BUILD_TRIGGER.md)** - 最简洁的配置指南 ⭐
+- **[部署文档 - 完整说明](./DEPLOYMENT.md#内容仓库更新触发构建)** - 包含多种方案
+- **[内容仓库配置指南](../Mizuki-Content/.github/workflows/README.md)** - 工作流详细说明
+
+---
+
+## 🔐 私有仓库配置
+
+完全支持私有内容仓库! 推荐使用 SSH 方式,安全且方便。
+
+### 方案 A: SSH 密钥 (推荐)
+
+#### 1. 生成 SSH 密钥
+
+```bash
+# 推荐使用 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 平台
+
+```bash
+# 查看公钥
+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:
+
+```bash
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=git@github.com:your-username/Mizuki-Content-Private.git
+```
+
+#### 4. 测试连接
+
+```bash
+# 测试 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
+
+```bash
+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** - 环境变量配置
+
+### 详细配置指南
+
+不同平台的具体配置步骤、私有仓库认证、故障排查等详细信息，请查看：
+
+📖 **[部署指南](./DEPLOYMENT.md)** - 完整的部署文档，包含：
+- 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`。
+
+**解决**:
+```bash
+# 检查 .env 文件
+cat .env
+
+# 确认有以下配置
+ENABLE_CONTENT_SYNC=true
+```
+
+### 问题 2: 提示 "未设置 CONTENT_REPO_URL"
+
+**原因**: 启用了内容分离但未配置仓库地址。
+
+**解决**:
+```bash
+# 在 .env 中添加
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+```
+
+### 问题 3: 私有仓库认证失败
+
+**SSH 方式**:
+```bash
+# 测试 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. 文件位置正确 (项目根目录)
+   ```bash
+   ls -la .env  # Linux/Mac
+   dir .env     # Windows
+   ```
+
+2. 文件格式正确
+   ```bash
+   # ✅ 正确
+   ENABLE_CONTENT_SYNC=true
+   
+   # ❌ 错误 (多余空格)
+   ENABLE_CONTENT_SYNC = true
+   
+   # ❌ 错误 (不需要引号,除非值中有空格)
+   ENABLE_CONTENT_SYNC="true"
+   ```
+
+3. 文件权限可读
+   ```bash
+   chmod 644 .env  # Linux/Mac
+   ```
+
+4. 运行检查命令
+   ```bash
+   pnpm run check-env
+   ```
+
+### 问题 5: 内容同步失败
+
+```bash
+# 手动同步内容
+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** - 提交前检查文章格式、图片大小等
+
+---
+
+## 📚 相关文档
+
+- [内容迁移指南](./CONTENT_MIGRATION.md) - 如何从单仓库迁移到分离模式
+- [内容仓库结构](./CONTENT_REPOSITORY.md) - 内容仓库的推荐结构
+- [主 README](../README.zh.md) - 项目总体说明
+
+---
+
+## 🤝 需要帮助?
+
+- 查看 [GitHub Issues](https://github.com/matsuzaka-yuki/Mizuki/issues)
+- 阅读 [完整文档](../README.zh.md)
+- 运行 `pnpm run check-env` 检查配置
+
+祝你使用愉快! 🎉

docs/DEPLOYMENT.md

@@ -0,0 +1,848 @@
+# Mizuki 部署指南
+
+本文档提供 Mizuki 博客在各个平台的部署配置说明。
+
+## 📖 目录
+
+- [部署前准备](#-部署前准备)
+- [GitHub Pages 部署](#-github-pages-部署)
+- [Vercel 部署](#-vercel-部署)
+- [Netlify 部署](#-netlify-部署)
+- [Cloudflare Pages 部署](#-cloudflare-pages-部署)
+- [故障排查](#-故障排查)
+
+---
+
+## 🚀 部署前准备
+
+### 基础配置
+
+1. **更新站点 URL**
+
+编辑 `astro.config.mjs`:
+```javascript
+export default defineConfig({
+  site: 'https://your-domain.com',  // 更新为你的域名
+  // ...
+});
+```
+
+2. **配置环境变量** (可选)
+
+如果使用内容分离功能，需要配置：
+- `ENABLE_CONTENT_SYNC=true`
+- `CONTENT_REPO_URL=你的内容仓库地址`
+- `USE_SUBMODULE=true`
+
+详见 [内容分离完整指南](./CONTENT_SEPARATION.md)
+
+---
+
+## 📦 GitHub Pages 部署
+
+### 自动部署 (推荐)
+
+项目已配置好 GitHub Actions 工作流，推送到 `main` 分支会自动部署。
+
+#### 本地模式 (默认)
+
+**无需任何配置**，开箱即用：
+
+1. 推送代码到 GitHub
+2. 在仓库设置中启用 GitHub Pages
+   - Settings → Pages
+   - Source: Deploy from a branch
+   - Branch: `pages` / `root`
+3. 等待 Actions 完成部署
+
+#### 内容分离模式
+
+**配置步骤**:
+
+1. **添加仓库 Secrets**:
+   - Settings → Secrets and variables → Actions → New repository secret
+   - 添加 `CONTENT_REPO_URL`: `https://github.com/your-username/Mizuki-Content.git`
+
+2. **修改 `.github/workflows/deploy.yml`**:
+
+取消注释环境变量部分:
+```yaml
+- name: Build site
+  run: pnpm run build
+  env:
+    ENABLE_CONTENT_SYNC: true
+    CONTENT_REPO_URL: ${{ secrets.CONTENT_REPO_URL }}
+    USE_SUBMODULE: true
+```
+
+3. **私有内容仓库配置**:
+
+**同账号私有仓库** (推荐):
+- 无需额外配置
+- 自动使用 `GITHUB_TOKEN` 访问
+
+**跨账号私有仓库 (SSH)**:
+```yaml
+# 添加 SSH 配置步骤
+- name: Setup SSH Key
+  uses: webfactory/ssh-agent@v0.8.0
+  with:
+    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+
+- name: Checkout
+  uses: actions/checkout@v4
+  with:
+    submodules: true
+```
+
+在 Secrets 中添加:
+- `SSH_PRIVATE_KEY`: SSH 私钥内容
+- `CONTENT_REPO_URL`: `git@github.com:other-user/repo.git`
+
+**跨账号私有仓库 (Token)**:
+```yaml
+- name: Checkout
+  uses: actions/checkout@v4
+  with:
+    submodules: true
+    token: ${{ secrets.PAT_TOKEN }}
+
+- name: Build site
+  run: pnpm run build
+  env:
+    ENABLE_CONTENT_SYNC: true
+    CONTENT_REPO_URL: https://${{ secrets.PAT_TOKEN }}@github.com/other-user/repo.git
+    USE_SUBMODULE: true
+```
+
+在 Secrets 中添加:
+- `PAT_TOKEN`: GitHub Personal Access Token (需要 `repo` 权限)
+
+### 工作流说明
+
+项目包含三个工作流:
+
+| 工作流 | 触发条件 | 功能 |
+|--------|---------|------|
+| `build.yml` | Push/PR 到 main | CI 测试，检查构建 |
+| `deploy.yml` | Push 到 main | 构建并部署到 pages 分支 |
+| `biome.yml` | Push/PR | 代码格式和质量检查 |
+
+---
+
+## 🔷 Vercel 部署
+
+### 快速部署
+
+1. **连接仓库**:
+   - 访问 [Vercel](https://vercel.com)
+   - Import Git Repository
+   - 选择你的 Mizuki 仓库
+
+2. **配置项目**:
+   - Framework Preset: Astro
+   - Build Command: `pnpm build` (默认)
+   - Output Directory: `dist` (默认)
+
+3. **部署**:
+   - 点击 Deploy 开始部署
+
+### 部署模式
+
+#### 本地模式
+
+**无需配置环境变量**，使用默认的 `vercel.json`。
+
+#### 内容分离模式 - 公开仓库
+
+在 Vercel 项目设置中添加环境变量:
+
+| 变量名 | 值 |
+|-------|---|
+| `ENABLE_CONTENT_SYNC` | `true` |
+| `CONTENT_REPO_URL` | `https://github.com/your-username/Mizuki-Content.git` |
+| `USE_SUBMODULE` | `false` 或 `true` (推荐 `false`) |
+
+> ⚠️ **重要提示**: 如果使用 `USE_SUBMODULE=true`,请确保 `.gitignore` 中的 `content/` 行已被注释掉,否则会导致部署失败。推荐在 Vercel 上使用 `USE_SUBMODULE=false` (独立仓库模式)。
+
+#### 内容分离模式 - 私有仓库
+
+**方式 A: 授权 Vercel 访问**
+- 在连接 GitHub 仓库时，确保授权包括内容仓库的访问权限
+
+**方式 B: 使用 Token**
+
+添加环境变量:
+```
+ENABLE_CONTENT_SYNC=true
+GITHUB_TOKEN=ghp_your_personal_access_token
+CONTENT_REPO_URL=https://${GITHUB_TOKEN}@github.com/your-username/Mizuki-Content-Private.git
+USE_SUBMODULE=true
+```
+
+### 配置文件
+
+项目包含两个 Vercel 配置文件:
+
+- `vercel.json` - 默认配置，适用于本地模式
+- `vercel-with-content.json.example` - 内容分离示例 (可选)
+
+**注意**: 使用默认 `vercel.json` 即可，通过环境变量控制是否启用内容分离。
+
+---
+
+## 🌐 Netlify 部署
+
+### 部署步骤
+
+1. **连接仓库**:
+   - 访问 [Netlify](https://www.netlify.com)
+   - New site from Git
+   - 选择你的 Mizuki 仓库
+
+2. **配置构建**:
+   - Build command: `pnpm build`
+   - Publish directory: `dist`
+
+3. **环境变量** (如果使用内容分离):
+
+在 Site settings → Environment variables 中添加:
+```
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=true
+```
+
+4. **私有仓库配置**:
+
+在 Site settings → Build & deploy → Deploy key 中添加有权限访问私有仓库的 SSH 密钥。
+
+### netlify.toml 配置
+
+可选：创建 `netlify.toml` 文件：
+
+```toml
+[build]
+  command = "pnpm build"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+  PNPM_VERSION = "9"
+  # 如果使用内容分离
+  ENABLE_CONTENT_SYNC = "true"
+  CONTENT_REPO_URL = "https://github.com/your-username/Mizuki-Content.git"
+  USE_SUBMODULE = "true"
+```
+
+---
+
+## ☁️ Cloudflare Pages 部署
+
+### 部署步骤
+
+1. **连接仓库**:
+   - 登录 [Cloudflare Dashboard](https://dash.cloudflare.com)
+   - Workers & Pages → Create application → Pages
+   - Connect to Git
+
+2. **配置构建**:
+   - Framework preset: Astro
+   - Build command: `pnpm build`
+   - Build output directory: `dist`
+
+3. **环境变量** (如果使用内容分离):
+
+添加以下变量:
+```
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=false  # ⚠️ Cloudflare Pages 默认不支持 submodule
+```
+
+### 注意事项
+
+⚠️ Cloudflare Pages 默认不支持 Git Submodule，建议:
+- 使用独立仓库模式: `USE_SUBMODULE=false`
+- 或在构建命令中手动初始化: `git submodule update --init && pnpm build`
+
+---
+
+## 🔄 自动同步机制
+
+所有部署平台都使用相同的自动同步机制：
+
+```json
+// package.json
+{
+  "scripts": {
+    "prebuild": "node scripts/sync-content.js || true"
+  }
+}
+```
+
+**工作原理**:
+1. `pnpm build` 执行前自动运行 `prebuild` 钩子
+2. 检查 `ENABLE_CONTENT_SYNC` 环境变量
+3. 如果为 `true`，从远程仓库同步内容到 `src/content/` 和 `public/images/`
+4. 如果为 `false` 或未设置，跳过同步，使用本地内容
+5. `|| true` 确保同步失败不会中断构建
+
+**优势**:
+- ✅ 统一的构建命令，无需修改配置
+- ✅ 自动兼容所有部署模式
+- ✅ 同步失败不影响构建（回退到本地内容）
+
+---
+
+## 🔍 故障排查
+
+### 问题 1: 部署失败 - "未设置 CONTENT_REPO_URL"
+
+**原因**: 启用了内容分离但未配置仓库地址
+
+**解决**:
+1. 检查环境变量中是否设置了 `ENABLE_CONTENT_SYNC=true`
+2. 检查是否设置了 `CONTENT_REPO_URL`
+3. 或将 `ENABLE_CONTENT_SYNC` 设置为 `false` 使用本地内容
+
+### 问题 2: 私有仓库认证失败
+
+**GitHub Actions**:
+- **同账号**: 确保使用 `${{ secrets.GITHUB_TOKEN }}`
+- **跨账号**: 配置 SSH 密钥或 PAT Token
+
+**Vercel/Netlify**:
+- 确保授权了私有仓库访问
+- 或使用 Token 方式: `https://TOKEN@github.com/user/repo.git`
+
+### 问题 3: Submodule 与 .gitignore 冲突
+
+**错误信息**:
+```
+The following paths are ignored by one of your .gitignore files:
+content
+fatal: Failed to add submodule 'content'
+```
+
+**原因**: `.gitignore` 文件中的 `content/` 规则阻止了 Git 添加 submodule
+
+**解决方案 A: 修改 .gitignore (推荐)**
+
+编辑 `.gitignore` 文件,注释掉或删除 `content/` 行:
+
+```diff
+# content repository (if using independent mode)
+- content/
++ # content/  # 使用 submodule 时需要注释掉
+*.backup
+```
+
+然后重新部署。
+
+**解决方案 B: 使用独立仓库模式**
+
+如果不想修改 `.gitignore`,可以使用独立仓库模式:
+
+```
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=false  # 改为 false
+```
+
+**解决方案 C: 自动降级 (v1.1+)**
+
+`sync-content.js` 会自动检测此冲突并降级到独立仓库模式,无需手动干预。
+
+### 问题 4: Submodule 克隆失败
+
+**检查**:
+1. 确认部署平台支持 Git Submodule
+2. 检查 SSH 密钥或 Token 配置
+3. 尝试使用独立仓库模式: `USE_SUBMODULE=false`
+
+### 问题 5: 构建成功但内容未更新
+
+**检查**:
+1. 查看构建日志，确认同步步骤执行
+2. 检查 `ENABLE_CONTENT_SYNC` 是否设置为 `true`
+3. 验证 `CONTENT_REPO_URL` 是否正确
+4. 清除部署平台的缓存并重新部署
+
+### 问题 6: 部署时间过长
+
+**优化建议**:
+- 使用 Git Submodule 模式 (更快)
+- 启用部署平台的缓存机制
+- 优化图片大小和数量
+
+### 问题 7: Vercel 部署时 submodule 权限问题
+
+**错误信息**:
+```
+fatal: could not read Username for 'https://github.com'
+```
+
+**原因**: 私有仓库需要认证
+
+**解决**:
+1. 在 Vercel 项目设置中添加 GitHub 集成权限
+2. 或使用 Token: `https://${GITHUB_TOKEN}@github.com/user/repo.git`
+3. 或切换到独立仓库模式: `USE_SUBMODULE=false`
+
+**检查**:
+1. 查看构建日志,确认同步步骤执行
+2. 检查 `ENABLE_CONTENT_SYNC` 是否设置为 `true`
+3. 验证 `CONTENT_REPO_URL` 是否正确
+4. 清除部署平台的缓存并重新部署
+
+---
+
+## 📋 环境变量参考
+
+| 变量名 | 必需 | 默认值 | 说明 |
+|-------|------|--------|------|
+| `ENABLE_CONTENT_SYNC` | ❌ | `false` | 是否启用内容分离功能 |
+| `CONTENT_REPO_URL` | ⚠️ | - | 内容仓库地址 (启用内容分离时必需) |
+| `USE_SUBMODULE` | ❌ | `false` | 是否使用 Git Submodule 模式 |
+| `CONTENT_DIR` | ❌ | `./content` | 内容目录路径 |
+| `UMAMI_API_KEY` | ❌ | - | Umami 统计 API 密钥 |
+| `BCRYPT_SALT_ROUNDS` | ❌ | `12` | bcrypt 加密轮数 |
+
+⚠️ = 在特定模式下必需
+
+---
+
+## 💡 推荐配置
+
+### 个人博客
+- **平台**: Vercel 或 GitHub Pages
+- **模式**: 本地模式（最简单）
+- **配置**: 无需环境变量
+
+### 团队协作
+- **平台**: 任意
+- **模式**: 内容分离 - 私有仓库
+- **配置**: 启用内容分离 + SSH 认证
+
+### 多站点部署
+- **平台**: 多个平台同时部署
+- **模式**: 内容分离 - 公开仓库
+- **配置**: 统一的环境变量配置
+
+---
+
+## 📚 相关文档
+
+- [内容分离完整指南](./CONTENT_SEPARATION.md) - 详细的内容分离配置
+- [内容迁移指南](./MIGRATION_GUIDE.md) - 从单仓库迁移到分离模式
+- [内容仓库结构](./CONTENT_REPOSITORY.md) - 内容仓库的组织方式
+
+---
+
+💡 **建议**: 如果是第一次部署，推荐先使用本地模式熟悉流程，之后再根据需要启用内容分离功能。
+
+## 🔔 内容仓库更新触发构建
+
+### 问题说明
+
+当使用**内容代码分离**架构时，默认情况下：
+- ✅ 代码仓库 (Mizuki) 更新会触发自动构建
+- ❌ 内容仓库 (Mizuki-Content) 更新**不会**触发构建
+
+这意味着您在内容仓库中发布新文章后，需要手动触发代码仓库的重新部署才能看到更新。
+
+### 解决方案概览
+
+有以下几种方式实现内容仓库更新时自动触发构建：
+
+| 方案 | 难度 | 推荐度 | 适用平台 |
+|------|------|--------|----------|
+| **Repository Dispatch** | ⭐ 简单 | ⭐⭐⭐⭐⭐ | GitHub Pages, Vercel, Netlify, CF Pages |
+| **Webhook + Deploy Hook** | ⭐⭐ 中等 | ⭐⭐⭐⭐ | Vercel, Netlify, CF Pages |
+| **定时构建** | ⭐ 简单 | ⭐⭐⭐ | 所有平台 |
+
+---
+
+### 方案 1: Repository Dispatch (推荐)
+
+**原理**: 内容仓库推送时，通过 GitHub Actions 触发代码仓库的构建工作流。
+
+**优点**:
+- ✅ 实时触发，无延迟
+- ✅ 无需云平台特定配置
+- ✅ 适用于所有部署平台
+- ✅ 完全免费
+
+#### 配置步骤
+
+**Step 1: 创建 GitHub Personal Access Token (PAT)**
+
+1. 访问 [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
+2. 点击 **Generate new token (classic)**
+3. 配置 Token:
+   - Note: `Mizuki Content Trigger` (名称随意)
+   - Expiration: `No expiration` 或选择合适的期限
+   - Scopes: 勾选 `repo` (完整仓库访问权限)
+4. 点击 **Generate token**，复制生成的 Token (只显示一次！)
+
+**Step 2: 在内容仓库添加 Secret**
+
+1. 打开内容仓库 (Mizuki-Content): `https://github.com/your-username/Mizuki-Content`
+2. Settings → Secrets and variables → Actions → New repository secret
+3. 添加:
+   - Name: `DISPATCH_TOKEN`
+   - Value: 粘贴刚才创建的 PAT Token
+4. 点击 **Add secret**
+
+**Step 3: 在内容仓库创建 GitHub Actions 工作流**
+
+在内容仓库创建文件 `.github/workflows/trigger-build.yml`:
+
+```yaml
+name: Trigger Main Repo Build
+
+on:
+  push:
+    branches:
+      - main  # 或你使用的主分支名称
+    paths:
+      - 'posts/**'
+      - 'spec/**'
+      - 'data/**'
+      - 'images/**'
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger repository dispatch
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.DISPATCH_TOKEN }}
+          repository: your-username/Mizuki  # 改为你的代码仓库
+          event-type: content-updated
+          client-payload: |
+            {
+              "ref": "${{ github.ref }}",
+              "sha": "${{ github.sha }}",
+              "message": "${{ github.event.head_commit.message }}"
+            }
+```
+
+**注意事项**:
+- 将 `your-username/Mizuki` 替换为你的代码仓库完整名称
+- 可以根据需要调整 `paths`，只在特定文件变化时触发
+
+**Step 4: 在代码仓库更新 GitHub Actions 工作流**
+
+编辑代码仓库的 `.github/workflows/deploy.yml`，添加 `repository_dispatch` 触发器:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  repository_dispatch:  # 添加这个触发器
+    types:
+      - content-updated
+
+# ...其余配置保持不变
+```
+
+**Step 5: 测试**
+
+1. 在内容仓库编辑一篇文章
+2. 提交并推送到 `main` 分支
+3. 查看内容仓库的 Actions 页面，确认 "Trigger Main Repo Build" 工作流运行
+4. 查看代码仓库的 Actions 页面，确认部署工作流被触发
+
+---
+
+### 方案 2: Webhook + Deploy Hook
+
+**原理**: 使用云平台提供的 Deploy Hook URL，在内容仓库更新时通过 webhook 触发构建。
+
+**优点**:
+- ✅ 实时触发
+- ✅ 与部署平台深度集成
+
+**缺点**:
+- ⚠️ 需要为每个部署平台单独配置
+- ⚠️ 不适用于 GitHub Pages
+
+#### Vercel 配置
+
+**Step 1: 获取 Deploy Hook URL**
+
+1. 打开 Vercel 项目设置
+2. Settings → Git → Deploy Hooks
+3. 创建新的 Hook:
+   - Name: `Content Update`
+   - Git Branch: `main` (或你的主分支)
+4. 点击 **Create Hook**，复制生成的 URL
+
+**Step 2: 在内容仓库配置 Webhook**
+
+在内容仓库创建 `.github/workflows/trigger-vercel.yml`:
+
+```yaml
+name: Trigger Vercel Deployment
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'posts/**'
+      - 'spec/**'
+      - 'data/**'
+      - 'images/**'
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Vercel Deploy Hook
+        run: |
+          curl -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"
+```
+
+**Step 3: 添加 Secret**
+
+在内容仓库添加 Secret:
+- Name: `VERCEL_DEPLOY_HOOK`
+- Value: 粘贴 Vercel Deploy Hook URL
+
+#### Netlify 配置
+
+**Step 1: 获取 Build Hook URL**
+
+1. 打开 Netlify 站点设置
+2. Site settings → Build & deploy → Continuous deployment → Build hooks
+3. 点击 **Add build hook**:
+   - Build hook name: `Content Update`
+   - Branch to build: `main`
+4. 保存并复制生成的 URL
+
+**Step 2: 配置 GitHub Actions**
+
+在内容仓库创建 `.github/workflows/trigger-netlify.yml`:
+
+```yaml
+name: Trigger Netlify Deployment
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'posts/**'
+      - 'spec/**'
+      - 'data/**'
+      - 'images/**'
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Netlify Build Hook
+        run: |
+          curl -X POST -d '{}' "${{ secrets.NETLIFY_BUILD_HOOK }}"
+```
+
+**Step 3: 添加 Secret**
+
+- Name: `NETLIFY_BUILD_HOOK`
+- Value: 粘贴 Netlify Build Hook URL
+
+#### Cloudflare Pages 配置
+
+**Step 1: 获取 Deploy Hook URL**
+
+1. 打开 Cloudflare Pages 项目
+2. Settings → Builds & deployments → Deploy hooks
+3. 创建 Deploy Hook:
+   - Hook name: `Content Update`
+   - Branch: `main`
+4. 保存并复制 URL
+
+**Step 2: 配置类似于 Vercel/Netlify**
+
+配置方式与上述相同，只需修改 Secret 名称和 workflow 文件名。
+
+---
+
+### 方案 3: 定时构建 (fallback)
+
+**原理**: 设置定时任务，每天自动构建一次。
+
+**优点**:
+- ✅ 配置简单
+- ✅ 无需额外 Token 或 Webhook
+
+**缺点**:
+- ⚠️ 有延迟，不是实时更新
+- ⚠️ 可能造成不必要的构建
+
+#### GitHub Actions 配置
+
+在代码仓库的 `.github/workflows/deploy.yml` 中添加定时触发:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 2 * * *'  # 每天凌晨 2 点 (UTC 时间)
+  workflow_dispatch:  # 支持手动触发
+
+# ...其余配置
+```
+
+**Cron 表达式示例**:
+- `0 2 * * *` - 每天凌晨 2 点
+- `0 */6 * * *` - 每 6 小时一次
+- `0 0 * * 1` - 每周一凌晨
+
+#### Vercel/Netlify 配置
+
+这些平台也支持通过 webhook 设置定时构建:
+
+```yaml
+# 在内容仓库创建 .github/workflows/scheduled-build.yml
+name: Scheduled Build
+
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Deploy
+        run: |
+          curl -X POST "${{ secrets.DEPLOY_HOOK_URL }}"
+```
+
+---
+
+### 推荐配置组合
+
+#### 最佳实践 (推荐)
+
+结合多种方式，确保稳定性:
+
+```yaml
+# 代码仓库 .github/workflows/deploy.yml
+on:
+  push:
+    branches:
+      - main
+  repository_dispatch:    # 内容更新触发
+    types:
+      - content-updated
+  schedule:              # 兜底方案
+    - cron: '0 2 * * *'
+  workflow_dispatch:     # 手动触发
+```
+
+**优势**:
+- ✅ 内容更新实时触发 (repository_dispatch)
+- ✅ 每天自动同步，防止遗漏 (schedule)
+- ✅ 支持手动触发调试 (workflow_dispatch)
+
+---
+
+### 验证配置
+
+#### 检查清单
+
+- [ ] 创建了 PAT Token 或 Deploy Hook
+- [ ] 在内容仓库添加了对应的 Secret
+- [ ] 创建了内容仓库的触发工作流
+- [ ] 更新了代码仓库的部署工作流
+- [ ] 测试了一次提交，确认触发成功
+
+#### 测试步骤
+
+1. **在内容仓库修改文章**:
+   ```bash
+   cd /path/to/Mizuki-Content
+   # 编辑文章
+   git add .
+   git commit -m "test: trigger build"
+   git push
+   ```
+
+2. **查看内容仓库 Actions**:
+   - 访问 `https://github.com/your-username/Mizuki-Content/actions`
+   - 确认 "Trigger Build" 工作流运行成功
+
+3. **查看代码仓库 Actions**:
+   - 访问 `https://github.com/your-username/Mizuki/actions`
+   - 确认部署工作流被触发
+   - 查看日志确认内容同步成功
+
+4. **查看部署平台**:
+   - Vercel/Netlify/CF Pages: 查看部署历史
+   - GitHub Pages: 访问站点确认更新
+
+---
+
+### 故障排查
+
+#### 问题 1: 内容仓库推送后没有触发构建
+
+**检查**:
+1. 内容仓库的 Actions 是否运行?
+   - 查看 Actions 页面，确认工作流被触发
+2. PAT Token 权限是否正确?
+   - 需要 `repo` 完整权限
+3. 代码仓库名称是否正确?
+   - 格式: `owner/repo`
+
+**调试**:
+```yaml
+# 在内容仓库工作流中添加调试步骤
+- name: Debug
+  run: |
+    echo "Repository: your-username/Mizuki"
+    echo "Event type: content-updated"
+```
+
+#### 问题 2: Repository dispatch 触发成功但构建失败
+
+**检查**:
+1. 代码仓库的 Actions 是否启用?
+   - Settings → Actions → General → 确保启用
+2. 工作流文件是否包含 `repository_dispatch` 触发器?
+3. 环境变量是否正确配置?
+
+#### 问题 3: PAT Token 过期
+
+**现象**: 工作流运行失败，提示认证错误
+
+**解决**:
+1. 重新生成 PAT Token
+2. 更新内容仓库的 Secret
+3. 测试触发
+
+#### 问题 4: Deploy Hook 无效
+
+**检查**:
+1. Hook URL 是否正确复制?
+2. Secret 是否正确添加?
+3. 使用 curl 测试 Hook:
+   ```bash
+   curl -X POST "https://api.vercel.com/v1/integrations/deploy/..."
+   ```
+
+---

docs/MIGRATION_GUIDE.md

@@ -0,0 +1,271 @@
+# Mizuki 内容迁移指南
+
+本指南将帮助你将现有的 Mizuki 博客从单仓库模式迁移到代码内容分离模式。
+
+> 💡 **提示**: 如果是新项目,建议先阅读 [内容分离完整指南](./CONTENT_SEPARATION.md)
+
+## 📋 迁移前准备
+
+### 检查清单
+
+- [ ] **备份整个项目** (重要!)
+- [ ] 确保所有更改已提交到 Git
+- [ ] 了解你要使用的模式 (推荐 Submodule)
+- [ ] 在 GitHub/GitLab 创建新的内容仓库
+
+## 🚀 迁移步骤
+
+### 步骤 1: 创建内容仓库
+
+```bash
+# 创建并进入新目录
+mkdir Mizuki-Content
+cd Mizuki-Content
+
+# 初始化 Git 仓库
+git init
+
+# 创建目录结构
+mkdir -p posts spec data images/albums images/diary images/posts
+
+# 创建 README
+cat > README.md << 'EOF'
+# Mizuki 博客内容
+
+这是 Mizuki 博客的内容仓库,包含所有文章、数据和图片。
+
+## 目录结构
+
+- `posts/` - 博客文章
+- `spec/` - 特殊页面 (关于、友链等)
+- `data/` - 数据文件 (番剧、项目、技能、时间线)
+- `images/` - 图片资源
+
+## 使用方法
+
+此仓库作为 Mizuki 代码仓库的内容源,通过 Git Submodule 或独立模式关联。
+
+详细说明请查看: https://github.com/matsuzaka-yuki/Mizuki
+EOF
+```
+
+### 步骤 2: 从 Mizuki 项目复制内容
+
+```bash
+# 设置路径变量
+MIZUKI_PATH="/path/to/your/Mizuki"
+CONTENT_PATH="/path/to/Mizuki-Content"
+
+# 复制文章
+cp -r "$MIZUKI_PATH/src/content/posts/"* "$CONTENT_PATH/posts/"
+
+# 复制特殊页面
+cp -r "$MIZUKI_PATH/src/content/spec/"* "$CONTENT_PATH/spec/"
+
+# 复制数据文件
+cp "$MIZUKI_PATH/src/data/anime.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "anime.ts not found"
+cp "$MIZUKI_PATH/src/data/projects.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "projects.ts not found"
+cp "$MIZUKI_PATH/src/data/skills.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "skills.ts not found"
+cp "$MIZUKI_PATH/src/data/timeline.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "timeline.ts not found"
+
+# 复制图片
+cp -r "$MIZUKI_PATH/public/images/albums/"* "$CONTENT_PATH/images/albums/" 2>/dev/null || echo "albums not found"
+cp -r "$MIZUKI_PATH/public/images/diary/"* "$CONTENT_PATH/images/diary/" 2>/dev/null || echo "diary not found"
+
+echo "✅ 内容复制完成!"
+```
+
+### 步骤 3: 提交内容仓库
+
+```bash
+cd "$CONTENT_PATH"
+
+# 添加所有文件
+git add .
+
+# 提交
+git commit -m "Initial commit: Migrate content from Mizuki monorepo"
+
+# 添加远程仓库 (替换为你的仓库地址)
+git remote add origin https://github.com/your-username/Mizuki-Content.git
+
+# 推送
+git branch -M master
+git push -u origin master
+
+echo "✅ 内容仓库已推送!"
+```
+
+### 步骤 4: 配置 Mizuki 代码仓库
+
+```bash
+cd "$MIZUKI_PATH"
+
+# 创建 .env 文件
+cp .env.example .env
+
+# 编辑 .env 文件,启用内容分离
+cat > .env << 'EOF'
+# 启用内容分离
+ENABLE_CONTENT_SYNC=true
+
+# 内容仓库配置
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=true
+EOF
+
+# 运行同步脚本
+pnpm run sync-content
+
+# 提交更改
+git add .env.example
+git commit -m "Enable content separation"
+git push
+```
+
+> 📖 更多配置选项请参考 [内容分离完整指南](./CONTENT_SEPARATION.md)
+
+### 步骤 5: 清理原仓库中的内容 (可选)
+
+⚠️ **警告**: 只有在确认内容已成功迁移后才执行此步骤!
+
+```bash
+cd "$MIZUKI_PATH"
+
+# 备份原内容 (以防万一)
+mkdir -p ../mizuki-content-backup
+cp -r src/content/posts ../mizuki-content-backup/
+cp -r src/content/spec ../mizuki-content-backup/
+cp -r src/data ../mizuki-content-backup/
+cp -r public/images ../mizuki-content-backup/
+
+# 删除已迁移的内容 (保留目录结构)
+rm -rf src/content/posts/*
+rm -rf src/content/spec/*
+rm -f src/data/anime.ts src/data/projects.ts src/data/skills.ts src/data/timeline.ts
+rm -rf public/images/albums/* public/images/diary/*
+
+# 创建 .gitkeep 文件保留目录
+touch src/content/posts/.gitkeep
+touch src/content/spec/.gitkeep
+touch public/images/albums/.gitkeep
+touch public/images/diary/.gitkeep
+
+# 提交更改
+git add .
+git commit -m "Remove migrated content (now in separate repository)"
+git push
+```
+
+## 🧪 测试迁移
+
+### 本地测试
+
+```bash
+cd "$MIZUKI_PATH"
+
+# 同步内容
+pnpm run sync-content
+
+# 启动开发服务器
+pnpm dev
+
+# 访问 http://localhost:4321 检查:
+# - 文章是否正常显示
+# - 图片是否正确加载
+# - 特殊页面是否工作
+# - 数据页面是否正常 (番剧、项目等)
+```
+
+### 构建测试
+
+```bash
+# 构建项目
+pnpm build
+
+# 预览构建结果
+pnpm preview
+
+# 检查所有功能是否正常
+```
+
+## 🔄 日常工作流
+
+### 更新内容
+
+```bash
+# 1. 在内容仓库中修改
+cd "$CONTENT_PATH"
+# 编辑文件...
+git add .
+git commit -m "Update content"
+git push
+
+# 2. 在代码仓库中同步
+cd "$MIZUKI_PATH"
+pnpm run sync-content
+```
+
+### 使用 Submodule 时
+
+```bash
+cd "$MIZUKI_PATH"
+
+# 更新 submodule 到最新版本
+git submodule update --remote --merge
+
+# 或者使用同步脚本 (推荐)
+pnpm run sync-content
+
+# 提交 submodule 更新
+git add content
+git commit -m "Update content submodule"
+git push
+```
+
+## 🚀 部署配置
+
+迁移完成后,需要在部署平台配置环境变量:
+
+```bash
+ENABLE_CONTENT_SYNC=true
+CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
+USE_SUBMODULE=true
+```
+
+详细的部署配置(包括私有仓库、GitHub Actions、Vercel 等)请参考 [内容分离完整指南 - CI/CD 部署](./CONTENT_SEPARATION.md#-cicd-部署)
+
+## ⚠️ 常见问题
+
+### Q: 同步脚本失败怎么办?
+
+A: 检查:
+1. 网络连接是否正常
+2. Git 凭据是否配置正确
+3. `ENABLE_CONTENT_SYNC=true` 是否已设置
+4. `CONTENT_REPO_URL` 是否正确
+5. 是否有足够的磁盘空间
+
+运行 `pnpm run check-env` 检查配置。
+
+### Q: 符号链接在 Windows 上不工作?
+
+A: 需要以管理员身份运行,或者脚本会自动切换到复制模式。
+
+### Q: 如何回滚到单仓库模式?
+
+A: 在 `.env` 中设置 `ENABLE_CONTENT_SYNC=false`,然后从备份或内容仓库复制内容回本地。
+
+### Q: 遇到私有仓库认证问题?
+
+A: 参考 [内容分离完整指南 - 私有仓库配置](./CONTENT_SEPARATION.md#-私有仓库配置)
+
+## 📚 参考文档
+
+- [内容分离完整指南](./CONTENT_SEPARATION.md) - 详细配置说明
+- [内容仓库结构说明](./CONTENT_REPOSITORY.md) - 推荐的仓库结构
+- [Git Submodule 文档](https://git-scm.com/book/zh/v2/Git-%E5%B7%A5%E5%85%B7-%E5%AD%90%E6%A8%A1%E5%9D%97)
+
+---
+
+💡 **提示**: 迁移前建议先在测试环境中验证整个流程!

docs/README.md

@@ -0,0 +1,110 @@
+# Mizuki 文档索引
+
+欢迎查阅 Mizuki 的详细文档！
+
+## 📚 文档列表
+
+### 核心文档
+
+- **[../README.zh.md](../README.zh.md)** - 项目主文档 (简体中文)
+  - 快速开始
+  - 功能特性
+  - 基础配置
+  - 常见问题
+
+### 多语言文档
+
+- **[../README.md](../README.md)** - English
+- **[../README.ja.md](../README.ja.md)** - 日本語  
+- **[../README.tw.md](../README.tw.md)** - 繁體中文
+
+### 内容分离相关
+
+- **[CONTENT_SEPARATION.md](./CONTENT_SEPARATION.md)** - 内容分离完整指南 ⭐
+  - ENABLE_CONTENT_SYNC 控制开关
+  - 环境变量配置详解
+  - 私有仓库配置方法
+  - 模式切换指南
+  - 故障排查
+
+- **[CONTENT_REPOSITORY.md](./CONTENT_REPOSITORY.md)** - 内容仓库结构指南
+  - 推荐的目录结构
+  - 文件组织方式
+  - 内容编写规范
+  - 图片管理建议
+
+- **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** - 内容迁移指南
+  - 从单仓库迁移到分离模式
+  - 详细迁移步骤
+  - 测试验证方法
+
+### 部署相关
+
+- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - 部署完整指南 ⭐
+  - 各平台部署配置 (GitHub Pages / Vercel / Netlify / Cloudflare Pages)
+  - 内容仓库更新自动触发构建
+  - 私有仓库认证
+  - 故障排查
+
+- **[AUTO_BUILD_TRIGGER.md](./AUTO_BUILD_TRIGGER.md)** - 自动构建触发快速参考 🆕
+  - 5 步快速配置，解决内容更新不触发部署的问题
+
+## 🚀 快速查找
+
+### 我是新手，想快速开始
+→ 阅读 [主 README](../README.zh.md)
+
+### 我想部署博客
+→ 阅读 [部署指南](./DEPLOYMENT.md)
+
+### 我想使用内容分离功能
+→ 阅读 [内容分离完整指南](./CONTENT_SEPARATION.md)
+
+### 我想从单仓库迁移到分离模式
+→ 阅读 [内容迁移指南](./MIGRATION_GUIDE.md)
+
+### 我想配置私有内容仓库
+→ 阅读 [内容分离指南 - 私有仓库配置](./CONTENT_SEPARATION.md#-私有仓库配置)
+
+### 我的部署遇到问题
+→ 阅读 [部署指南 - 故障排查](./DEPLOYMENT.md#-故障排查)
+
+### 我遇到了内容同步错误
+→ 阅读 [内容分离指南 - 故障排查](./CONTENT_SEPARATION.md#-故障排查)
+
+### 内容仓库更新后站点没有自动重新部署 🆕
+→ 阅读 [自动构建触发快速参考](./AUTO_BUILD_TRIGGER.md)
+
+## 📖 文档架构
+
+```
+docs/
+├── README.md                    # 本文档 - 索引导航
+├── CONTENT_SEPARATION.md        # 内容分离核心指南
+├── CONTENT_REPOSITORY.md        # 内容仓库结构
+├── MIGRATION_GUIDE.md           # 迁移指南
+├── DEPLOYMENT.md                # 部署完整指南
+├── AUTO_BUILD_TRIGGER.md        # 自动构建触发快速参考
+└── image/                       # 文档图片资源
+```
+
+## 🎯 文档使用建议
+
+### 新用户推荐阅读顺序
+
+1. [主 README](../README.zh.md) - 了解项目基本情况
+2. [部署指南](./DEPLOYMENT.md) - 选择平台并部署
+3. (可选) [内容分离指南](./CONTENT_SEPARATION.md) - 高级功能
+
+### 高级用户推荐
+
+- 直接查阅具体主题的文档
+- 使用快速查找定位问题解决方案
+
+## 🤝 需要帮助？
+
+- 查看 [GitHub Issues](https://github.com/matsuzaka-yuki/Mizuki/issues)
+- 阅读相关文档的故障排查章节
+- 运行 `pnpm run check-env` 检查配置
+
+祝你使用愉快！🎉