迁移指南（含 Shirone 重构版迁移）
本页汇总 Mizuki 项目涉及的两条迁移路径：一是从 Mizuki 迁移到全面重构的后继项目 Shirone；二是在继续使用 Mizuki 的前提下，把博客从「单仓库模式」迁移到「代码/内容分离模式」。所有步骤均来自仓库中的官方迁移文档。
Purpose and Scope
本页面覆盖以下内容：
- Shirone 重构版迁移：Mizuki 已宣布停止更新与维护，官方建议迁移到后继项目 Shirone；本页说明官方通知的原文出处、迁移建议与决策依据。
- 单仓库 → 内容分离模式迁移：基于
docs/MIGRATION_GUIDE.md的完整五步迁移流程，包括内容仓库创建、内容复制、.env配置、pnpm run sync-content同步、原仓库清理、本地/构建测试以及日常工作流。 - 迁移相关配置项：
ENABLE_CONTENT_SYNC、CONTENT_REPO_URL、USE_SUBMODULE的作用与使用方式。 - 常见故障与回滚：同步失败、Windows 符号链接问题、私有仓库认证问题以及回滚到单仓库模式的方法。
以下主题有意留给兄弟页面，本页只做指引：
- 内容分离的原理、环境变量全集与私有仓库认证细节 → 参见「内容分离」页面（源文档：docs/CONTENT_SEPARATION.md）。
- 各部署平台（GitHub Pages / Vercel / Netlify / Cloudflare Pages）的具体配置与故障排查 → 参见「部署」页面（源文档：docs/DEPLOYMENT.md）。
- 内容仓库的推荐目录结构与编写规范 → 参见「内容仓库结构」页面（源文档：docs/CONTENT_REPOSITORY.md）。
- 内容更新后自动触发构建的配置 → 参见「自动构建触发」相关页面（源文档：docs/AUTO_BUILD_TRIGGER.md）。
Overview
Mizuki 是一个基于 Astro 的博客模板项目。围绕它存在两类完全不同的"迁移"需求：
- 项目级迁移（Mizuki → Shirone）：Mizuki 官方已发布公告，项目即将停止更新与维护，由功能基本一致、架构全新升级的 Shirone 接棒。对希望持续获得更新与支持的用户，官方建议直接迁移到新项目仓库。
- 仓库结构迁移（单仓库 → 分离模式）：Mizuki 支持把文章（
posts）、特殊页面（spec）、数据文件（anime.ts/projects.ts/skills.ts/timeline.ts）与图片资源（albums/diary）从代码仓库中剥离，放入独立的内容仓库（推荐的仓库名为Mizuki-Content），再通过 Git Submodule 或独立模式关联。这一模式让「写博客」与「改代码」彻底解耦，也更方便私有内容仓库、多端协作与自动构建。
两条路径的选择标准很直接：如果接受切换到新一代架构以获得长期维护，选择 Shirone；如果只是想在不换框架的前提下分离内容与代码，按本页第二部分操作即可。
官方停更通知原文（中文版 README）如下：
[!WARNING]
⚠️ 项目停止更新与迁移通知
本项目（Mizuki）即将停止更新与维护。 全新全面重构版本 Shirone 现已发布，功能与本项目基本一致，并在架构与体验上进行了全面重构与优化。建议前往新项目获取最新支持与更新：
Source: README.md
同样的通知还出现在 README.en.md、README.ja.md、README.tw.md 与 docs/README.md 中。
Architecture
迁移决策总览
下图展示一个 Mizuki 用户面对的两条迁移路径及其后续流程：
设计意图：官方把「换项目」和「换仓库结构」作为两个正交的决策点。Shirone 路径只需要切换仓库与跟随新项目的部署说明；分离模式路径则完全在 Mizuki 体系内完成，不依赖任何外部服务。
迁移前后的仓库结构对比
内容分离迁移的本质是把下面左侧的单仓库结构重组为右侧的「代码仓库 + 内容仓库」双仓库结构：
设计意图（WHY）：
- 职责分离：文章、数据与图片属于"高频低风险改动"，与主题代码的"低频高风险改动"放在同一仓库会互相污染提交历史；分离后内容仓库可以设为私有，只暴露构建产物。
- 同步机制复用：迁移后代码仓库通过
pnpm run sync-content拉取内容（Submodule 模式下等价于git submodule update --remote --merge），Mizuki 自身不感知内容来源差异，因此迁移对站点构建是透明的。 - 目录约定一致：内容仓库内部沿用
posts、spec、data、images的目录划分，与docs/CONTENT_REPOSITORY.md的推荐结构完全对应，降低迁移心智成本。
迁移到 Shirone 重构版
官方公告与现状
Mizuki 在所有语言的 README 顶部都放置了停更公告。以中文版为例：
- 公告位置：README.md
- 新项目地址：https://github.com/lyraVoid/shirone
- 官方对 Shirone 的定位：「功能与本项目基本一致，并在架构与体验上进行了全面重构与优化」；英文版 README 表述为 "equivalent features and a modernized architecture"。
文档索引页 docs/README.md 同样将 Shirone 标注为「全新全面重构版本（功能基本一致，架构全新升级）」。
迁移建议
由于 Shirone 是独立仓库，本仓库中没有提供自动化迁移脚本或专门的 Mizuki → Shirone 迁移文档；迁移方式以「前往新项目并按其 README 初始化」为主。基于 Mizuki 本身的仓库结构，迁移时需要带走的内容与下文「内容分离迁移」步骤 2 中的复制清单一致：
- 博客文章：
src/content/posts/ - 特殊页面（关于、友链等）：
src/content/spec/ - 数据文件：
src/data/anime.ts、src/data/projects.ts、src/data/skills.ts、src/data/timeline.ts - 图片资源：
public/images/albums/、public/images/diary/
⚠️ Mizuki 已停止维护意味着后续的安全修复与功能更新只发生在 Shirone；如果暂时留在 Mizuki，也建议至少完成下文的内容分离迁移，使内容资产独立于模板代码，为将来再次迁移降低成本。
单仓库 → 内容分离模式迁移（核心流程）
以下五步全部来自官方迁移文档 docs/MIGRATION_GUIDE.md。官方迁移前检查清单：
- 备份整个项目（重要！）
- 确保所有更改已提交到 Git
- 了解你要使用的模式（推荐 Submodule）
- 在 GitHub/GitLab 创建新的内容仓库
Source: MIGRATION_GUIDE.md
步骤 1：创建内容仓库
1# 创建并进入新目录
2mkdir Mizuki-Content
3cd Mizuki-Content
4
5# 初始化 Git 仓库
6git init
7
8# 创建目录结构
9mkdir -p posts spec data images/albums images/diary images/posts
10
11# 创建 README
12cat > README.md << 'EOF'
13# Mizuki 博客内容
14
15这是 Mizuki 博客的内容仓库,包含所有文章、数据和图片。
16
17## 目录结构
18
19- `posts/` - 博客文章
20- `spec/` - 特殊页面 (关于、友链等)
21- `data/` - 数据文件 (番剧、项目、技能、时间线)
22- `images/` - 图片资源
23
24## 使用方法
25
26此仓库作为 Mizuki 代码仓库的内容源,通过 Git Submodule 或独立模式关联。
27
28详细说明请查看: https://github.com/matsuzaka-yuki/Mizuki
29EOFSource: MIGRATION_GUIDE.md
注意目录结构中有 images/posts，但后文复制图片时只涉及 albums 与 diary 两个子目录——这是为其他来源的图片预留的位置。
步骤 2：从 Mizuki 项目复制内容
1# 设置路径变量
2MIZUKI_PATH="/path/to/your/Mizuki"
3CONTENT_PATH="/path/to/Mizuki-Content"
4
5# 复制文章
6cp -r "$MIZUKI_PATH/src/content/posts/"* "$CONTENT_PATH/posts/"
7
8# 复制特殊页面
9cp -r "$MIZUKI_PATH/src/content/spec/"* "$CONTENT_PATH/spec/"
10
11# 复制数据文件
12cp "$MIZUKI_PATH/src/data/anime.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "anime.ts not found"
13cp "$MIZUKI_PATH/src/data/projects.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "projects.ts not found"
14cp "$MIZUKI_PATH/src/data/skills.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "skills.ts not found"
15cp "$MIZUKI_PATH/src/data/timeline.ts" "$CONTENT_PATH/data/" 2>/dev/null || echo "timeline.ts not found"
16
17# 复制图片
18cp -r "$MIZUKI_PATH/public/images/albums/"* "$CONTENT_PATH/images/albums/" 2>/dev/null || echo "albums not found"
19cp -r "$MIZUKI_PATH/public/images/diary/"* "$CONTENT_PATH/images/diary/" 2>/dev/null || echo "diary not found"
20
21echo "✅ 内容复制完成!"Source: MIGRATION_GUIDE.md
实现细节：数据文件和图片的复制命令都带 2>/dev/null || echo "xxx not found" 兜底——因为并不是每个站点都有番剧、时间线等数据，缺文件属于正常情况而不是错误。这一设计让同一份脚本可以直接在「最小化模板」与「完整站点」上运行。
步骤 3：提交内容仓库
1cd "$CONTENT_PATH"
2
3# 添加所有文件
4git add .
5
6# 提交
7git commit -m "Initial commit: Migrate content from Mizuki monorepo"
8
9# 添加远程仓库 (替换为你的仓库地址)
10git remote add origin https://github.com/your-username/Mizuki-Content.git
11
12# 推送
13git branch -M master
14git push -u origin master
15
16echo "✅ 内容仓库已推送!"Source: MIGRATION_GUIDE.md
git branch -M master 强制把当前分支重命名为 master，保证后续 Submodule 与部署平台的默认分支引用一致。
步骤 4：配置 Mizuki 代码仓库
1cd "$MIZUKI_PATH"
2
3# 创建 .env 文件
4cp .env.example .env
5
6# 编辑 .env 文件,启用内容分离
7cat > .env << 'EOF'
8# 启用内容分离
9ENABLE_CONTENT_SYNC=true
10
11# 内容仓库配置
12CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
13USE_SUBMODULE=true
14EOF
15
16# 运行同步脚本
17pnpm run sync-content
18
19# 提交更改
20git add .env.example
21git commit -m "Enable content separation"
22git pushSource: MIGRATION_GUIDE.md
三个环境变量构成内容分离的最小配置：ENABLE_CONTENT_SYNC=true 打开同步总开关，CONTENT_REPO_URL 指向内容仓库，USE_SUBMODULE=true 选择 Submodule 关联方式（另一个可选模式是独立模式，详见「内容分离」页面）。
步骤 5：清理原仓库中的内容（可选，危险操作）
官方明确警告：只有在确认内容已成功迁移后才执行此步骤。
1cd "$MIZUKI_PATH"
2
3# 备份原内容 (以防万一)
4mkdir -p ../mizuki-content-backup
5cp -r src/content/posts ../mizuki-content-backup/
6cp -r src/content/spec ../mizuki-content-backup/
7cp -r src/data ../mizuki-content-backup/
8cp -r public/images ../mizuki-content-backup/
9
10# 删除已迁移的内容 (保留目录结构)
11rm -rf src/content/posts/*
12rm -rf src/content/spec/*
13rm -f src/data/anime.ts src/data/projects.ts src/data/skills.ts src/data/timeline.ts
14rm -rf public/images/albums/* public/images/diary/*
15
16# 创建 .gitkeep 文件保留目录
17touch src/content/posts/.gitkeep
18touch src/content/spec/.gitkeep
19touch public/images/albums/.gitkeep
20touch public/images/diary/.gitkeep
21
22# 提交更改
23git add .
24git commit -m "Remove migrated content (now in separate repository)"
25git pushSource: MIGRATION_GUIDE.md
设计意图：先做一次 ../mizuki-content-backup 备份再删除；删除后用 .gitkeep 占位，让 Git 继续跟踪空目录，避免构建工具因为目录缺失而报错。
端到端时序
步骤顺序不可颠倒的原因：内容必须先在远端仓库存在并完成一次同步验证，才能安全清理本地副本；否则一旦同步脚本失败，原内容已被删除。
测试验证
迁移完成后，官方要求先本地验证再部署。
本地测试
1cd "$MIZUKI_PATH"
2
3# 同步内容
4pnpm run sync-content
5
6# 启动开发服务器
7pnpm dev
8
9# 访问 http://localhost:4321 检查:
10# - 文章是否正常显示
11# - 图片是否正确加载
12# - 特殊页面是否工作
13# - 数据页面是否正常 (番剧、项目等)Source: MIGRATION_GUIDE.md
构建测试
1# 构建项目
2pnpm build
3
4# 预览构建结果
5pnpm preview
6
7# 检查所有功能是否正常Source: MIGRATION_GUIDE.md
本地测试覆盖四类内容（文章、图片、特殊页面、数据页面），恰好对应步骤 2 复制的四类资产；pnpm preview 用于在生产构建产物上复核，避免 dev 模式的宽松行为掩盖问题。
迁移后的日常工作流
更新内容（独立模式）
1# 1. 在内容仓库中修改
2cd "$CONTENT_PATH"
3# 编辑文件...
4git add .
5git commit -m "Update content"
6git push
7
8# 2. 在代码仓库中同步
9cd "$MIZUKI_PATH"
10pnpm run sync-contentSource: MIGRATION_GUIDE.md
使用 Submodule 时
1cd "$MIZUKI_PATH"
2
3# 更新 submodule 到最新版本
4git submodule update --remote --merge
5
6# 或者使用同步脚本 (推荐)
7pnpm run sync-content
8
9# 提交 submodule 更新
10git add content
11git commit -m "Update content submodule"
12git pushSource: MIGRATION_GUIDE.md
从 git add content 可以看出：Submodule 模式下内容会被检出到代码仓库内的 content 目录，代码仓库记录的是 submodule 指针（commit SHA）。官方推荐用 pnpm run sync-content 统一两条模式的操作入口，避免记忆两套命令。
部署配置
迁移完成后，需要在部署平台配置环境变量：
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
USE_SUBMODULE=trueSource: MIGRATION_GUIDE.md
部署平台的环境变量必须与本地 .env 保持一致，否则 CI 构建时无法拉取内容仓库。私有仓库认证、GitHub Actions、Vercel 等平台的完整配置，参见「内容分离」页面的 CI/CD 部署章节（源文档：docs/CONTENT_SEPARATION.md）。
Configuration Options
迁移涉及的最小配置集合如下（完整变量清单在「内容分离」页面）：
| 变量 | 类型 | 迁移场景取值 | 说明 |
|---|---|---|---|
ENABLE_CONTENT_SYNC | boolean | true | 内容分离总开关；设为 false 即回退到单仓库模式 |
CONTENT_REPO_URL | string | https://github.com/your-username/Mizuki-Content.git | 内容仓库地址，同步脚本拉取目标 |
USE_SUBMODULE | boolean | true（推荐） | 关联模式：true 为 Git Submodule，内容检出到代码仓库 content 目录；false 为独立模式 |
Source: MIGRATION_GUIDE.md
配套命令：
| 命令 | 用途 |
|---|---|
pnpm run sync-content | 拉取/同步内容仓库到构建目录，两种模式通用 |
pnpm run check-env | 检查环境变量配置是否正确 |
pnpm dev / pnpm build / pnpm preview | 本地开发、生产构建与构建产物预览 |
git submodule update --remote --merge | Submodule 模式下手动更新内容到最新版本 |
Source: MIGRATION_GUIDE.md · MIGRATION_GUIDE.md · MIGRATION_GUIDE.md
Failure Modes, Edge Cases & Concurrency
以下是官方文档明确列出的故障与边界情况：
同步脚本失败
排查顺序（来自 FAQ）：
- 网络连接是否正常
- Git 凭据是否配置正确
ENABLE_CONTENT_SYNC=true是否已设置CONTENT_REPO_URL是否正确- 是否有足够的磁盘空间
并运行 pnpm run check-env 检查配置。
Source: MIGRATION_GUIDE.md
Windows 符号链接问题
独立模式（非 Submodule）下同步脚本可能使用符号链接；Windows 上若权限不足会失败。官方说明：需要以管理员身份运行，或者脚本会自动切换到复制模式。
Source: MIGRATION_GUIDE.md
私有仓库认证问题
私有内容仓库需要额外认证配置，官方指引参见 docs/CONTENT_SEPARATION.md 的「私有仓库配置」章节。
Source: MIGRATION_GUIDE.md
回滚到单仓库模式
在 .env 中设置 ENABLE_CONTENT_SYNC=false，然后从备份或内容仓库复制内容回本地。Source: MIGRATION_GUIDE.md
这正是迁移前检查清单强调「备份整个项目」的原因：删除原内容（步骤 5）之后，唯一可靠的内容来源是内容仓库远端与步骤 5 中创建的 ../mizuki-content-backup。
一致性注意点
- 清理时机：步骤 5 是唯一不可逆操作，必须先通过本地 + 构建测试；官方以 ⚠️ 警告标出。
- Submodule 指针漂移：
git submodule update --remote --merge会把 submodule 指针推到内容仓库最新 commit，之后必须在代码仓库中提交该指针变更，否则 CI 仍会拉取旧内容。 - Mizuki → Shirone 的迁移没有自动脚本：本仓库未提供跨项目迁移工具，需手动搬运内容资产。
Performance / Operational Notes
- 内容体量主导迁移耗时：五步流程中最耗时的是复制图片（
public/images/albums、public/images/diary），首次git push内容仓库的耗时与图片总量正相关。 - 日常同步成本：分离后每次写博客 = 内容仓库一次 commit + 代码仓库一次
pnpm run sync-content（Submodule 模式下还需提交指针），相比单仓库多一步，换取内容私有化与模板可独立升级。 - 官方建议：迁移前先在测试环境中验证整个流程。
Source: MIGRATION_GUIDE.md
Related Links
- Shirone 新项目仓库：https://github.com/lyraVoid/shirone
- Mizuki 停更公告 - README.md（另有 en / ja / tw 版本）
- docs/MIGRATION_GUIDE.md - 本页主要来源文档
- docs/CONTENT_SEPARATION.md - 内容分离完整指南（环境变量全集、私有仓库、CI/CD）
- docs/CONTENT_REPOSITORY.md - 内容仓库结构说明
- docs/DEPLOYMENT.md - 部署完整指南
- docs/AUTO_BUILD_TRIGGER.md - 内容更新自动触发构建
- docs/README.md - 文档索引导航
- Git Submodule 官方文档（来自迁移指南参考文档章节）