📚 Quartz 4.5.2 搭建指南
版本：v4.5.2 | 更新：2026.07
从零搭建个人知识库 / 数字花园的完整教程
📖 选择适合你的版本
这里有两份教程，根据你的需求选择：
| 版本 | 适合人群 | 特点 | 阅读时间 |
|---|---|---|---|
| 精简版 | 想快速上手、直接照着做 | 步骤清晰、代码紧凑、避坑为主 | ~15 分钟 |
| 详细版 | 想深入了解、系统学习 | 7 大篇 33 节、面面俱到 | ~2 小时 |
⚡ 精简搭建教程
适合：已经有基础，或者只想快速跑起来的人
包含内容
- ✅ 全新创建项目（4 步）
- ✅ 复制现有项目（3 步）
- ✅ 4 个关键避坑点
- ✅ GitHub Pages 部署
- ✅ 自定义域名配置
- ✅ 日常更新流程
- ✅ 7 个常见问题排查
👉 打开精简版教程
📚 企业级知识库搭建完全指南
适合：想系统学习、长期维护、打造专业知识库的人
7 大篇 33 节完整内容
| 篇章 | 内容 |
|---|---|
| 第一篇：基础部署篇 | 环境准备、项目创建、配置、部署、问题排查 |
| 第二篇：工作流篇 | Obsidian + Git 自动化、目录设计、多设备同步、备份 |
| 第三篇：进阶定制篇 | 主题 CSS、布局定制、评论系统、域名、SEO、统计 |
| 第四篇：高级配置篇 | 工作原理、插件系统、性能优化、故障排查 |
| 第五篇：生产环境篇 | 部署检查清单、日常维护、长期运营 |
| 第六篇：实战项目篇 | 从零搭建个人技术博客完整实战 |
| 第七篇：进阶开发篇 | 源码解析、组件开发、插件开发、二次开发 |
👉 打开详细版教程
🎯 阅读建议
新手推荐路线
- 先看 精简版 → 快速把项目跑起来
- 遇到问题查 常见问题 章节
- 跑通后再看 详细版 → 深入学习优化
有经验的开发者
- 直接看 精简版 → 照着步骤操作
- 需要定制时再查 详细版 对应章节
⚠️ 重要提醒（必看）
💡 4.5.2 专属避坑，提前知道
- Node 版本必须 22+ - 18/20 会报
Unsupported engine- 必须注释 CustomOgImages - 国内网络必报错 fetch failed
- 克隆 v4 分支 - 不是 main 或 master
- 配置文件在根目录 -
quartz.config.ts- baseUrl 很重要 - 配置错了样式全乱、图片 404
🚀 快速开始
准备好了吗？选择一个版本开始吧！
📌 本指南基于 Quartz 4.5.2 版本编写
官方文档（v4）：https://four.quartz.jzhao.xyz/ GitHub 仓库：https://github.com/jackyzha0/quartz