日常同步与维护
学习目标
- 掌握日常内容更新的正确流程
- 学会处理新增章节的同步配置
- 掌握 Quartz 版本升级方法
- 能独立排查常见问题
前置条件
- 完成 03_自动化部署流水线
- 网站已成功上线
1. 日常更新流程
修改已有笔记
# 在 main 分支编辑笔记
git add .
git commit -m "更新 section3 内容"
git push origin main
# → Actions 自动同步并部署添加新笔记
把新文件放到对应章节目录下，正常提交即可：
# 在 main 分支添加新文件
git add section5/新笔记.md
git commit -m "添加新笔记"
git push添加新图片
图片需要先被 git 跟踪，同步工作流才能复制到 v5：
# 将图片放到 image/ 目录
git add image/新图片.png
git commit -m "添加图片资源"
git push未
git add的图片不会被同步。图片引用路径应为../image/xxx.png（相对于content/下各章节目录）。
2. 新增章节的处理
如果新建了 section10/ 等目录，需要更新同步工作流的配置：
编辑 .github/workflows/sync-main-to-v5.yml，找到 for dir 行：
- name: Sync content
run: |
for dir in section0 section1 section2 section3 section4 section5 section6 section7 section8 section9 appendix image; do
rsync -a --delete "$dir/" "v5-branch/content/$dir/"
done新增 section10 到列表中：
for dir in section0 section1 section2 section3 section4 section5 section6 section7 section8 section9 section10 appendix image; do同理，如果不想同步某个目录，从列表中移除即可。
3. 分支切换注意事项
在 main 和 v5 之间切换时，未跟踪的目录（node_modules/、public/、quartz/、.quartz/）会残留在工作目录中。
# 切回 main 后清理 v5 残留
Remove-Item -Recurse -Force node_modules, public, quartz, .quartz这些目录已在 main 的 .gitignore 中，不会影响 git 状态，但会占用磁盘空间。
4. 更新 Quartz 版本
Quartz 官方会持续更新 v5 分支。同步上游更新：
git checkout v5
git fetch upstream v5
git merge upstream/v5
# 解决可能的冲突
npm ci
npx quartz plugin install --latest
npx quartz build --serve # 本地验证
git push5. 故障排查指南
5.1 网站不更新
- 检查 Actions 页面 是否有失败
- 确认
main已推送到远程（git push） - 确认
sync-main-to-v5成功触发 - 确认
deploy成功触发 - 硬刷新浏览器（Ctrl+F5）
5.2 构建失败
常见原因：
| 错误 | 原因 | 解决 |
|---|---|---|
Cannot find module | 依赖缺失 | npm ci 重新安装 |
npm ERR! 404 | 镜像源缺少包 | 设置 registry=https://registry.npmjs.org |
| YAML 解析错误 | 配置格式问题 | 检查缩进和语法 |
| LaTeX 警告 | 数学公式中有中文 | 将中文移出 $...$，或用 \text{} 包裹 |
5.3 图片不显示
- 确认图片文件已
git add到 main 分支 - 确认引用路径正确（如
../image/xxx.png） - 确认
image/目录在同步工作流的同步列表中
5.4 链接 404
Quartz v5 自动处理 wikilink 转换。如果手动编写的链接出现 404：
- 使用相对路径：
../sectionX/文件名.md - 文件名区分大小写
- 特殊字符会被 URL 编码
6. 完全重新部署
如果需要从头开始：
# 删除 gh-pages 分支
git push origin --delete gh-pages
# 重新推送 v5 触发构建
git checkout v5
git push
# 在 Pages 设置中重新选择 gh-pages 分支扩展阅读
常见问题
Q: 推送到 main 后网站没有更新？
去 Actions 页面查看工作流是否正在运行。如果 sync-main-to-v5 失败，查看日志中的具体错误。
Q: 新增了目录但同步没生效？
同步工作流的 for dir 列表需要手动更新。这是为了防止意外同步不需要的目录。
Q: npm ci 和 npm install 有什么区别？
npm ci 根据 package-lock.json 精确安装，速度更快。npm install 会更新 lockfile。在 CI 环境中推荐 npm ci。
练习任务
- 在
image/中放入一张图片，提交后确认网站能正常显示 - 模拟一次新增章节：创建
section10/（可选） - 查看 Actions 日志，熟悉构建输出信息
- 尝试本地修改配置并预览效果
验收清单
- 掌握日常内容更新的完整流程
- 知道如何处理新增章节
- 了解常见故障的排查方法
- 知道如何更新 Quartz 版本