功能	说明
Markdown 转网站	将笔记转换为美观的网页
Obsidian 兼容	原生支持双链、标签、Callout 等语法
双向链接	自动生成反向链接
全文搜索	内置搜索功能
知识图谱	Graph View 可视化知识关联
免费部署	支持 GitHub Pages 等多种托管方式

为什么选 4.5.2 而不是 5.x？

对比项	Quartz 4.5.2	Quartz 5.x
配置文件位置	根目录 `quartz.config.ts`	`.quartz/config.ts`
国内构建成功率	高（注释 OG 图片即可）	较低（插件依赖多）
稳定性	成熟稳定	较新，可能有变化
教程资源	丰富	相对较少

⚠️ 网上很多教程版本混杂，4.x 和 5.x 配置文件位置不同，不要混淆。

2. 环境准备（4.5.2 专属要求）

2.1 必需软件

软件	版本要求	说明
Node.js	v22.0 及以上	⚠️ 4.5.2 强制要求，18/20 会报错
Git	任意最新版	代码版本控制
GitHub 账号	-	用于托管代码和 Pages 部署
Obsidian	任意版本	笔记编辑工具

2.2 检查环境

node -v    # 必须 >= 22
npm -v
git --version

2.3 Node.js 安装

访问 https://nodejs.org/
下载 LTS 版本（推荐 22.x）
安装完成后重启终端

💡 推荐使用 nvm 管理 Node 版本：
nvm install 22 && nvm use 22

3. 获取 Quartz 4.5.2

3.1 方式一：直接克隆（推荐）

git clone -b v4 https://github.com/jackyzha0/quartz.git my-quartz-site
cd my-quartz-site

3.2 方式二：GitHub Template

访问 https://github.com/jackyzha0/quartz
切换到 v4 分支
点击 Use this template → Create a new repository

3.3 项目目录结构

my-quartz-site/
├── content/              # Markdown 笔记内容
│   └── index.md          # 首页
├── quartz/               # Quartz 核心源码
│   ├── components/       # 页面组件
│   ├── plugins/          # 功能插件
│   └── styles/           # CSS 样式
├── quartz.config.ts      # ⭐ 全局配置文件
├── quartz.layout.ts      # ⭐ 页面布局配置
├── package.json          # 依赖配置
└── .github/workflows/
    └── deploy.yml        # 自动部署配置

4. 安装依赖与本地预览

4.1 安装依赖

cd my-quartz-site
npm install

💡 网络慢切换国内镜像：
npm config set registry https://registry.npmmirror.com

4.2 初始化站点

npx quartz create

按提示填写：

选择模板（推荐 obsidian）
选择内容策略
设置 baseUrl（后续可改）
选择链接解析策略（推荐 shortest）

4.3 本地实时预览

npx quartz build --serve

启动成功后打开 http://localhost:8080，修改笔记后自动热重载。

4.4 仅构建不预览

npx quartz build

生成的静态文件在 public/ 目录下。

5. quartz.config.ts 核心配置

5.1 关键坑：注释 CustomOgImages

⚠️ 国内网络必踩坑：CustomOgImages 依赖境外接口生成 OG 分享图，构建时会超时失败。

plugins: [
  Plugin.TableOfContents(),
  Plugin.Backlinks(),
  // Plugin.CustomOgImages(),  // ✅ 必须注释！否则构建 fetch 失败
  Plugin.GraphView(),
  Plugin.Search(),
]

5.2 网站基础配置

configuration: {
  pageTitle: "Python 学习笔记",
  // ⚠️ 必须与实际访问地址一致
  // GitHub Pages："用户名.github.io/仓库名"
  // 自定义域名："example.com"
  baseUrl: "zhangsan.github.io/python-notes",
  enableSPA: true,
  enablePopovers: true,
  locale: "zh-CN",
}

5.3 baseUrl 配置对照表

部署方式	访问地址示例	baseUrl 配置
GitHub Pages（项目仓库）	`https://zhangsan.github.io/python-notes`	`"zhangsan.github.io/python-notes"`
GitHub Pages（用户主页）	`https://zhangsan.github.io`	`"zhangsan.github.io"`
自定义根域名	`https://example.com`	`"example.com"`
自定义子域名	`https://notes.example.com`	`"notes.example.com"`

⚠️ 配置错误表现：样式错乱、图片 404、链接跳转错误、搜索失效

5.4 忽略文件配置

ignorePatterns: [
  ".obsidian",
  ".trash",
  "*.draft.md",
  "templates",
]

5.5 常用插件列表

插件	功能	推荐开启
`Plugin.TableOfContents()`	文章目录	✅
`Plugin.Backlinks()`	反向链接	✅
`Plugin.GraphView()`	知识图谱	✅
`Plugin.Search()`	全文搜索	✅
`Plugin.ObsidianFlavoredMarkdown()`	Obsidian 语法支持	✅
`Plugin.SyntaxHighlighting()`	代码高亮	✅
`Plugin.CreatedModifiedDate()`	创建/更新时间	✅
`Plugin.Sitemap()`	SEO 站点地图	✅
`Plugin.RSSFeed()`	RSS 订阅	⭕ 可选
`Plugin.CustomOgImages()`	OG 分享图	❌ 国内建议关闭

