对于 Obsidian 用户来说，“数字花园（Digital Garden）”不仅是知识的沉淀，更是向外输出的窗口。而在众多静态网站生成器中，Quartz 5.0 凭借极快的原生渲染速度、近乎完美的双链支持以及优雅的交互界面，成为了目前的最佳方案。
本文将为你梳理建立最新的 Quartz 5.0 站点并托管至云端的全流程。我们不谈繁琐的源码魔改与样式美化，只专注最核心的环境准备、安装步骤、GitHub 与 Cloudflare 设置，以及日常更新推送的实战指令。
一、必备的环境支持
Quartz 5.0 基于现代前端技术栈构建，在开始安装之前，请务必确保你的电脑（或服务器）上已经完整配置了以下基础环境：
- Node.js (LTS 版本)：Quartz 核心由 TypeScript 驱动，要求 Node.js 版本必须在
v18.14或以上。 - NPM / NPX：通常随 Node.js 一同自动安装，用于管理依赖包和执行 Quartz 核心脚手架命令。
- Git：用于本地内容的版本管理，以及将笔记推送到远端 GitHub 存储库。
- VS Code (选装)：可用于编辑或查看项目配置文件。
二、GitHub 远端存储库准备
为了让你的数字花园能被全世界访问，我们需要先在 GitHub 建立一个用来存放代码与笔记的存储库：
- 登录 GitHub，点击右上角的
+-> New repository。 - 输入存储库名称（例如：
my-blog）。 - 重要设置 ：不要勾选「Add a README file」、「.gitignore」或「Choose a license」， 必须保持存储库完全空白。
- 点击 Create repository，并复制该存储库的 Git 网址（例如：
[https://github.com/ 你的用户名 /my-blog.git](https://github.com/ 你的用户名 /my-blog.git)）。
三、本地架设与初始化安装
打开终端（Windows 用户强烈建议使用 PowerShell），按顺序执行以下命令完成本地建置：
Step 1. 克隆官方核心仓库
找一个合适的本地目录（例如 G:\git\），将 Quartz 官方的空白模板仓库克隆到本地，并进入该文件夹：
PowerShell
git clone https://github.com/jackyzha0/quartz.git
cd quartz
Step 2. 安装项目依赖
利用 npm 安装项目运行所必须的基础依赖包：
PowerShell
npm i
Step 3. 运行初始化脚手架
使用内置的交互式脚手架初始化你的数字花园。这一步会引导你进行站点绑定：
PowerShell
npx quartz create
请根据终端弹出的提示进行如下选择：
- 选择 Empty Quartz（构建全新的空白站点）。
- 在选择笔记连接方式时，选择 Symlink（软链接模式，最推荐，能让你在原 Vault 写作的同时实时同步，无需手动复制文件）。
- 依提示输入或粘贴你本地 Obsidian 库（Vault）的绝对路径。
Step 4. 自动补齐模板插件 (5.0 关键新增)
为了确保系统核心组件和官方默认插件能够正常工作，在构建前需要运行以下命令，自动安装脚手架引用的所有依赖：
PowerShell
npx quartz plugin install --from-config
Step 5. 关联到你的 GitHub 远端存储库
将本地初始化好的 Quartz 目录与刚才在 GitHub 建立的空白存储库进行绑定并初次推送：
PowerShell
git remote set-url origin [ 你刚才复制的 GitHub 存储库网址]
git branch -M main
git push -u origin main
四、Cloudflare Pages 自动化托管配置
Cloudflare Pages 提供完全免费且速度极快的静态网站托管，与 GitHub 的联动极为无缝。配置完成后，只要 GitHub 有代码推送，它就会自动在云端编译并更新网站：
- 登录 Cloudflare 仪表板，导航至 Compute (Workers & Pages) -> Pages。
- 点击 Connect to Git（连接到 Git），并选择你的 GitHub 帐户。
- 在存储库列表中，选择你刚才建立的存储库，点击 Begin setup。
- 关键构建设置项目（请务必严格填写）
参考官方网站：Quartz Hosting Guide
| Configuration option | Value |
|---|---|
| Production branch | v5 |
| Framework preset | None |
| Build command | npx quartz plugin install && npx quartz build |
| Build output directory | public |
- 点击 Save and Deploy（保存并部署）。此时 Cloudflare 会开始第一次线上构建，完成后就会提供给你一个免费的
*.pages.dev网址。
五、日常写作：本地预览与“三步推送指令”
当你在 Obsidian 中撰写、修改或删除了笔记，想要同步推送到网络上的数字花园时，流程非常简单：
1. 本地预览（选做）
在正式推送前，如果你想在本地检查双链或排版是否正常，可以在 quartz/ 目录下分步执行以下命令启动本地服务器：
PowerShell
# 步骤一：彻底清除本地旧缓存（专治各种本地快取不更新的疑难杂症，这一条不同版本可能执行不成功，直接执行下一条就行）npx quartz create --action clean
# 步骤二：启动本地预览服务器
npx quartz build --serve
启动后打开 http://localhost:8080 即可实时预览。
2. 自动化推送发布（必做）
确认无误后，只需在本地电脑的 quartz/ 目录下执行简单的 三步 Git 同步指令 即可完成发布：
PowerShell
# 步骤 1：将本地所有修改和新笔记存入暂存区
git add .
# 步骤 2：提交更改并附带日志说明（双引号内的文字可自订）git commit -m "更新博文内容"
# 步骤 3：推送到 GitHub 远端仓库
git push origin main
执行完这三步后，你就可以关掉终端了。GitHub 收到你的更新推送后，会立刻触发 Cloudflare Pages 在后台自动帮你打包，1~2 分钟内 你的数字花园就会在线上自动更新完成！
六、推送博文操作与注意事项
1.obisidian 设置中，新建笔记的存放位置建议放在根目录下可以单独设立一个目录比如“附件”，有利于整体打包上传。
2. 需要打包的栏目从 obsidian 目录中复制出来，放到 quartz\content 目录下，然后执行命令“npx quartz build –serve”就会生成预览，html 文件在 quartz 的 public 目录下，可用于静态网站空间使用。
3. 关于域名设置问题，打开你本地的 quartz.config.ts 文件，找到 configuration: 下面的 baseUrl 这一行（它默认可能是 “jackyzha0.github.io/quartz” 或者类似的带小尾巴的地址）。将它精准修改为你自己的独立域名，且后面绝对不要带任何斜杠和尾巴。类似如下：baseUrl: “blogex.ping.us.kg”, 因为静态网站使用的是固定链接，如果这个网址设置错误，会导致主页能打开，博文打不开显示 404 错误。
4.obsidian 的数据库目录可以放置在 onedrive 的网盘里，能实现网络实时储存、下载和更新。
结语： 只要配置好这套自动化工作流，日常发布就变成了简单的 Git 三步命令。你只需专心在 Obsidian 中产出知识，剩下的编译、构建和分发工作通通交给 GitHub 与 Cloudflare 即可！
以上由 AI 模型帮助整理，可能存在缺漏，随着版本更新，也可能出现新状况，可以配合 AI 模型去寻找解决的办法。