Thinking Notes

网页知识库搭建说明

12分钟阅读

网页知识库搭建说明

现状

本仓库（liuchao21/Notes，私有）既是 Obsidian 笔记库，也是网页知识库的源码仓库。
站点由 Quartz 5.1.0 生成，通过 Cloudflare Pages 的 Git 集成发布：
push 到 main → Cloudflare 自动构建并部署到 https://notes-dsw.pages.dev/。

不用 GitHub Pages 的原因：GitHub Free 计划不支持私有仓库使用 Pages
（创建站点 API 返回 422 Your current plan does not support GitHub Pages for this repository，
部署步骤报 404 Ensure GitHub Pages has been enabled）。Cloudflare Pages 免费且支持私有仓库。

为什么用 Pages，不用现在的 Workers

Cloudflare 现在新建项目默认走 Workers（官方文档写 “Start new projects with Workers”），
2026-11-10 第一次按 Workers 建过一次：wrangler deploy 探测不到 site/public 报错，
补了 wrangler.toml 后部署能成功，但 *.workers.dev 在国内网络打不开：
DNS 被投毒（返回随机假 IP），且即使强制连 Cloudflare 真 IP，TLS 握手也失败
（ERR_SSL_PROTOCOL_ERROR / SEC_E_INVALID_TOKEN）——随便编一个不存在的 workers.dev 子域同样失败，
说明是域名被针对，与站点内容、构建配置无关。换 DNS、改 hosts、重新部署都救不了。
同期 *.pages.dev 和 Cloudflare 自定义域名 TLS 均正常（200 / 404）。
所以最终改回 Cloudflare Pages：不需要买域名，国内可直接访问。

另外 notes.pages.dev 已被别人占用（返回文本 DEPRECATED）；Cloudflare 实际分配的是
notes-dsw.pages.dev（项目名以 Dashboard 显示为准）。
站点内部链接是相对 URL，换域名照常可用，但 baseUrl 和笔记里指向动画页的绝对链接必须同步改，
否则 sitemap / RSS / canonical 和那几个动画入口会指到不存在的地址。

架构

