quartz/content/10_Atlas/13_Methodology/Quartz V4 部署实战：从本地到公网的数字花园.md

type	topic	project_status	tags	created	updated	version
engineering	生产力工具	进行中	#project #engineering #demo	2026-02-10 16:35	2026-02-10 16:35	1.0

🏗️ 工程实战：Quartz V4 部署实战：从本地到公网的数字花园

[!abstract] 项目意图

• 目标：将 Synapse-Vault 笔记库通过 Quartz v4 渲染成静态网站，并发布至 GitHub Pages。
• 核心工具链：Node.js (v18.14+), Quartz v4, GitHub Actions.
• 当前版本：V=this.version

🏁 环境准备 (Prerequisites)

• 运行环境：(如 Node.js v18.14+, Python 3.10)
• 依赖安装：

# 在克隆好的 quartz 目录下执行
npm install

💻 核心实现 (Core Implementation)

1. 初始化链接

在终端执行初始化向导，将 Quartz 代码仓库与 Obsidian 笔记库物理关联。

npx quartz create

🔍 选项深度对比

选项	对应行为	适合场景
Empty Quartz	建立一个空的内容目录	从零开始在 Quartz 文件夹里写笔记
Copy an existing folder	物理复制。把你的笔记文件夹里的文件全部拷贝一份到 quartz/content	推荐新手使用。最稳定，不破坏原笔记库，也不怕路径权限问题
Symlink an existing folder	软链接。即 Link an existing Obsidian vault 的本质。在 macOS 系统层建立一个“快捷方式”	进阶使用。实现“实时同步”，你在 Obsidian 改完，网页浏览直接刷新，无需复制

这里选择：Link an existing Obsidian vault（即第三个选项） 并输入笔记库绝对路径。

2. 跨仓库自动同步脚本 (GitHub Action)

在笔记仓库（Synapse-Vault）的 .github/workflows/sync.yml 中配置以下逻辑：

name: Sync to Quartz
on:
  push:
    branches: [ main ]
jobs:
  repo-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Pushing to Quartz Repo
        uses: cpina/github-action-push-to-another-repository@main
        env:
          API_TOKEN_GITHUB: ${{ secrets.QUARTZ_SYNC_TOKEN }}
        with:
          source-directory: '.'
          destination-github-username: '你的用户名'
          destination-repository-name: 'quartz'
          user-email: your-email@example.com
          target-directory: 'content'

🚩 关键步骤与坑点 (Key Steps & Pitfalls)

1. Node 版本：Quartz v4 依赖较高版本的 Node，若 npm i 报错，请检查 node -v。

2. 符号链接 (Symlink)：

   • ⚠️ 踩坑提示：Windows 系统下执行 npx quartz create 必须使用 管理员权限 运行终端，否则无法建立链接，导致 content 文件夹为空。

🧪 测试与验收 (Testing)

• 预期结果：执行 npx quartz build --serve 后，本地 8081 端口可访问美化后的笔记网页。

• 实际表现：

📓 复盘与迭代 (Review)

• 优化空间：默认主题颜色需根据 Synapse-Vault 的风格进行 CSS 微调。

• 下一步计划: 下个迭代笔记名

---

#project #engineering