网页知识库搭建说明

现状

本仓库（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 / 忽略规则 / 主题）
│   ├── animations.json                ← 动画页「源文件 → 目标文件名」映射
│   ├── sync-animations.mjs            ← 构建后复制动画页的脚本
│   ├── static-pages\                  ← 新增独立 HTML 页面放这里（自动发布）
│   ├── package.json / package-lock.json
│   ├── preview.py                     ← 本地预览服务器（支持 clean URL）
│   └── .gitignore                     ← 排除 node_modules / public
└── index.md                           ← 站点首页

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

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

打开 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。
进入 Pages 后选 Connect to Git → GitHub → liuchao21/Notes → Install & Authorize → Begin setup。
按下面填写构建设置：

配置项	值
Project name	以 Dashboard 实际显示为准（当前域名 `notes-dsw.pages.dev`）；`notes` 已被占用
Production branch	`main`
Framework preset	None / 留空
Root directory (advanced)	留空（在构建命令里自己 `cd site`）
Build command	见下方代码块（整行复制）
Build output directory	`site/public`
环境变量	添加 `NODE_VERSION` = `24`

cd site && npm ci && node ./quartz/bootstrap-cli.mjs build -d .. -o public && node ./sync-animations.mjs

Root directory 留空是为了让 -d .. 稳定指向仓库根（Cloudflare 会完整 clone 仓库）；若填了 site，部分构建环境可能只把该目录作为上下文，导致读不到笔记。
这一行以后永远不用改：复制动画页的逻辑收在 site/sync-animations.mjs 里，新增页面只改仓库、不动 Cloudflare。修改 Build settings 后保存，下一次构建才会用新配置；直接 Retry 会用重试时已保存的配置。

Save and Deploy，等首次构建完成。之后每次 push 到 main（包括 Obsidian Git 的自动备份提交）都会自动重新发布。
如果之前建过 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 绝对路径执行）。同步脚本本身只用 Node 内置模块，20 也能跑。

cd D:\Thinking\Notes\site
npm ci
node ./quartz/bootstrap-cli.mjs build -d .. -o public
node ./sync-animations.mjs
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。

配置要点（都改了什么）

项	值 / 原因
`baseUrl`	`notes-dsw.pages.dev` —— Pages 项目页，不带协议 / 斜杠 / 子路径
`sync-animations.mjs`	构建后统一复制动画页；Cloudflare Build command 里只留一行 `node ./sync-animations.mjs`，以后永不用改
`locale`	`zh-CN` —— 日期与界面语言
`analytics`	`null` —— 默认模板会把统计发到 Quartz 官方的 Plausible，已关掉
`theme.fontOrigin`	`local` —— 国内不依赖 Google Fonts；`typography` 用微软雅黑 / Consolas
`ignorePatterns`	排除 `.git`、`.github`、`.obsidian`、`site`、`node_modules`、`public`，以及 content 内的 `*/.html`
`publishAssets`	`all` —— 图片等资源原样发布
`@quartz-community/cname`	`enabled: false` —— 避免生成 `CNAME` 干扰部署
中文搜索	Quartz 5 的 FlexSearch 原生支持中日韩分词，无需额外配置；索引在 `static/contentIndex.json`

交互动画页怎么接进来的

Quartz 会把 .html 资源过滤掉（只复制图片等），且 md 笔记里的 .html 相对链接会被重写成无扩展名的内部链接，浏览器不会执行其中的 JS。所以独立 HTML 页面必须单独复制到 public/static/，用完整 https 链接访问。

复制由 site/sync-animations.mjs 统一完成，它有两个来源：

site/animations.json —— 显式映射「目标文件名 → 源文件路径」。现有四篇页面用它，源文件仍留在 vault 各笔记目录，Obsidian 本地可直接打开，不产生第二份：
- netflow.html ← 虚幻引擎/网络/UE 角色移动同步全流程主控端-DS-3P模拟端.html
- ground-movement.html ← 虚幻引擎/移动/UE 原生贴地移动 1P-3P 逻辑.html
- walkingsurface.html ← 虚幻引擎/移动/WalkingSurface 优化实现逻辑.html
- walkingsurface-3d.html ← 虚幻引擎/移动/WalkingSurface 3D 几何图示.html
site/static-pages/*.html —— 约定目录，自动发现。把新 HTML 直接放进去，文件名就是线上 URL 名，脚本自动按原名复制。

新增一个动画页要做什么

把单文件 HTML 放进 site/static-pages/，例如 my-page.html（推荐）；或者如果源文件想留在笔记目录里，就在 animations.json 加一行映射。
在 index.md 或对应笔记里加一条完整的 https://notes-dsw.pages.dev/static/my-page.html 链接。
push。

不需要改 Cloudflare 的 Build command，不需要手动 cp，也不需要 Retry。 如果源文件缺失，脚本会报错并让构建失败，日志里会指出是哪个文件。

为什么不用相对链接

相对 .html 链接会被 Quartz 的 links 内建处理当成内部笔记链接重写，丢掉扩展名，动画就打不开。外部绝对链接是唯一稳妥写法。五篇 HTML 都是单文件自包含（图片以 base64 内嵌），不依赖外部资源目录。

已改动的文件清单

新增：index.md（首页）、site/（Quartz 源码与配置，含 preview.py、
animations.json、sync-animations.mjs、static-pages/）、其他/网页知识库搭建说明.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 命中的路径不会发布。
新增独立 HTML 页面：丢进 site/static-pages/ 并加一条绝对链接即可，见上文「新增一个动画页要做什么」。

Thinking Notes

探索

网页知识库搭建说明

网页知识库搭建说明

架构

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

本地预览

配置要点（都改了什么）

交互动画页怎么接进来的

新增一个动画页要做什么

已改动的文件清单

已知的小提示

关系图谱

目录

反向链接