6. GitHub Pages 自动部署

6.1 创建部署工作流

创建文件：.github/workflows/deploy.yml

name: Deploy Quartz site to GitHub Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: "npm" }
      - run: npm ci
      - run: npx quartz build
      - uses: actions/upload-pages-artifact@v3
        with: { path: public }
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

6.2 提交并推送

git add .github/workflows/deploy.yml
git commit -m "添加 GitHub Pages 自动部署"
git push

6.3 开启 GitHub Pages

打开 GitHub 仓库 → Settings → Pages
Source 选择 GitHub Actions
保存设置

6.4 查看部署状态

仓库 Actions 标签页查看工作流运行状态，成功后显示绿色 ✅。

访问地址：https://你的用户名.github.io/你的仓库名/

7. 首页优化与内容组织

7.1 自定义首页模板

编辑 content/index.md：

---
title: Python 学习笔记
description: 个人 Python 从入门到实战完整知识库
tags: [Python, 编程, 学习笔记]
---
 
# 🐍 Python 学习知识库
 
欢迎来到我的 Python 学习笔记站。
 
## 📚 快速导航
 
### 基础入门
- [[Python基础语法]]
- [[数据类型与变量]]
- [[函数与模块]]
- [[面向对象编程]]
 
### 进阶主题
- [[Python装饰器详解]]
- [[生成器与迭代器]]
- [[异常处理]]
- [[文件操作]]
 
## 🔍 如何使用
 
- 左侧 **文件目录** 浏览所有笔记
- 顶部 **搜索框** 快速查找内容
- **知识图谱** 查看笔记关联关系
- **反向链接** 发现相关主题
 
> 💡 本站由 Obsidian + Quartz 4.5.2 构建

📝 上面的 [[Python基础语法]] 等是双链示例，需根据实际笔记文件名修改。灰色双链表示未创建，点击可快速创建。

7.2 推荐目录结构

content/
├── index.md              # 首页
├── 00-Inbox/             # 收件箱
├── 01-Daily/             # 日记
├── 02-Projects/          # 项目笔记
├── 03-Areas/             # 领域知识
│   ├── Python/
│   ├── Linux/
│   └── Git/
├── 04-Resources/         # 参考资料
├── 05-Notes/             # 永久笔记
├── MOC/                  # 知识地图
└── Attachments/          # 图片/附件

8. 常见问题排查

8.1 构建报错：Unsupported engine

原因：Node 版本过低，4.5.2 要求 Node 22+

解决：升级本地 Node 到 22+，修改 deploy.yml 中 node-version: 22

8.2 本地构建报错：fetch failed

原因：CustomOgImages 插件依赖境外接口

解决：quartz.config.ts 中注释 Plugin.CustomOgImages()

8.3 页面 404 / 样式错乱

原因：baseUrl 配置错误

解决：检查 baseUrl 是否与实际访问地址完全一致

8.4 图片不显示

原因：图片路径错误 / baseUrl 配置问题 / 图片不在 content 目录下

解决：

图片放在 content/Attachments/ 目录
使用相对路径引用：![[图片名.png]]
检查 baseUrl 配置

8.5 双链不显示

原因：未启用 ObsidianFlavoredMarkdown 插件

解决：确认 quartz.config.ts 中有 Plugin.ObsidianFlavoredMarkdown()

8.6 GitHub Actions 构建失败

排查步骤：

查看 Actions 日志，定位具体错误
确认 Node 版本为 22
本地 npx quartz build 能否成功
检查是否有语法错误的 md 文件
检查 Workflow permissions 是否为 Read and write

第二篇：工作流篇

9. Obsidian + Git 自动化工作流

9.1 整体架构

Obsidian → Markdown 笔记 → Git → GitHub → Actions → Quartz → GitHub Pages

9.2 日常更新流程

git status          # 查看变更（可选）
git add .           # 添加所有修改
git commit -m "添加 Python 装饰器笔记"  # 提交
git push            # 推送到 GitHub

之后 GitHub Actions 自动构建部署。

9.3 提交信息规范

不要写模糊的：

❌ update
❌ 修改
❌ 更新笔记

推荐清晰描述：

✅ add Python装饰器详解笔记
✅ update Linux命令笔记，新增管道符章节
✅ fix 修复首页链接错误

9.4 一键部署脚本（可选）

Windows：deploy.bat

@echo off
echo Quartz 知识库一键部署
echo.
git add .
set /p msg="请输入提交说明："
git commit -m "%msg%"
git push
echo.
echo ✅ 部署完成！等待 GitHub Actions 构建...
pause

Mac/Linux：deploy.sh

#!/bin/bash
echo "Quartz 知识库一键部署"
git add .
read -p "请输入提交说明：" msg
git commit -m "$msg"
git push
echo "✅ 部署完成！"

chmod +x deploy.sh  # 添加执行权限

10. 知识库目录结构设计

10.1 PARA 方法（推荐）