D:\Thinking\Notes\                    ← Obsidian vault（内容，100+ 篇 md）
├── *.md / 各分类/*.md                 ← 直接成为网站页面，零迁移
├── 虚幻引擎\网络\...html              ← 带交互动画的独立页面
├── site\                              ← Quartz 5 源码与配置（构建系统）
│   ├── quartz.config.yaml             ← 站点配置（baseUrl / 忽略规则 / 主题）
│   ├── package.json / package-lock.json
│   ├── preview.py                     ← 本地预览服务器（支持 clean URL）
│   └── .gitignore                     ← 排除 node_modules / public
└── index.md                           ← 站点首页

关键点：内容目录是仓库根（构建时 -d ..），所以笔记不用搬进 content/，Obsidian 的目录结构完全不变；site/、.git/、.obsidian/ 等通过 ignorePatterns 排除。

首次部署（只需做一次，在 Cloudflare 网页操作）

  1. 打开 Cloudflare Dashboard → Workers & Pages → Create application。
    ⚠️ 新版 Create 页面默认全是 Worker 入口（Continue with GitHub / Upload your static files），
    Pages 入口藏在最底部那行小字：「Need to use the legacy Pages workflow? → Continue to Pages」。
    点它才是 Pages 流程；直接点 GitHub 会建出 Worker，其表单有 Deploy command 而不是 Build output directory。
  2. 进入 Pages 后选 Connect to Git → GitHub → liuchao21/Notes → Install & Authorize → Begin setup。
  3. 按下面填写构建设置：
配置项值
Project name以 Dashboard 实际显示为准（当前域名 notes-dsw.pages.dev）；notes 已被占用
Production branchmain
Framework presetNone / 留空
Root directory (advanced)留空（在构建命令里自己 cd site）
Build command见下方代码块（整行复制）
Build output directorysite/public
环境变量添加 NODE_VERSION = 24
cd site && npm ci && node ./quartz/bootstrap-cli.mjs build -d .. -o public && cp "../虚幻引擎/网络/UE 角色移动同步全流程 主控端-DS-3P模拟端.html" public/static/netflow.html && cp "../虚幻引擎/移动/UE 原生贴地移动 1P-3P 逻辑.html" public/static/ground-movement.html && cp "../虚幻引擎/移动/WalkingSurface 优化实现逻辑.html" public/static/walkingsurface.html && cp "../虚幻引擎/移动/WalkingSurface 3D 几何图示.html" public/static/walkingsurface-3d.html

Root directory 留空是为了让 -d .. 稳定指向仓库根（Cloudflare 会完整 clone 仓库）；若填了 site，部分构建环境可能只把该目录作为上下文，导致读不到笔记。
四条 cp 缺一不可，少一条对应动画页就 404。修改 Build settings 后保存，下一次构建才会用新配置；直接 Retry 会用重试时已保存的配置。

  1. Save and Deploy，等首次构建完成。之后每次 push 到 main（包括 Obsidian Git 的自动备份提交）都会自动重新发布。
  2. 如果之前建过 Worker 项目，把它删掉或断开 Git 连接，避免每次 push 多跑一个没用的构建。

关于域名与 baseUrl

实际域名 https://notes-dsw.pages.dev/，与 quartz.config.yaml 的
baseUrl: notes-dsw.pages.dev 一致。
如果之后换了域名（或绑了自定义域名），同步改 baseUrl 一行、index.md 和 4 篇动画笔记里的绝对链接。
不要给 baseUrl 加子路径（如 /Notes/），否则侧边栏绝对路径会多出前缀导致 404。

本地预览

需要 Node ≥ 22 与 npm ≥ 10.9.2（本机系统 Node 是 20.18.0，不够；用 nvm-windows 装 22，或用已装好的 Node 24 绝对路径执行）。

cd D:\Thinking\Notes\site
npm ci
node ./quartz/bootstrap-cli.mjs build -d .. -o public
Copy-Item '..\虚幻引擎\网络\UE 角色移动同步全流程 主控端-DS-3P模拟端.html' '.\public\static\netflow.html'
Copy-Item '..\虚幻引擎\移动\UE 原生贴地移动 1P-3P 逻辑.html' '.\public\static\ground-movement.html'
Copy-Item '..\虚幻引擎\移动\WalkingSurface 优化实现逻辑.html' '.\public\static\walkingsurface.html'
Copy-Item '..\虚幻引擎\移动\WalkingSurface 3D 几何图示.html' '.\public\static\walkingsurface-3d.html'
python preview.py                 # http://127.0.0.1:8177/

为什么必须用 preview.py，不能用 python -m http.server

Quartz 生成的内部链接不带 .html（实际文件是 file.html，URL 却是 /file）。普通静态服务器不认，点双链或刷新就 404（Cloudflare Pages / Workers 的 html_handling 原生支持）。site/preview.py 会给无扩展名路径自动补 .html；另外还保留了一段 /Notes/ 前缀映射，用于兼容早期 GitHub Pages 项目页配置（当前 baseUrl 无子路径，正常不会触发）。

验证：curl -I http://127.0.0.1:8177/虚幻引擎/网络/ue-角色移动同步全流程-主控端-ds-3p模拟端 应返回 200。

npx quartz build --serve 带热重载，但每次重建会清空 public/（需重新复制四篇动画），故本地预览统一用 preview.py。构建产物 site/public/ 不提交到 git。

配置要点（都改了什么）

项值 / 原因
baseUrlnotes-dsw.pages.dev —— Pages 项目页，不带协议 / 斜杠 / 子路径
localezh-CN —— 日期与界面语言
analyticsnull —— 默认模板会把统计发到 Quartz 官方的 Plausible，已关掉
theme.fontOriginlocal —— 国内不依赖 Google Fonts；typography 用微软雅黑 / Consolas
ignorePatterns排除 .git、.github、.obsidian、site、node_modules、public，以及 content 内的 **/*.html
publishAssetsall —— 图片等资源原样发布
@quartz-community/cnameenabled: false —— 避免生成 CNAME 干扰部署
中文搜索Quartz 5 的 FlexSearch 原生支持中日韩分词，无需额外配置；索引在 static/contentIndex.json

