背景
2026年4月29日，完成 3 篇 MLCC 行业深度研报和 3 个交互式 HTML 数据看板的数字花园部署（notes.zhuzg.com），同时确保 Obsidian 本地环境正常打开。
核心矛盾：Quartz 的 SPA 路由会拦截站内链接，通过 micromorph 进行增量渲染——这对于标准 Markdown 页面没有问题，但对于内含 Chart.js/Tailwind CDN 脚本的外部 HTML 文件，增量渲染不会重新执行 <script> 标签，导致看板渲染为空白页面。
核心概念说明
什么是 SPA？
SPA（单页应用）是一种前端架构模式：用户访问站点后，后续页面切换不再重新加载整个网页，而是由前端路由拦截链接点击，动态取回内容并渲染。好处是切换快、流畅；代价是某些特殊资源（如独立 HTML 文件）在被 SPA 捕获处理时，其内嵌脚本和环境依赖可能无法正确执行。
什么是 Quartz？
Quartz 是一个将 Markdown 笔记编译为静态网站的工具。它生成的页面默认启用 SPA 路由。
整体架构（最终方案）
D盘知识库（主数据源）
├── 行业研究/
│ ├── 3篇报告.md ← 研报原文
│ └── 3个看板.html ← 交互式图表（Obsidian 点链接打开）
│
└── 网站展示/ ← 公网发布副本
└── 行业研究/
├── 3篇报告.md
└── index.md
Quartz 站点：
notes.zhuzg.com/static/*.htm ← SPA 路由跳过 /static/，直接加载看板
问题排查与解决
阶段一：本地部署（Obsidian）
将 HTML 文件置于研报同级目录，Markdown 表格中引用相对路径。✅ 一次性通过，耗时 2 分钟。
阶段二：Quartz 基础设施适配（3个实用教训）
问题 1：静态文件路径错误
- 现象：
npx quartz build后public/static/未生成文件 - 原因：Quartz 静态文件插件读取路径为
~/quartz/quartz/static/，而非~/quartz/static/——差了一层子目录 - 处理：将文件移至正确路径
问题 2：文件名兼容性
- 现象：含中文和空格的文件名导致链接 404
- 原因：Quartz 对
.html后缀执行路由重写 - 处理：文件名改为英文无空格格式，后缀改为
.htm——Quartz 不识别此后缀，原样发布
问题 3：误删网站首页
- 现象：站点侧边栏仅显示旧文件夹，行业研究入口丢失
- 原因：
rm -rf ~/quartz/content/*删除了根目录的index.md - 处理：从 git 历史恢复，重新补充导航链接
阶段三~四：SPA 路由排查（压缩版）
针对 SPA 拦截导致看板空白的问题，先后尝试了 7 种方案（站内链接、完整 URL、关闭 SPA、注入自愈脚本、修改源码、target="_blank"、跳转页面）以及独立部署外部仓库——全部失败或在架构上不可接受。
最大教训：前 6 个方案在应用层解决问题，第 7 个在架构层绕路，而正确的解法在路由层——错误的层面浪费了 ~3 小时。
阶段五（最终方案）：一行代码
回到 Quartz SPA 路由源码，在路由拦截逻辑入口处增加一条判断：
// /static/ 路径下的文件由浏览器直接加载，SPA 不拦截
if (a.pathname.startsWith("/static/")) return逻辑说明：SPA 路由的 routerIgnore 逻辑允许对特定路径前缀放行。/static/ 目录下的看板文件被设定为直接全页加载，绕过增量渲染，确保 Chart.js 和 Tailwind CDN 脚本正常执行。
| 指标 | 结果 |
|---|---|
| 看板地址 | https://notes.zhuzg.com/static/mlcc-overview.htm |
| 访问方式 | 点链接直接全页加载，零跳转 |
| 渲染效果 | 秒开、正常渲染，无需手动刷新 |
| 外部依赖 | 无（回归单一域名 notes.zhuzg.com） |
时间成本统计
| 阶段 | 耗时 | 评价 |
|---|---|---|
| 本地部署（Obsidian） | 2 分钟 | ✅ 一次性通过 |
| Quartz 基础设施适配 | ~1 小时 | 常规环境配置 |
| SPA 路由排查（7个方案 + 独立部署） | ~2.5 小时 | ❌ 错误的解决层面 |
| 最终方案（一行代码） | ~10 分钟 | ✅ 正确方案 |
总耗时约 4 小时。正确方案耗时约 10 分钟。其余时间处于错误方向。
经验记录
1. 理解问题的层面归属
SPA 路由问题是框架层问题。在应用层解决（注入脚本、修改渲染逻辑）或在架构层绕路（独立部署）都是错误的方向。在错误的层面寻找解决方案是最大的时间损耗来源。
2. 方案连续失败 2 次应重新评估
同一个方向连续尝试 2 个不同方案均不通过，应退回去重新定义问题，而非在当前框架内继续尝试变种方案。
本文写于 2026-04-29 · 基于 Hermes Agent + Quartz 数字花园平台