content/
├── 00-Inbox/          # 收件箱：临时记录、待整理
├── 01-Projects/       # 项目：有明确目标和期限的事项
├── 02-Areas/          # 领域：需要持续关注的知识领域
│   ├── Python/
│   ├── Linux/
│   └── 前端开发/
├── 03-Resources/      # 资源：参考资料、工具、模板
├── 04-Notes/          # 永久笔记：经过整理的原子化知识
├── MOC/               # 知识地图：主题索引、导航页面
└── Attachments/       # 附件：图片、文件等

10.2 MOC（知识地图）设计

MOC（Map of Content）是一个主题索引页面，用于组织相关笔记。

示例：技术知识地图.md

---
title: 技术知识地图
---
 
# 🗺️ 技术知识地图
 
## 编程语言
- [[Python学习路径]]
- [[JavaScript基础]]
- [[Go语言入门]]
 
## 操作系统
- [[Linux命令速查]]
- [[Linux系统管理]]
- [[Shell脚本]]
 
## 开发工具
- [[Git使用指南]]
- [[VSCode配置]]
- [[Docker入门]]

📝 上面的双链是示例，需根据实际存在的笔记文件修改。在 Obsidian 中点击灰色双链可快速创建对应文件。

10.3 命名规范

文件名：使用中文或英文，避免特殊字符
日期格式：YYYY-MM-DD，如 2026-07-18-周报.md
编号前缀：用于排序，如 01-基础语法.md
标签：使用 Front Matter 中的 tags 字段

11. 多设备同步与备份策略

11.1 推荐同步架构

电脑 A ──┐
         ├── GitHub ─── 手机
电脑 B ──┘

不要直接在设备之间复制文件，容易产生冲突。

11.2 标准同步流程

开始工作前：

git pull  # 先拉取最新版本

完成工作后：

git add .
git commit -m "更新内容"
git push

11.3 处理同步冲突

出现 CONFLICT 时：

打开冲突文件，找到 <<<<<<< 标记
手动合并内容，保留需要的部分
删除冲突标记
提交解决后的版本

git status    # 查看哪些文件有冲突
git add .
git commit -m "解决合并冲突"

11.4 3-2-1 备份原则

备份	说明	示例
3 份数据副本	至少 3 份完整数据	电脑 + GitHub + 云盘
2 种存储介质	不同类型的存储方式	SSD 硬盘 + 云存储
1 份异地备份	至少 1 份在不同地理位置	GitHub（云端）

11.5 推荐备份方案

备份层级	位置	更新频率	恢复速度
主备份	本地电脑硬盘	实时	极快
第二备份	GitHub 仓库	每次 push	快
第三备份	云盘（定期打包）	每周/每月	中
第四备份	移动硬盘	每季度/每年	中

11.6 自动备份脚本

Mac/Linux：backup.sh

#!/bin/bash
BACKUP_DIR="$HOME/Backups/knowledge-base"
SOURCE_DIR="$HOME/Projects/my-quartz-site"
DATE=$(date +%Y-%m-%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
cd "$(dirname "$SOURCE_DIR")"
zip -r "$BACKUP_DIR/knowledge-base-$DATE.zip" "$(basename "$SOURCE_DIR")"
find "$BACKUP_DIR" -name "*.zip" -mtime +30 -delete
echo "✅ 备份完成：$BACKUP_DIR/knowledge-base-$DATE.zip"

💡 重要：没有验证过的备份等于没有备份。定期从 GitHub 重新 clone 验证。

12. Git 分支与版本管理

12.1 个人知识库分支策略

对于个人使用，一个 main 分支就够了：

main ────●────●────●────●───→

12.2 进阶：开发分支

如果经常做实验性修改，可以用 dev 分支：

main ──●──────────●─────────→
        \        /
dev ────●──●──●──┘

使用场景：测试新主题、开发自定义插件、大版本升级 Quartz

12.3 常用命令

git log                    # 查看提交历史
git log --oneline          # 简化历史
git log -- 文件名          # 查看某文件修改历史
 
git checkout 提交编号       # 查看旧版本（不修改当前文件）
git checkout HEAD -- 文件名 # 恢复某文件到上一版本
git reset --soft HEAD~1    # 回退到上一个提交（保留修改）
git reset --hard HEAD~1    # 强制回退（丢弃修改，慎用！）

⚠️ git reset --hard 会永久丢弃未提交的修改，使用前确认！

第三篇：进阶定制篇

13. 自定义主题与 CSS

13.1 自定义 CSS 文件位置

创建或编辑文件：quartz/styles/custom.scss

13.2 常用样式修改

修改页面宽度：

.page { max-width: 900px; margin: 0 auto; }

修改字体：

body { font-family: "Noto Sans SC", "Microsoft YaHei", sans-serif; }
code, pre { font-family: "JetBrains Mono", "Fira Code", monospace; }

修改标题样式：

h1 { font-size: 2.2rem; font-weight: 700; margin-top: 2rem; }
h2 {
  font-size: 1.6rem;
  margin-top: 2.5rem;
  padding-bottom: 0.5rem;
  border-bottom: 1px solid #e5e7eb;
}

暗色主题优化：

.dark {
  background-color: #1a1a1a;
  h1, h2, h3 { color: #e5e7eb; }
}

代码块样式：

pre { border-radius: 8px; padding: 1rem; font-size: 0.9rem; line-height: 1.6; }

13.3 主题颜色变量

:root {
  --light: #ffffff;
  --lightgray: #f3f4f6;
  --gray: #d1d5db;
  --darkgray: #4b5563;
  --dark: #111827;
  --secondary: #3b82f6;
  --tertiary: #8b5cf6;
  --highlight: #fef3c7;
}

13.4 移动端适配

@media (max-width: 768px) {
  .page { padding: 0 1rem; }
  h1 { font-size: 1.8rem; }
  h2 { font-size: 1.4rem; }
  pre { font-size: 0.85rem; }
}

14. 页面布局定制（quartz.layout.ts）

14.1 布局结构

┌─────────────────────────────────────┐
│              Header                 │
├──────────┬──────────────┬───────────┤
│  Left    │   Content    │   Right   │
│  Sidebar │              │  Sidebar  │
├──────────┴──────────────┴───────────┤
│              Footer                 │
└─────────────────────────────────────┘

14.2 常用组件列表

组件	位置	功能
`Component.Header()`	顶部	网站标题、导航
`Component.Explorer()`	左侧	文件目录树
`Component.Search()`	顶部	搜索框
`Component.Breadcrumbs()`	文章前	面包屑导航
`Component.ArticleTitle()`	文章前	文章标题
`Component.Content()`	中间	文章正文
`Component.TableOfContents()`	右侧	文章目录
`Component.Graph()`	右侧	知识图谱
`Component.Backlinks()`	文章后	反向链接
`Component.RecentNotes()`	侧边栏	最近更新
`Component.Footer()`	底部	页脚信息
`Component.Comments()`	文章后	评论系统

14.3 布局配置示例

export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TableOfContents(),
  ],
  left: [
    Component.MobileOnly(Component.Spacer()),
    Component.Search(),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.Backlinks(),
  ],
}

