Quartz 4

Obsidian + Quartz +Github数字花园搭建

7 min read

❌ 主要错误原因分析

  1. 代码块未闭合（致命错误）：
    • 你写了开始的 ```bash，但是忘记写结束的 ```。这会导致 Markdown 渲染器把后面的所有文字（包括标题、正文）都当成代码显示，导致排版全乱。
  2. 表格被关在了代码块里：
    • 你把表格语法（| -u | ... |）放在了代码块（```）内部。在代码块里，Markdown 语法是不生效的，它只会显示为纯文本字符。表格必须放在外面。
  3. 层级混乱：
    • 在解释 sync 原理时，使用了 ### 标题，但放在了代码块里，导致无法生成目录索引。
如果要写：   “---”
结构： 必须成对出现
或者直接不要这个就不用写。

💡 改进建议

  • 分离指令与说明：不要把所有东西都塞进一个代码框。命令归命令，解释归解释。
  • 表格独立：表格前后要留空行。
  • 命令清晰化：像代理设置这种长命令，最好分行写，方便复制。

📘 Obsidian + Quartz 数字花园搭建手册 (隐私保护版)

🛠 核心架构逻辑

这是一个**“源码私有，网站公开”**的架构，确保你的笔记原稿安全，同时免费发布。

  1. 本地 (Local): Obsidian (写作) + Quartz (编译工具)。
  2. 中转 (Storage): GitHub Private Repo (私有仓库，只有你能看)。
  3. 发布 (Deploy): Cloudflare Pages (从私有仓库拉取代码，构建静态网页并公开)。

一、 环境准备 (一次性)

1. 软件要求

  • Git: 用于版本控制。
  • Node.js: 必须 v22+ (Quartz v4.5+ 强制要求)。

2. 本地初始化 (最稳妥的 git clone 法)

由于网络原因，推荐直接克隆源码而不是使用 npm 脚手架。

# 1. 下载源码
git clone https://github.com/jackyzha0/quartz.git my-garden
 
# 2. 进入目录
cd my-garden
 
# 3. 安装依赖 (读取 package.json 安装工具)
npm install
 
# 4. 【关键】切断官方历史
# Windows: rm -r -force .git
# Mac/Linux: rm -rf .git
 
# 5. 初始化自己的 Git
git init
git add .
git commit -m "Initial setup"
git branch -M v4
 
---
 
## 二、 云端连接 (一次性)
 
### 1. GitHub (私有仓库)
*   **创建**: 新建仓库 -> 仓库名随意 -> **Visibility: Private** (必须私有) -> 初始化时不勾选任何文件。
*   **连接**:
    ```bash
    git remote add origin https://github.com/你的用户名/仓库名.git
    git push -u origin v4
    ```
 
### 2. Cloudflare Pages (构建托管)
*   **入口**: Dashboard -> Workers & Pages -> Create -> Connect to Git。
*   **授权**: 选中刚才的私有仓库。
*   **配置**:
    *   **Project Name**: 决定二级域名 (如 `my-notes.pages.dev`)。
    *   **Framework**: 选 `Quartz` (或手动填 `npx quartz build` / 输出目录 `public`)。
*   **环境变量 (至关重要)**:
    *   变量名: `NODE_VERSION`
    *   值: `22` (修复 Build 失败的核心)。
 
---
 
## 三、 日常使用流程 (Workflow)
 
### 1. 写作 (Writing)
*   打开 Obsidian，加载 `my-garden` 文件夹。
*   **规则**: 所有要发布的文章必须放在 **`content`** 文件夹内。
*   **图片**: 直接粘贴到 Obsidian，会自动存入附件目录，Quartz 能识别。
*   **隐藏**: 如果不想发布某篇文章，在文件头 (Frontmatter) 添加 `draft: true`。
 
### 2. 预览 (Preview - 可选)
想在本地看看效果再发布？
```bash
npx quartz build --serve
# 访问 http://localhost:8080，按 Ctrl+C 停止

3. 发布 (Publish)

写完后，一键同步到云端（在终端quartz文件夹下执行这个命令）：

npx quartz sync
  • 逻辑: 自动备份到 GitHub (私有) → 触发 Cloudflare 自动构建 → 网站更新 (约 1-2 分钟)。
  • 访问: notes-eaw.pages.dev

🔎 原理解析：npx quartz sync 做了什么？

它相当于按顺序执行了以下 Git 命令：

# 1. 暂存所有更改
git add .
 
# 2. 提交更改 (自动生成带时间戳的消息)
git commit -m "update"
 
# 3. 拉取远程更新 (防止冲突，重要！)
git pull --rebase
 
# 4. 推送更改
git push origin v4

Git Push 参数详解（如果需要手动执行）：

参数说明
-u设置上游分支（upstream），建立跟踪关系（第一次需用）
origin远程仓库的别名（默认远程仓库名称）（必选）
v4本地分支名（Quartz 默认分支）（必选）

🚨 故障排除：如果 Sync 失败 (网络问题)

如果出现连接超时，请配置 Git 代理（端口号按需修改）：

# 设置代理 (假设端口为 7897)
git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897

如果不需要代理了，务必清除，否则无法直连：

# 清除代理设置
git config --global --unset http.proxy
git config --global --unset https.proxy

四、 个性化配置 (Config)

修改根目录下的配置文件（改完记得 npx quartz sync）：

  1. quartz.config.ts:
    • pageTitle: 网站左上角的标题。
    • theme: 修改颜色（支持十六进制色值）。
    • locale: 语言设置（如 zh-CN）。
  2. quartz.layout.ts:
    • 决定首页显示什么（最近更新、图谱等）。
    • 决定侧边栏显示什么（目录、搜索框等）。

五、 常见故障排查 (Troubleshooting)

现象可能原因解决方案
Cloudflare 构建失败Node 版本过低检查 CF 环境变量 NODE_VERSION 是否为 22
构建失败 (Exit code 1)依赖包损坏本地删除 node_modules 和 package-lock.json，重运行 npm install 后推送
git push 报错仓库非空确保 GitHub 创建仓库时没有勾选 README/gitignore
网站 404没写首页确保 content/index.md 文件存在
图片不显示路径问题尽量使用 Obsidian 默认的 Wiki Link 格式 ![[image.png]]

祝贺你！你现在拥有了一个完全由自己掌控、永久免费、且源码隐私安全的数字花园。 🌱

Graph View

Backlinks