1. 环境准备

先把软件和账号准备好。本地预览只需要 Node.js。要把网站放到公网，还需要 Git、GitHub 和 Cloudflare。

下面的路径都是例子。D:\Notes 换成你自己的目录就行。

1.1 本机软件

软件	用途	下载
Obsidian	写 Markdown 笔记	https://obsidian.md/download
Node.js 22 或更高	运行 Quartz	https://nodejs.org/
Git	把工程推到 GitHub	https://git-scm.com/download/win

Git 的安装步骤见 Git环境搭建。Node.js 安装时选 LTS，npm 会一起装上。

装好后在终端里检查：

node -v
npm -v
git --version

三条都能打出版本号，再继续后面的步骤。

1.2 账号

发布到公网之前准备两个账号：

GitHub：https://github.com/signup 。用来存放 Quartz 工程。仓库可以设为私有，别人只能打开网页，看不到仓库里的原文。
Cloudflare：https://dash.cloudflare.com/sign-up 。用来把编好的网页放到公网。用 GitHub 登录只能授权仓库，不能代替注册 Cloudflare。

只在自己电脑上看，可以先不注册这两个账号，做完第 4 节的本地预览即可。

2. 文件夹放在哪里

准备两个文件夹：

笔记库：D:\Notes\Blog。用 Obsidian 打开这个文件夹。
Quartz 工程：D:\Notes\quartz。放在笔记库外面。

不要把笔记库的上一级当成网站根目录。上一级如果还放着 Quartz 程序，扫进去会把程序文件也变成网页。

两个文件夹，笔记只存一份

quartz\content 不是另一份笔记。它是指向 Blog 的目录联接，两个路径看到的是同一批文件。在 Obsidian 里改 Blog，就是在改网站内容。不要删掉 Blog，删掉之后 content 里的笔记也会没。

GitHub 上的 content 是推送时拷进去的真实文件。云端没有这个链接。

笔记、本地预览和公网是这样串起来的：

从笔记到公网

3. 建立 Quartz 工程

在放笔记库的那一层执行。--source 指向笔记库，网站只扫描这一层。

npx quartz create --template obsidian --strategy symlink --source "D:\Notes\Blog" --baseUrl localhost:8080

Windows 上建出来的是目录联接，不是快捷方式。自己重做这个链接时用：

mklink /J "D:\Notes\quartz\content" "D:\Notes\Blog"

资源管理器里没有建立这种链接的按钮。鼠标右键拖动能做的是快捷方式，Quartz 读不到快捷方式里面的笔记。

工程建好后，打开 quartz.config.yaml，建议改这几项：

pageTitle：网站名称，例如 Blog
locale：zh-CN
本地预览时 baseUrl 用 localhost:8080
发布后把 baseUrl 改成公网域名，不带 https://，例如 my-blog.pages.dev

4. 本地预览

进入工程目录后执行：

cd /d D:\Notes\quartz
npx quartz build --serve

终端出现 Started a Quartz server listening at http://localhost:8080 后，用浏览器打开 http://localhost:8080 。

这个窗口要一直开着。关掉终端，或在那个窗口按 Ctrl+C，本地网站就停了。停掉本地服务不会影响已经发布的公网网站。

5. 首页

首页是笔记库根目录的 index.md。Quartz 把它当成 http://localhost:8080 。

新笔记要出现在首页，就在这个文件里加一条链接：

- [[笔记标题]]

6. 哪些文件不会出现在网站上

在 quartz.config.yaml 的 ignorePatterns 里写上不想发布的路径，例如：

.obsidian
Excalidraw
*.base
private
templates

这些文件可以留在笔记库里，网站上不会显示。

7. 推到 GitHub

新建一个空仓库，按下面填写。

新建 GitHub 仓库时怎么填

仓库地址类似 https://github.com/你的用户名/blog。

本地 Quartz 工程原来指向 Quartz 官方仓库。发布前把 origin 改成自己的仓库，官方仓库留在 upstream，以后升级 Quartz 还能用：

git remote set-url origin https://github.com/你的用户名/blog.git

这个工程的分支叫 v5。这是 Quartz 第 5 版自带的分支名，不是生产分支的通用叫法。通用的主分支名是 main。Cloudflare 要选的是仓库里真实存在的分支，所以这里填 v5。

第一次推送：

cd /d D:\Notes\quartz
git push -u origin v5

GitHub 如果提示登录失败，先在这台电脑上完成 GitHub 登录，再推一次。

8. 用 Cloudflare Pages 发布

新建网站时选 Pages。如果先进入 Worker 向导，点页面下方的 Continue to Pages。

Cloudflare 里选哪一个入口

然后点 Import an existing Git repository，选中刚才的仓库。构建页按下一张图填写。

Cloudflare 构建页怎么填

仓库还是空的时候，生产分支下拉框里没有 v5。先把代码推上去，刷新页面再选。

pages.dev 地址在创建项目时就定了，之后不能改名。项目名如果别人用过，Cloudflare 会自动加一段字符，例如 my-blog-ab12.pages.dev。想换地址，只能删掉这个 Pages 项目，用新的项目名重建。想用 .com，需要自己的域名，再加到这个项目的自定义域名里。

发布成功后，把 quartz.config.yaml 的 baseUrl 改成页面上显示的那个域名，再提交并推送一次。

9. 以后怎么更新

继续在 Obsidian 里改笔记库，例子里是 D:\Notes\Blog。保存之后网站不会自己变。

到 Quartz 目录里提交并推送到 v5：

cd /d D:\Notes\quartz
git add content quartz.config.yaml
git commit -m "更新笔记"
git push

推送成功后，Cloudflare 会自动重新构建。等几分钟，刷新你的 pages.dev 地址。

停掉自动构建只会让以后的提交不再发布，当前网页仍然能打开。想让公网地址失效，到 Cloudflare 的这个项目里打开 Settings，拉到最下面删除项目。GitHub 仓库和本地笔记都还在。以后想再公开，用同一个仓库重新建一个 Pages 项目。

Blog

探索

Quartz 博客从零搭建