14.4 首页布局定制

export const indexPageLayout: PageLayout = {
  beforeBody: [Component.ArticleTitle(), Component.Content()],
  left: [Component.Search(), Component.Explorer()],
  right: [Component.RecentNotes({ limit: 10 }), Component.Graph()],
}

15. 评论系统集成（Giscus）

15.1 为什么选 Giscus

评论系统	优点	缺点
Giscus	免费、开源、基于 GitHub、无广告	需要 GitHub 账号评论
Disqus	用户多、功能全	有广告、免费版有限制
Waline	国产、支持匿名	需要自己部署后端

推荐 Giscus：适合技术类博客，读者大多有 GitHub 账号。

15.2 配置步骤

第一步：开启 GitHub Discussions

打开 GitHub 仓库 → Settings → Features
勾选 Discussions，保存

第二步：获取 Giscus 配置

访问 https://giscus.app
填写仓库信息，生成配置代码

第三步：Quartz 中配置

在 quartz.layout.ts 中添加：

afterBody: [
  Component.Backlinks(),
  Component.Comments({
    provider: "giscus",
    options: {
      repo: "你的用户名/你的仓库名",
      repoId: "你的 repoId",
      category: "General",
      categoryId: "你的 categoryId",
      mapping: "pathname",
      reactionsEnabled: "1",
      emitMetadata: "0",
      inputPosition: "bottom",
      theme: "preferred_color_scheme",
      lang: "zh-CN",
    },
  }),
],

16. 自定义域名配置

16.1 域名类型

类型	示例	配置方式
根域名（裸域）	`example.com`	A 记录
www 子域名	`www.example.com`	CNAME
其他子域名	`notes.example.com`	CNAME

16.2 DNS 配置

根域名（如 example.com）：根域名不能用 CNAME，必须用 A 记录

主机记录	类型	记录值	TTL
@	A	185.199.108.153	自动
@	A	185.199.109.153	自动
@	A	185.199.110.153	自动
@	A	185.199.111.153	自动

www 子域名：

主机记录	类型	记录值	TTL
www	CNAME	你的用户名.github.io	自动

其他子域名（如 notes.example.com）：

主机记录	类型	记录值	TTL
notes	CNAME	你的用户名.github.io	自动

16.3 GitHub Pages 配置

仓库 Settings → Pages
Custom domain 填写你的域名
等待 DNS 检查通过
勾选 Enforce HTTPS（DNS 生效后才可勾选）

16.4 CNAME 文件

配置自定义域名后，GitHub 会在仓库根目录生成 CNAME 文件。

必须提交到 main 分支，否则每次部署会丢失域名配置。

16.5 生效时间

DNS 解析生效：10 分钟 ~ 24 小时
HTTPS 证书签发：几分钟 ~ 几小时
可以用 nslookup example.com 检查解析是否生效

17. SEO 优化指南

17.1 基础优化

网站标题：

// quartz.config.ts
pageTitle: "Python 学习笔记 - 张三的技术博客"

网站描述：

