今天，我正式将博客从传统的 Hexo 框架迁移到了 Quartz 4。这不仅是前端样式的改变，更是整个知识管理工作流的一次升级。但在迁移过程中，我也踩了不少意想不到的坑，在此记录。
为什么选择 Quartz？
Hexo 是一个非常优秀的静态博客引擎，但随着我的笔记逐渐增多，Hexo 的一些局限性开始显现：
- 发布流程繁琐：每次都需要复杂的生成与推送。
- 与 Obsidian 脱节：Hexo 对 Obsidian 原生特性的支持不够。
- 维护成本：主题配置复杂，插件更新容易导致样式崩坏。
迁移过程中的“坑”与避雷指南
1. 私有仓库与 GitHub Pages 的“冲突”
坑点：我希望保持源码私有（Private），但 GitHub Pages 的免费版不支持私有仓库。 避雷：不要在 GitHub Actions 上死磕。最终我转向了 Cloudflare Pages。它完美支持 Private 仓库的自动构建和发布。
2. Cloudflare Pages 的“Worker 误识别”
坑点：在部署时，Cloudflare 报错：If are uploading a directory of assets... 并要求提供 wrangler.jsonc。
避雷：这是因为 Cloudflare 正在推行新架构。如果系统没能自动识别出是静态站点，它会要求你明确指定 assets 目录。在创建项目时，一定要确保选的是 Pages 选项卡而不是 Workers。
3. Obsidian 预览的“标签陷阱”
坑点：为了美化首页，我尝试在 index.md 中使用 <div> 进行网格布局。结果导致 Obsidian 软件内部无法正常渲染 Markdown 语法（如链接和 Callouts 失效）。
避雷：永远优先使用标准 Markdown 语法。Obsidian 对 HTML 嵌套非常敏感。如果需要网格布局，推荐使用 Frontmatter 中的 cssclasses 配合 quartz/styles/custom.scss 来实现“语义与样式分离”。
Quartz 使用指南：如何高效维护博客？
迁移完成后，日常维护博客变得非常简单，只需掌握以下几个核心环节：
1. 新建文章
你不需要运行类似 hexo new 的命令。
- 推荐做法：直接在 Obsidian 里的
content/目录下新建.md文件。 - 分类方法：直接在
content/下创建子文件夹（如Java核心/），Quartz 会自动在侧边栏生成对应的目录树。
2. 本地预览
在发布之前，你可以在本地查看效果：
npx quartz build --serve访问 http://localhost:8080 即可。它支持热重载，你在 Obsidian 保存文件后，浏览器会自动刷新。
3. 一键同步 (发布)
当你写完文章并准备上线时，只需运行：
npx quartz sync该命令会自动完成：git pull → git add . → git commit → git push。一旦推送成功，Cloudflare Pages 会在 1 分钟内完成构建并更新你的博客。
总结
这次迁移不仅仅是换了个壳，更重要的是建立了一套 “写完即发布” 的心智模型。虽然中间踩了些关于部署环境和预览兼容性的坑，但解决过程也让我对 Quartz 的架构有了更深的理解。
再见，Hexo；你好，Quartz。
提示：本篇文章由 Gemini CLI 协助完成整理与归档。