交互动画页怎么接进来的

Quartz 会把 .html 资源过滤掉（只复制图片等），且 md 笔记里的 .html 相对链接会被重写成无扩展名的内部链接，浏览器不会执行其中的 JS。因此采用两步：

  1. 把四篇 HTML 文档作为构建后步骤原样复制到 public/static/：
    • netflow.html（三端移动同步流程，源在 虚幻引擎/网络/）
    • ground-movement.html（贴地移动 1P/3P 逻辑，源在 虚幻引擎/移动/）
    • walkingsurface.html（WalkingSurface 优化实现逻辑，图示 + 动图，源在 虚幻引擎/移动/）
    • walkingsurface-3d.html（WalkingSurface 3D 几何图示，Three.js 自包含，源在 虚幻引擎/移动/）
      四条 cp 都写在上面 Cloudflare 的 Build command 里；本地预览也要手动复制一次。四篇 HTML 都是单文件自包含（图片以 base64 内嵌），不依赖外部资源目录。
  2. 笔记里用完整 https 链接指向它们（Quartz 不会重写外部链接），见 index.md 与
    UE 角色移动同步全流程 主控端-DS-3P模拟端、UE 原生贴地移动 1P-3P 逻辑、WalkingSurface 优化实现逻辑、WalkingSurface 3D 几何图示 的 callout。

为什么不用相对链接

相对 .html 链接会被 Quartz 的 links 内建处理当成内部笔记链接重写，丢掉扩展名，动画就打不开。外部绝对链接是唯一稳妥写法。新增动画页时记得同时加 cp 和更新链接。

已改动的文件清单

  • 新增：index.md（首页）、site/（Quartz 源码与配置，含 preview.py）、
    其他/网页知识库搭建说明.md（本文）。
  • 修改：虚幻引擎/网络/UE 角色移动同步全流程 主控端-DS-3P模拟端.md（动画链接改为在线版）。
  • 3 篇笔记的 --- → `***：数学物理/数值分析/Simpson积分法则.md、 虚幻引擎/特效/特效优化之第一次创建开销.md、虚幻引擎/移动/MoveAlongFloor.md。 这三篇把 ---当**水平分隔线**用在文件开头，Quartz 会误判为 YAML frontmatter 并报错； 改成***` 后 Markdown 渲染完全一致，真 frontmatter 的 3 篇（概率目录）保持不动。
  • 已删除：.github/workflows/deploy.yml（GitHub Pages 版）——Free 计划下私有仓库无法启用 Pages，
    留着只会让每次 push 都跑出一个失败的运行；wrangler.toml（Workers 版部署配置）——改回 Pages 后不再需要。
    发布由 Cloudflare Pages 的 Git 集成承担。

已知的小提示

  • 构建会有 KaTeX 的「数学模式内有中文字符」警告（strict=warn），只是警告，公式照常渲染。
  • @quartz-community/og-image 生成分享图时会尝试 Google Fonts，国内会 400 并 fallback 到系统字体，不影响页面。
  • 有 4 个双链指向尚未撰写的笔记（前向传播 / 梯度下降法 / 损失函数），Quartz 会提示但不影响构建。
  • 升级 Quartz：cd site && npx quartz upgrade（会改源码，建议先提交当前状态）。
  • 新加笔记直接写在 vault 里即可；被 ignorePatterns 命中的路径不会发布。

关系图谱

反向链接