---
title: Python 学习笔记
description: 个人 Python 从入门到实战完整知识库
---

文章 Front Matter：

---
title: Python 装饰器完全指南
description: 深入理解 Python 装饰器的原理、用法和最佳实践
tags: [Python, 装饰器, 进阶]
date: 2026-07-18
---

17.2 标签优化

✅ 使用有意义的标签：python、linux、web开发
❌ 不要用无意义标签：abc、test
每篇文章 3-5 个标签比较合适

17.3 Sitemap 与 robots.txt

Quartz 默认生成 sitemap.xml，确认插件已启用：

Plugin.Sitemap()

创建 static/robots.txt：

User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml

17.4 文件名优化

✅ python-decorator-guide.md
❌ article123.md
❌ 新建文本文档.md

17.5 内容优化建议

标题包含关键词
首段点明主题（前 100 字）
合理使用小标题（H2、H3）
图片添加 alt 描述
文章之间互相链接

18. 网站统计与分析

18.1 推荐统计工具

工具	优点	缺点
Google Analytics	功能强大、免费	国内访问慢、隐私问题
Umami	轻量、隐私友好、可自托管	需要自己部署
Plausible	简洁、隐私友好	付费
百度统计	国内访问快	有广告、数据准确性存疑

18.2 Google Analytics 配置

// quartz.config.ts
analytics: {
  provider: "google",
  tagId: "G-XXXXXXXXXX",
}

18.3 关注哪些数据

基础指标：访问量（PV/UV）、平均访问时长、跳出率

内容分析：热门文章 TOP 10、新发布文章访问趋势、搜索关键词

来源分析：直接访问、搜索引擎、外链推荐

第四篇：高级配置篇

19. Quartz 工作原理与插件系统

19.1 Quartz 本质

Quartz 是一个 静态网站生成器（SSG），核心流程：

Markdown 文件 → 读取解析 → 插件处理（Transformer） → 内容过滤（Filter）
→ 组件渲染 → 生成 HTML/CSS/JS → 输出到 public/ 目录

19.2 三层处理架构

层级	作用	示例
Transformers	转换内容	Markdown 转 HTML、代码高亮、解析双链
Filters	过滤内容	排除草稿、按标签筛选
Emitters	生成输出	生成文章页面、标签页、RSS、Sitemap

19.3 常用 Transformer 插件

插件	功能
`FrontMatter`	解析 YAML Front Matter
`ObsidianFlavoredMarkdown`	支持 Obsidian 语法（双链、标签等）
`GitHubFlavoredMarkdown`	支持 GFM 语法（表格、任务列表等）
`SyntaxHighlighting`	代码语法高亮
`CreatedModifiedDate`	添加创建和修改时间
`Latex`	LaTeX 数学公式支持

19.4 常用 Emitter 插件

插件	生成内容
`ContentPage`	每篇文章的 HTML 页面
`FolderPage`	文件夹索引页
`TagPage`	标签分类页
`Sitemap`	sitemap.xml 站点地图
`RSSFeed`	rss.xml 订阅源
`Static`	静态资源复制

19.5 插件配置方式

plugins: {
  transformers: [
    Plugin.FrontMatter(),
    Plugin.ObsidianFlavoredMarkdown(),
    Plugin.SyntaxHighlighting({
      theme: { light: "github-light", dark: "github-dark" },
    }),
  ],
  filters: [
    // Plugin.RemoveDrafts(),  // 启用后隐藏 draft: true 的文章
  ],
  emitters: [
    Plugin.ContentPage(),
    Plugin.FolderPage(),
    Plugin.TagPage(),
    Plugin.Sitemap(),
    Plugin.RSSFeed(),
  ],
}

20. 性能优化策略

20.1 图片优化

优化项	建议
格式	优先使用 WebP，其次 JPG/PNG
大小	单张图片建议 < 500KB
尺寸	宽度不超过 1920px
数量	单篇文章图片不要太多

工具推荐：Squoosh（在线压缩）、TinyPNG、ImageOptim（Mac）

20.2 内容优化

单篇文章不要太长（建议 < 5000 字）
长文章拆分成多个笔记，用双链连接
避免过多的嵌套列表和复杂表格

20.3 插件精简

只启用真正需要的插件
不需要的功能就关掉
插件越多，构建越慢

20.4 GitHub Actions 构建优化

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: "npm"  # 启用 npm 缓存

20.5 构建速度优化建议

减少文件数量：定期清理无用笔记
优化图片：压缩和使用合适格式
精简插件：只保留必要的
本地构建测试：推送前先本地 build 确认

21. 高级故障排查

21.1 调试方法

本地调试：

npx quartz build --serve  # 启动开发服务器

查看生成文件：

ls public/                    # 查看生成的文件列表
cat public/some-page.html | head -50  # 检查某个页面

详细日志：

npx quartz build --verbose

21.2 常见错误排查表

