RoamMind

用 Quartz 搭建个人知识网站

Properties2
description从 Obsidian 写作、Quartz 构建，到 GitHub/Vercel 部署和自定义域名配置的个人网站搭建实践。
tags项目, 建站, quartz

9分钟阅读

用 Quartz 搭建个人知识网站

这是一份基于 Quartz 的个人网站搭建实践：用 Obsidian 写作，用 Quartz 把 Markdown 笔记构建成静态网站，再通过 GitHub 和 Vercel 自动发布到公网。

适合想把个人笔记、项目文档、教程、读书笔记或数字花园发布出来的人参考。

整体流程

从写作到发布，大致分为五步：

  1. 在 Obsidian 中写作
    先按自己的知识管理习惯自由记录，不必一开始就考虑发布格式。

  2. 整理可公开内容
    将适合公开的文章移动到 content/ 目录，并删除私人上下文、账号信息、未确认结论等内容。

  3. 补全文章元信息
    为文章添加标题、描述、标签、发布日期，并在 Frontmatter 中设置 publish: true。

  4. 提交到 GitHub 仓库
    使用 Git 将内容提交并推送到远程仓库（git push -u origin main），GitHub 作为源码和版本管理中心。

  5. 由 Vercel 自动构建发布
    Vercel 监听 GitHub 仓库变更，每次推送后自动运行 Quartz 构建命令，并将 public/ 目录发布为网站。

flowchart LR
  A[Obsidian 写作] --> B[整理到 content 目录]
  B --> C[补全 Frontmatter]
  C --> D[Git 提交到 GitHub]
  D --> E[Vercel 自动构建]
  E --> F[公开网站]

工具清单

工具作用使用阶段
Obsidian本地 Markdown 笔记编辑器，用于日常写作和知识管理。写作
Quartz将 Markdown 笔记转换为静态网站，支持双链、标签、搜索、关系图等数字花园能力。构建
Node.js / npm提供 Quartz 本地预览、依赖安装和构建所需的运行环境。本地开发 / 构建
Git记录内容和配置变更，方便版本管理和回滚。版本管理
GitHub托管 Quartz 项目仓库，作为 Vercel 自动部署的代码来源。代码托管
GitHub Actions可选，用于在推送后自动检查构建是否成功。自动化检查
Vercel托管静态网站，并在 GitHub 更新后自动部署。网站托管
Vercel Domains管理自定义域名，例如 notes.roammind.com。域名绑定
华为云域名注册注册和管理自有域名，例如 roammind.com。域名
华为云云解析 DNS配置域名解析，将子域名指向 Vercel 或后续国内服务器/CDN。DNS
华为云对象存储 OBS存放公开图片、附件等静态资源，减少仓库体积并方便后续迁移到国内访问链路。图片/附件托管
PicList图床和对象存储管理工具，可将图片上传到 OBS、GitHub、S3 等存储服务。图片上传
Obsidian Image Auto Upload Plugin在 Obsidian 粘贴图片后自动调用 PicGo/PicList 上传，并把本地图片链接替换为远程链接。图片写作流

推荐目录结构

Quartz 默认把 content/ 作为公开内容目录。这个网站的核心内容也都放在这里。

content/
  index.md              # 网站首页
  notes/                # 长青笔记、知识卡片
  projects/             # 项目记录和实践教程
  resources/            # 工具、链接、参考资料
  assets/               # 少量需要随仓库管理的图片或附件
ops/                    # 运行维护的相关文档  
 
quartz.config.ts        # Quartz 站点配置
quartz.layout.ts        # 页面布局配置
vercel.json             # Vercel 构建与部署配置

首页建议承担“入口页”的作用，不必写成进度日志。更清晰的组织方式是：

  • 首页：说明这个网站是什么、如何搭建、当前采用的技术路线。
  • 项目页：记录 Quartz 建站规划、待办和踩坑。
  • 检查清单页：沉淀发布前检查流程。
  • 托管页：单独记录 Vercel、域名、DNS、OBS 等部署细节。

本地预览

首次安装依赖：

npm install

本地构建并预览：

node quartz/bootstrap-cli.mjs build --serve

默认预览地址通常是：

http://localhost:8080

发布前建议至少本地预览一次，重点检查：

  • 首页是否能打开。
  • 双链、标签、目录是否正常。
  • 图片是否能加载。
  • 不该公开的内容是否已经删除。
  • sitemap.xml、robots.txt、index.xml 等站点文件是否正常生成。

文章发布规范

每篇要公开的文章建议包含 Frontmatter：

---
title: 文章标题
description: 一句话说明这篇文章的内容
publish: true
date: 2026-06-11
tags:
  - quartz
  - 建站
---

常用字段说明：

字段作用
title页面标题，影响站内展示和搜索结果。
description页面摘要，适合写成一句清楚的话。
publish是否发布。公开文章设为 true。
date发布时间或最后整理日期。
tags文章标签，用于站内归类和发现。

更多说明可参考：Frontmatter。

图片处理策略

图片建议分两类处理：

  1. 少量关键图片
    可以放在 content/assets/ 中，随仓库一起管理，适合 logo、示意图、固定截图等。

  2. 大量文章配图
    建议上传到对象存储，例如华为云 OBS，再在 Markdown 中引用远程图片链接，避免 Git 仓库过大。

推荐工作流：

flowchart LR
  A[在 Obsidian 粘贴图片] --> B[Image Auto Upload 插件触发上传]
  B --> C[PicList 处理上传]
  C --> D[华为云 OBS 存储图片]
  D --> E[Markdown 中写入远程图片链接]
  E --> F[Quartz 构建页面]

发布前需要确认图片链接是公开可访问的，否则部署成功后页面仍可能出现图片加载失败。

部署到 Vercel

推荐 Vercel 项目配置：

配置项推荐值
Framework PresetOther
Root Directory./
Install Commandnpm ci
Build Commandnode quartz/bootstrap-cli.mjs plugin install --from-config --concurrency 2 && node quartz/bootstrap-cli.mjs build
Output Directorypublic

如果仓库中已经配置了 vercel.json，Vercel 会优先读取其中的构建配置：

{
  "cleanUrls": true,
  "installCommand": "npm ci",
  "buildCommand": "node quartz/bootstrap-cli.mjs plugin install --from-config --concurrency 2 && node quartz/bootstrap-cli.mjs build",
  "outputDirectory": "public"
}

部署成功后，Vercel 会先生成一个默认域名，例如：

https://obsidian-quartz-notes.vercel.app

确认默认域名可以访问后，再绑定自定义域名。

自定义域名

以 notes.roammind.com 为例：

  1. 在 Vercel 项目中进入 Settings → Domains。
  2. 添加域名：notes.roammind.com。
  3. 按 Vercel 提示到 DNS 服务商处添加 CNAME 记录。
  4. 在 Vercel 页面点击 Refresh，直到显示 Valid Configuration。
  5. 访问 https://notes.roammind.com 验证是否生效。

常见 DNS 配置示例：

类型主机记录记录值
CNAMEnotes以 Vercel 页面提示为准

如果后续迁移到国内托管，可以保持站点内容和 Quartz 构建流程不变，只切换 DNS 指向和静态资源托管方案。

相关页面

参考资料

最近的笔记

关系图谱

反向链接