LoCreics Space

Day001_Quartz4

5 min read

1. 地基搭建 (Environment)

本阶段核心目标是将 Quartz 运行所需的 Node.js 环境与 Git 工具配置完毕。这是项目运行的硬性条件。

1.1 Node.js 配置 (必须 v22+)

Quartz v4 对 Node 版本有严格要求，必须使用 v22 或更高版本。

  • 下载地址：Node.js 官网 (Current版本)

  • 安装选择：v22.x.x (LTS) → Windows Installer (.msi)。

  • 避坑指南：安装向导中 不要勾选 Tools for Native Modules（会导致安装时间过长且不必要）。

  • 验证安装：打开 PowerShell 输入以下命令，必须显示 v22.x.x：

    PowerShell

    node -v

1.2 Git 与包管理器

  • Git 安装：前往 Git SCM 下载并一路默认安装。

  • pnpm 安装 (推荐)：pnpm 相比 npm 更快且磁盘占用更小。如果曾卸载过 Node，需重新执行安装命令：

    PowerShell

    npm install -g pnpm

2. 源码安装 (Installation)

本阶段目标是从 GitHub 拉取 Quartz 源码并锁定依赖版本。请在期望存放项目的目录（如 D 盘根目录）打开 PowerShell。

2.1 克隆与依赖安装

请依次执行以下三步操作：

PowerShell

# 1. 克隆官方仓库
git clone https://github.com/jackyzha0/quartz.git quartz

# 2. 进入项目目录
cd quartz

# 3. 安装依赖 (使用 pnpm 锁死版本)
pnpm install

3. 初始化与修复 (Initialization)

Windows 环境下（尤其是非 C 盘路径）直接初始化极易报错。本章节包含关键的“预处理”步骤。

3.1 Git 权限预处理 (必做)

在执行初始化前，必须修复 detected dubious ownership 和 remote show upstream 两个常见报错。

PowerShell

# 1. 修复权限白名单 (注意：将 E:/LoCreicsObQz 替换为你实际的项目绝对路径)
git config --global --add safe.directory E:/LoCreicsObQz

# 2. 手动添加上游更新源 (用于骗过初始化脚本的检测)
git remote add upstream https://github.com/jackyzha0/quartz.git

3.2 执行初始化

完成上述修复后，执行 Quartz 的初始化向导：

PowerShell

npx quartz create

  • 交互选项 1：选择 Empty Quartz (从零开始)。

  • 交互选项 2：选择 Shortest path (兼容 Obsidian 默认的双链格式)。

4. 故障排除 (Troubleshooting)

本章节重点解决 CustomOgImages 插件因网络环境导致的构建失败问题。

4.1 CustomOgImages 报错修复

  • 报错现象：构建时提示 Failed to emit from plugin CustomOgImages: fetch failed。

  • 核心原因：该插件需访问 Google Fonts 或 GitHub 资源生成社交媒体预览图，国内网络无法直连。

  • 解决方案：开启全局代理 (Global Proxy)。

4.2 操作步骤

  1. 环境准备：确保你的网络代理软件已开启，并设置为 “全局模式 (Global Mode)”。

  2. 终端代理设置：如果不确定终端是否走了代理，请在 PowerShell 中临时注入代理环境变量（假设端口为 7890）：

    PowerShell

    $env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

  3. 保持配置：不要修改 quartz.config.ts，保留 Plugin.CustomOgImages()。

  4. 重试构建：网络通畅后，资源下载会自动完成。

5. 布局确认 (Layout)

确保最终网页呈现“左侧目录树，右侧大纲”的经典文档布局。

5.1 检查布局配置文件

打开 quartz.layout.ts，检查 defaultPageLayout 部分。默认配置通常无需修改，但需确认包含以下组件：

TypeScript

export const defaultPageLayout: PageLayout = {
  // ...
  left: [
    // ...
    Component.DesktopOnly(Component.Explorer()), // 关键点：左侧文件夹目录
  ],
  right: [
    Component.Graph(),
    Component.DesktopOnly(Component.TableOfContents()), // 关键点：右侧文章导航
    Component.Backlinks(),
  ],
}

6. 启动与验证 (Launch)

一切就绪，开始本地预览。

6.1 注入内容与启动

  1. 迁移内容：将你的 Obsidian 笔记文件夹（Markdown 文件）和图片资源放入项目的 content 文件夹中。

  2. 启动服务：

    PowerShell

    npx quartz build --serve

  3. 访问预览：打开浏览器访问 http://localhost:8080。

    • 注意：首次构建因生成缩略图（OgImages），可能会比后续构建慢几秒钟，请耐心等待。

Graph View