踩坑记录
搭建过程中遇到的各种坑，以及怎么填的。
1. node_modules 被提交到 Git
仓库 234MB，推送永远超时。原来是 .gitignore 漏了 node_modules/。rm -rf .git 重来，教训深刻。
2. Cloudflare Pages 构建失败
报 Error: Quartz requires Node >= 22。Cloudflare Pages 默认 Node 20，环境变量加上 NODE_VERSION=22 就好了。
3. 图片不显示
所有图片 404。排查发现 markdownLinkResolution: "shortest" 把 assets/img.png 解析到了错误路径，改成 "relative" 解决。
4. C/C++ 的 #include 被识别为 Obsidian 标签
#include、#define 居然在 /tags 页面生成了标签。ObsidianFlavoredMarkdown 插件的 parseTags 默认开着，关掉：parseTags: false。
5. SPA 导航 404（文件夹页面）
文件夹页面点文章链接，第一次 404，返回再点就正常。原因是 URL 尾斜杠的问题：
/分类A/+./X→/分类A/X（对）/分类A+./X→/X（错，浏览器把分类A当文件往上解析了）
SPA 路由在跳转时会处理尾斜杠，但漏了两个场景：首次直接加载和浏览器后退。在 spa.inline.ts 里补了 history.replaceState 修正。
根源是 markdownLinkResolution: "relative" 让链接变成相对路径，对尾斜杠敏感。用 "absolute" 没这问题，但 "relative" 对子路径部署兼容更好。
6. TOC 目录不跟随滚动
加了移动端 overflow-x: hidden 之后 TOC 不再 sticky。overflow-x: hidden 挂在 html/body 上会破坏子元素的 position: sticky，限制在 @media ($mobile) 内就好了。
7. 移动端内容偏右
内容区域莫名向右偏。#quartz-body 有 padding: 0 1rem，.center 又有一遍，双重叠加了。删掉 .center 的重复 padding。
8. 中国大陆无法访问
博客在国内加载极慢或打不开。Cloudflare Pages 的 IP 被限速/阻断了，用 SaaS Custom Hostname + Worker 代理绕过，详见国内访问加速。
9. 缩进代码块无语法高亮
所有代码块纯白文字没有颜色。内容用的是 4 空格缩进而不是围栏代码块，Quartz 生成的 <code> 没有 language-xxx class，Shiki 直接跳过了。自写了个 rehype 插件用 highlight.js + 手动规则检测语言注入 class。
附录
项目依赖
{
"highlight.js": "^11.x" // 代码语言自动检测
}关键文件索引
| 文件 | 用途 |
|---|---|
quartz.config.ts | 主配置（主题、插件、站点信息） |
quartz.layout.ts | 页面布局（三栏配置） |
quartz/components/Head.tsx | HTML head（meta、字体、标题） |
quartz/components/PageTitle.tsx | Logo + 标题组件 |
quartz/components/pages/TimelineContent.tsx | 时间线页面 |
quartz/plugins/transformers/syntax.ts | 代码语言检测插件 |
quartz/plugins/transformers/clickableImages.ts | 图片放大插件 |
quartz/plugins/transformers/ofm.ts | Obsidian 语法处理（含图片懒加载） |
quartz/components/scripts/spa.inline.ts | SPA 路由（含 trailing slash 修复） |
quartz/styles/custom.scss | 自定义样式 |
Git 提交历史摘要
- v1.0 — 基础搭建：Quartz 初始化 + 内容导入 + Cloudflare Pages 部署
- v1.1 — Giscus 评论 + 导航栏 + Logo + 时间线
- v1.2 — Explorer 图标 + 主页重构 + 字体 + 配色
- v1.3 — 性能优化（懒加载、CDN 回退、contentIndex 分片）
- v1.4 — SPA 修复 + 返回顶部 + 移动端适配 + PageSpeed 优化
- v1.5 — 主题更换 + Cloudflare SaaS 加速 + 代码高亮 + Lightbox 插件
- v1.6 — SPA 文件夹页尾斜杠修复（初始加载 + 后退导航）
这是系列文章的第五篇：
- 上一篇：代码高亮与插件
- 系列首篇：从零搭建：Quartz + Cloudflare Pages 博客