Quartz 4

Obsidian + Quartz +Github数字花园搭建

11 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]]

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

关于git失败的解决方法

一、 命令行网络环境切换指南

在使用命令行工具（如 Git、npm 等）时，它们通常不会自动跟随 Windows 系统的代理设置。因此，当您开关 Clash 等代理软件时，必须手动告诉命令行该怎么走。

1. 开启“科学上网”（Clash 打开时）

当您开启代理时，本地会生成一个监听端口（通常是 7890 或 7897 等）。如果直接拉取或推送速度慢、报错，需要显式地让 Git 走代理端口。

操作步骤： 打开终端执行以下命令（假设您的 Clash 代理端口是 7890）：

Bash

# 1. 设置 Git 全局代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 2. （可选）设置终端当前窗口的环境变量代理
# 如果是 CMD：
set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
# 如果是 PowerShell：
$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"

2. 关闭“科学上网”（直连模式，Clash 关闭时）

当您关闭代理（或者身在日本等无需代理即可访问 GitHub 的网络环境下），本地的 7890 端口就失效了。如果此时 Git 还配置着代理，请求就会撞到一堵“死墙”，导致握手失败或 TLS 错误。

操作步骤： 彻底清空代理配置，让 Git 恢复直连：

Bash

# 1. 取消 Git 全局代理
git config --global --unset http.proxy
git config --global --unset https.proxy

# 2. 清理终端当前窗口的环境变量
# 如果是 CMD：
set http_proxy=
set https_proxy=
# 如果是 PowerShell：
$env:http_proxy=""
$env:https_proxy=""

💡 高效建议： 作为计算机专业的学生，您可以把这两组命令写成两个简单的批处理脚本（比如 proxy-on.bat 和 proxy-off.bat），或者在 PowerShell 中配置 alias（别名），以后敲一个短命令就能一键切换了。

二、 npx quartz sync 到底运行了哪些命令？

npx quartz sync 其实是一个自动化的 Git 工作流包装器。结合您第一条消息里的运行日志，当我们执行这条命令时，Quartz 在后台按顺序帮您悄悄执行了以下 4 条核心 Git 命令：

第一步：暂存所有更改 (Backing up your content)

Bash

git add .

将您新建的 Markdown 笔记和图片（例如 Clash Verge 核心概念...、Pasted image... 等）添加到 Git 的暂存区。

第二步：自动生成提交 (Quartz sync: …)

Bash

git commit -m "Quartz sync: Mar 23, 2026, 10:29 PM"

为您刚刚暂存的文件生成一个带有当前时间戳的 commit。

第三步：拉取远程更新 (Pulling updates from your repository)

Bash

git pull
# 或者更严谨的 git fetch origin 加上 git merge

这一步是为了防止您在多台设备上写笔记导致版本冲突。它会先把你 GitHub 仓库 v4 分支上的最新内容拉取到本地进行合并。

第四步：推送到云端 (Pushing your changes)

Bash

git push origin v4

将您本地的最新 commit（包括刚才打好包的笔记）推送到 GitHub 的远程仓库中。

Graph View

Backlinks