问题	可能原因	检查方向
页面 404	baseUrl 错误	检查配置中的 baseUrl
CSS 丢失	路径问题	baseUrl、public 目录结构
Actions 失败	Node 版本不对	确认 node-version: 22
中文文件打不开	编码问题	文件是否为 UTF-8
双链不显示	插件未启用	ObsidianFlavoredMarkdown
图片不显示	路径错误	图片位置、引用方式
搜索异常	索引问题	Search 插件配置
构建很慢	文件太多	检查 content 目录大小
样式错乱	CSS 冲突	custom.scss 自定义样式

21.3 升级 Quartz 版本

git pull upstream v4
npm install
npx quartz build

⚠️ 升级前先备份、阅读更新日志、在 dev 分支测试后再合并到 main

21.4 版本管理建议

创建 CHANGELOG.md 记录重要变更：

# 更新日志
 
## 2026-07-18
- 升级 Quartz 到 4.5.2
- 添加 Giscus 评论系统
- 优化移动端样式

第五篇：生产环境篇

22. 生产环境部署检查清单

22.1 环境准备

Node.js 已安装（版本 >= 22）
npm 正常运行
Git 已安装并配置账号
GitHub 账号已注册并验证邮箱

22.2 Quartz 项目

项目下载完成（v4 分支）
npm install 成功，node_modules 存在
quartz.config.ts 存在
quartz.layout.ts 存在
content/ 目录存在

22.3 内容准备

22.4 配置检查

pageTitle 已修改（不是默认 Quartz）
baseUrl 配置正确（无 https://）
locale: "zh-CN" 中文设置
CustomOgImages 已注释（国内）
必要插件都已启用

22.5 本地测试

22.6 GitHub 仓库

22.7 部署检查

22.8 功能检查

22.9 SEO 检查

22.10 域名检查（可选）

22.11 安全与备份

23. 日常维护与长期运营

23.1 每日流程

打开 Obsidian → 记录学习内容 → 整理到对应文件夹
→ 添加双链连接 → git add/commit/push → 自动部署

23.2 每周流程

23.3 每月流程

23.4 每年流程

23.5 内容运营策略

质量 > 数量：

不要追求每天发多少篇
每篇笔记都要经过思考和整理
定期回顾和更新旧笔记

持续积累：

知识系统是复利效应
前期可能感觉不到价值
坚持 1 年以上会有质的飞跃

23.6 技术维护策略

关注 Quartz 官方更新
定期升级，但不要追新
稳定是第一位的
大版本升级前先备份测试

23.7 数据安全策略

永远不要只有一份备份
定期验证备份可恢复
重要笔记导出 PDF 存档
考虑导出为其他格式（防 Markdown 格式过时）

第六篇：实战项目篇

24. 实战：从零搭建个人技术博客

24.1 项目目标

完成一个包含以下功能的个人技术博客：

个人技术网站
├── 首页（欢迎 + 导航）
├── 关于我
├── 技术文章
├── 学习笔记
├── 项目展示
├── 知识地图
├── 标签系统
├── 全文搜索
├── Graph 知识图谱
└── 评论系统

24.2 技术架构

Obsidian → Markdown → Git → GitHub → Actions → Quartz → GitHub Pages

24.3 准备工作

所需工具：Node.js 22+、Git、GitHub 账号、Obsidian

检查环境：

node -v    # 确认 >= 22
npm -v
git --version

24.4 创建项目

git clone -b v4 https://github.com/jackyzha0/quartz.git knowledge-garden
cd knowledge-garden
npm install

24.5 设计知识库结构

content/
├── index.md                    # 首页
├── 00-Inbox/                   # 收件箱
├── 01-Daily/                   # 日记
├── 02-Projects/                # 项目
├── 03-Areas/                   # 领域知识
│   ├── Python/
│   ├── Linux/
│   └── Web开发/
├── 04-Resources/               # 参考资料
├── 05-Notes/                   # 永久笔记
├── MOC/                        # 知识地图
├── 关于我.md
└── Attachments/                # 图片附件

24.6 创建网站首页

编辑 content/index.md：

---
title: 我的技术数字花园
description: 记录技术学习、项目实践和个人成长的个人知识库
---
 
# 👋 欢迎来到我的数字花园
 
这里是我的个人技术知识库，记录学习、思考和实践。
 
> 💡 数字花园是一种不断生长的知识空间，不同于博客的时间流，
> 这里的笔记会持续迭代、互相关联。
 
## 🚀 快速导航
 
### 📚 知识地图
- [[技术知识地图]] - 所有技术主题的总索引
- [[学习路线图]] - 我的学习路径和规划
 
### 💻 技术领域
- [[Python 学习笔记]]
- [[Linux 运维指南]]
- [[前端开发]]
 
### 🔧 项目实践
- [[项目列表]] - 我做过的所有项目
 
### 👤 关于
- [[关于我]] - 个人介绍和联系方式
 
---
*本站由 Obsidian + Quartz 4.5.2 构建*

24.7 配置 Quartz

编辑 quartz.config.ts：

configuration: {
  pageTitle: "我的技术数字花园",
  baseUrl: "zhangsan.github.io/knowledge-garden",
  locale: "zh-CN",
  enableSPA: true,
  enablePopovers: true,
}

24.8 设计页面布局

编辑 quartz.layout.ts，配置：

