从零搭建：Quartz + Cloudflare Pages 博客

从技术选型到上线，记录用 Quartz v4.5.2 + Cloudflare Pages 搭建个人博客的完整过程。

1. 技术选型

为什么选 Quartz？

选之前试了不少方案：

方案	优点	缺点	结论
Hexo	主题丰富	跟 Obsidian 不怎么兼容	放弃
Hugo	构建快	同上	放弃
Obsidian Publish	官方方案	$8/月，自定义空间小	放弃
Digital Garden	Obsidian 内直发	样式简陋，依赖单一插件	放弃
Quartz v4	原生支持 Obsidian 语法，SSG，免费部署	社区插件少，得改源码	选了

最终技术栈

Quartz v4.5.2（Node.js，支持 JSX 组件）
Obsidian 风格 Markdown
GitHub 私有仓库
Cloudflare Pages 部署
自定义域名（阿里云）
Cloudflare SaaS + Worker 做国内加速
Giscus 评论（基于 GitHub Discussions）

2. 环境准备

系统要求

Node.js >= 22（Quartz 4.5.2 需要）
Git
npm

工具安装

# macOS
brew install node git
 
# 确认版本
node -v   # >= 22.x
git -v
npm -v

GitHub 账号准备

注册 GitHub 账号
安装 GitHub CLI：brew install gh
登录：gh auth login

3. 初始化 Quartz 项目

# 克隆 Quartz
git clone https://github.com/jackyzha0/quartz.git quartz-blog
cd quartz-blog
 
# 安装依赖
npm i
 
# 本地预览（默认端口 8080）
npx quartz build --serve

项目结构

quartz-blog/
├── content/          # Markdown 内容（你的笔记放这里）
├── quartz/
│   ├── components/   # UI 组件（JSX/TSX）
│   ├── plugins/      # 构建插件（transformer/filter/emitter）
│   └── static/       # 静态资源（favicon、logo 等）
├── quartz.config.ts  # 主配置文件
├── quartz.layout.ts  # 页面布局配置
└── public/           # 构建输出（不提交到 Git）

4. 导入内容

内容来源

以 Obsidian 中的学习笔记为例，假设目录结构如下：

my-notes/
├── 分类A/（子分类1、子分类2、子分类3 ...）
├── 分类B/（子分类1、子分类2、子分类3 ...）
├── 分类C/（子分类1、子分类2、子分类3 ...）
└── 分类D/（子分类1、子分类2 ...）

复制内容到 Quartz

# 复制 Markdown 和图片到 content 目录（保留原始文件不动）
cp -r /path/to/my-notes/* content/
 
# 根据你的内容规模可能有：几十到上百篇 Markdown + 大量图片

创建首页

创建 content/index.md：

---
title: My Blog
---
 
# Welcome
 
这里是我的学习笔记博客。

创建各分类的 index 页面

每个文件夹（如 分类A/）需要一个 index.md 作为目录页，Quartz 才会正确生成文件夹页面。

关键配置：图片路径

// quartz.config.ts
Plugin.CrawlLinks({ markdownLinkResolution: "relative" })

注意：内容使用相对路径引用图片（如 assets/img.png），必须用 "relative" 而非默认的 "shortest"，否则图片路径解析会出错。

5. 推送到 GitHub

创建私有仓库

gh repo create my-blog --private

配置 .gitignore

node_modules/
public/
.quartz-cache/
tsconfig.tsbuildinfo

踩坑：初次提交时忘记忽略 node_modules/，仓库 234MB 推送直接超时。最后 rm -rf .git 重来了。

分批推送（大仓库必看）

由于图片总计约 150MB，一次性推送容易超时失败。采用分批推送：

# 第 1 次：推送代码 + Markdown（约 14MB）
git add --all -- ':!content/**/assets/'
git commit -m "Initial commit: code and markdown"
git push origin main
 
# 第 2-N 次：按文件夹逐批推送图片
git add content/分类A/
git commit -m "Add images: 分类A"
git push origin main
# ... 重复其他文件夹

6. 部署到 Cloudflare Pages

步骤

登录 Cloudflare Dashboard
进入 Workers & Pages → Create
选择 Connect to Git → 选择你的 GitHub 仓库
配置构建设置：
- Build command: npx quartz build
- Build output directory: public
- Environment variable: NODE_VERSION = 22

踩坑：Cloudflare Pages 默认 Node 20，Quartz 4.5.2 要求 >= 22，不手动设环境变量构建必挂。

自动部署

每次 git push 到 main 分支，Cloudflare Pages 会自动拉取并构建，通常 1-2 分钟完成。

构建后可通过 <your-project>.pages.dev 访问。

7. 自定义域名

购买域名

在域名注册商（如阿里云万网）购买域名，例如 example.cn。

绑定到 Cloudflare Pages

Cloudflare Pages 项目 → Custom domains → 添加你的域名
在域名 DNS 添加 CNAME 记录指向 <your-project>.pages.dev

注意：如果域名直接托管在 Cloudflare，DNS 配置会自动完成。

这是系列文章的第一篇，后续内容：

Shizi's Blog

Explorer

01_从零搭建_Quartz_Cloudflare_Pages_博客