左侧：搜索框 + 文件目录
中间：文章内容
右侧：知识图谱 + 反向链接 + 最近更新

24.9 创建第一篇技术文章

创建 content/03-Areas/Python/Python装饰器详解.md：

---
title: Python 装饰器完全指南
description: 深入理解 Python 装饰器的原理、用法和最佳实践
tags: [Python, 装饰器, 进阶]
date: 2026-07-18
---
 
# Python 装饰器完全指南
 
装饰器是 Python 中非常重要的高级特性，理解装饰器能让你写出更优雅的代码。
 
## 什么是装饰器
 
装饰器本质上是一个函数，它可以在不修改原函数代码的情况下，扩展函数的功能。
 
## 基础用法
 
```python
def my_decorator(func):
    def wrapper():
        print("函数执行前")
        func()
        print("函数执行后")
    return wrapper
 
@my_decorator
def say_hello():
    print("Hello!")


### 24.10 建立 MOC 知识地图

创建 `content/MOC/技术知识地图.md`：

```markdown
---
title: 技术知识地图
---

# 🗺️ 技术知识地图

## 🐍 Python

### 基础
- [[Python 基础语法]]
- [[数据类型与变量]]
- [[函数与模块]]

### 进阶
- [[Python 装饰器完全指南]]
- [[生成器与迭代器]]
- [[上下文管理器]]

## 🐧 Linux
- [[Linux 常用命令]]
- [[Shell 脚本编程]]

## 🌐 Web 开发
- [[HTML/CSS 基础]]
- [[JavaScript 入门]]
- [[React 学习笔记]]

## 🔧 工具
- [[Git 使用指南]]
- [[Docker 入门]]

24.11 本地测试

npx quartz build --serve

打开 http://localhost:8080 检查：

24.12 创建 GitHub 仓库

git init
git add .
git commit -m "初始：个人技术数字花园"
git remote add origin https://github.com/你的用户名/knowledge-garden.git
git branch -M main
git push -u origin main

24.13 配置自动部署

创建 .github/workflows/deploy.yml（参考第 6 节 GitHub Pages 自动部署）

24.14 开启 GitHub Pages

Settings → Pages
Source: GitHub Actions
等待部署完成

24.15 第一次上线检查

访问 https://你的用户名.github.io/knowledge-garden/

检查清单：

24.16 后续扩展计划

第一阶段：内容积累 - 目标：100 篇笔记，重点：先把内容写起来

第二阶段：结构完善 - 增加知识地图、完善项目展示、整理技术专题

第三阶段：网站优化 - 绑定个人域名、SEO 优化、添加 RSS 订阅

第四阶段：高级功能 - 评论系统、网站统计、自定义主题、AI 搜索

24.17 最终成果

完成后，你将拥有：

个人博客 + 知识库 + 技术文档 + 项目展示 + 数字花园

这是一个完全属于你自己的知识资产，会随着你的学习不断成长。

第七篇：进阶开发篇

25. 源码架构与自定义组件

25.1 核心设计理念

Quartz 不是普通的博客程序，它的本质是：

Markdown 内容 → 内容处理管道 → 插件系统 → 组件渲染 → HTML 生成

三层架构：

内容层：Markdown 文件
处理层：插件系统（Transformer / Filter / Emitter）
展示层：React 组件 + CSS

25.2 源码目录结构

quartz/
├── quartz/
│   ├── components/       # 页面组件（React）
│   ├── plugins/          # 功能插件
│   │   ├── transformers/  # 内容转换插件
│   │   ├── filters/       # 内容过滤插件
│   │   └── emitters/      # 输出生成插件
│   ├── processors/       # 内容处理器
│   ├── util/             # 工具函数
│   ├── styles/           # CSS 样式
│   └── build.ts          # 构建入口
├── content/              # 用户内容
├── quartz.config.ts      # 用户配置
└── quartz.layout.ts      # 用户布局

25.3 构建流程

执行 npx quartz build 时：

启动 Build：读取配置，初始化插件
读取 Content：扫描 content 目录，读取所有 md 文件
解析 Markdown：用 remark 解析 Markdown 为 AST
执行 Transformers：所有转换器插件处理内容
执行 Filters：所有过滤器插件筛选内容
生成页面：Emitter 插件生成各种页面
输出 HTML：写入 public 目录

25.4 自定义组件开发

Quartz 组件本质上是 React 组件。

示例：创建欢迎横幅组件

创建文件：quartz/components/MyBanner.tsx

import React from "react"
 
interface MyBannerProps {
  title?: string
  subtitle?: string
}
 
export default function MyBanner({ 
  title = "欢迎来到我的数字花园", 
  subtitle = "在这里记录学习、思考和成长" 
}: MyBannerProps) {
  return (
    <div className="my-banner">
      <h1>{title}</h1>
      <p>{subtitle}</p>
    </div>
  )
}

添加组件样式（quartz/styles/custom.scss）：

.my-banner {
  text-align: center;
  padding: 3rem 1rem;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border-radius: 12px;
  margin-bottom: 2rem;
  h1 { margin: 0 0 0.5rem 0; font-size: 2rem; }
  p { margin: 0; opacity: 0.9; }
}

注册组件（quartz.layout.ts）：

import MyBanner from "./quartz/components/MyBanner"
 
beforeBody: [
  MyBanner({
    title: "👋 欢迎来到我的技术花园",
    subtitle: "记录 Python、Linux、Web 开发的学习历程",
  }),
  Component.Content(),
]

25.5 组件类型

组件类型	用途	示例
展示型组件	纯展示，无交互	欢迎横幅、统计卡片
交互型组件	用户操作	搜索框、切换按钮
数据型组件	读取内容数据	最近文章、标签云
布局型组件	组织其他组件	侧边栏、卡片网格

25.6 组件开发建议

从简单开始：先做展示型组件
参考官方组件：学习现有组件的写法
保持组件独立：每个组件只做一件事
考虑移动端：确保在小屏幕上也能正常显示

26. 插件开发入门

26.1 插件类型回顾

类型	作用	开发难度
Transformer	修改内容	⭐⭐
Filter	过滤内容	⭐
Emitter	生成输出	⭐⭐⭐

26.2 Transformer 插件开发

示例：给文章添加阅读时间

创建文件：quartz/plugins/transformers/ReadingTime.ts

import { QuartzTransformerPlugin } from "../types"
 
export const ReadingTime: QuartzTransformerPlugin = () => {
  return {
    name: "ReadingTime",
    markdownPlugins() { return [] },
    htmlPlugins() { return [] },
  }
}

26.3 Filter 插件开发

示例：只发布包含 publish 标签的文章

import { QuartzFilterPlugin } from "../types"
 
export const OnlyPublished: QuartzFilterPlugin = () => {
  return {
    name: "OnlyPublished",
    shouldPublish(_ctx, [_tree, vfile]) {
      const published = vfile.data?.frontmatter?.published
      return published === true
    },
  }
}

26.4 Emitter 插件开发

Emitter 是最复杂的插件类型，负责生成新的页面文件。

示例：生成统计页面

import { QuartzEmitterPlugin } from "../types"
 
export const StatsPage: QuartzEmitterPlugin = () => {
  return {
    name: "StatsPage",
    async emit(ctx, content, resources) {
      const totalNotes = content.length
      const totalTags = new Set(
        content.flatMap(([, vfile]) => vfile.data?.frontmatter?.tags || [])
      ).size
      const html = `
        <h1>📊 知识库统计</h1>
        <p>总笔记数：${totalNotes}</p>
        <p>总标签数：${totalTags}</p>
      `
      return [{ slug: "stats", ext: ".html", content: html }]
    },
  }
}

26.5 插件开发学习路径

初级：配置现有插件，修改参数
中级：理解插件原理，做简单修改
高级：开发自定义插件
专家：贡献插件到社区

27. 二次开发方向建议

27.1 个人 Wiki 系统

可以在 Quartz 基础上打造更完善的个人 Wiki：

增加权限控制（公开/私密）
增加版本对比
增加全文搜索增强
增加知识统计面板

27.2 企业知识平台

企业级应用方向：

团队空间隔离
文档审核流程
权限管理系统
评论和讨论
访问统计分析

27.3 AI 知识助手

结合 AI 技术：

Markdown 笔记 → 向量化处理 → 向量数据库 → AI 问答接口 → 智能知识助手

功能设想：

基于知识库的智能问答
自动生成笔记摘要
智能推荐相关笔记
自动生成知识图谱
写作辅助和润色

27.4 推荐开发路线

初级阶段：掌握 config 配置、掌握 layout 布局、掌握 CSS 自定义

中级阶段：学习 React 组件基础、理解插件系统原理、学习 TypeScript 基础

高级阶段：开发自定义组件、开发简单插件、理解构建流程

专家阶段：开发复杂插件、深度定制主题系统、AI 功能扩展、贡献开源社区

27.5 最终开发架构

                 Quartz 4.5.2
                    |
        ----------------------
        |                    |
    Components          Plugins
        |                    |
    React UI          Content Pipeline
        |                    |
        -------- Build --------
                    |
              Static Website
                    |
        ----------------------
        |                    |
   GitHub Pages         自定义部署

结语

Quartz 4.5.2 不只是一个博客框架，它可以成为：

个人知识操作系统 + 企业 Wiki 平台 + 技术文档系统 + 数字花园引擎

掌握基础配置，你可以快速搭建自己的知识库；深入组件和插件开发，你可以打造完全符合自己需求的知识平台。

最重要的不是工具，而是持续积累的内容。

Obsidian 负责创造知识
     Git 负责保存历史
  GitHub 负责托管保存
  Quartz 负责展示分享

最终形成：属于自己的永久数字资产。

💡 本指南基于 Quartz 4.5.2 版本编写

官方文档（v4）：https://four.quartz.jzhao.xyz/ GitHub 仓库：https://github.com/jackyzha0/quartz

魔客室

探索

Quartz 4.5.2 完全搭建教程

Quartz 4.5.2 企业级知识库搭建完全指南

📋 目录

第一篇：基础部署篇

1. 基础认识