CIJUN的笔记

常见问题与排错

Properties1
tagsquartz, 排错

5 min read

常见问题与排错

基础用法见：Quartz/Quartz 使用教程 部署流程见：Quartz/部署与更新

网站根目录 / 显示 404

原因：Quartz 把 content/index.md 当作首页。笔记仓库根目录缺这个文件，根路径就没有落地页。

解决：在 Obisidian-Note 仓库根目录（不是子文件夹）新建 index.md。

本地预览 npx quartz build --serve 报 [404] /

同样缺根 index.md，或 content/ 是空的（本方案 content 平时为空，本地预览需先手动放一份笔记进去）。确认有 index.md 后重启服务（Ctrl+C 再重跑命令）刷新即可。

部署出来是空站 / 没有笔记

最常见原因：Cloudflare 的 Build command 没拉到笔记。按 Quartz/部署与更新 检查：

  1. Build command 是否为 rm -rf content && git clone ...${GH_PAT}... Obisidian-Note.git content && npx quartz build（不是旧的 git submodule update ...）。
  2. GH_PAT 环境变量是否已配、是否 Encrypt、作用域是否含 Production；token 是否仍有读 Obisidian-Note 的权限。
  3. 改了环境变量后是否点过 Retry deployment 让它生效。

私有仓库在 Cloudflare 上拉不下来：could not read Username

现象：构建日志出现 fatal: could not read Username for 'https://github.com' 或 Authentication failed。

原因：这是本方案踩过的大坑。Cloudflare 在 Build command 之前会自动执行 git submodule update --init --recursive；如果仓库里还残留 .gitmodules / content 子模块指针，它会尝试拉私有笔记但没有凭据，直接失败。

解决：彻底移除子模块，改用 Build command 内 token 克隆（见 Quartz/部署与更新 > Cloudflare Pages 的 Build command）。具体：

cd D:\Quartz\quartz
git rm -r --cached content      # 取消子模块登记
Remove-Item .gitmodules          # 删除子模块配置（若存在）
# content/ 加进 .gitignore，避免空目录被提交
echo "content/" >> .gitignore
git add -A && git commit -m "remove notes submodule, use token clone in build" && git push origin v5

推上去后再把 Build command 改成 token 克隆版并 Retry。

页面样式错乱 / 资源 404

检查 quartz.config.yaml 里的 baseUrl 是否设成你的域名（不带 https://、不带末尾斜杠）：

baseUrl: notes.cijun.win

设错会导致 CSS、JS 等资源路径错误。

图片或附件不显示

  • 把图片放进笔记同目录（或子目录），用相对路径引用：![说明](./img/1.png)。
  • 不要引用 Obsidian 的 file:// 绝对路径。
  • .obsidian 配置目录默认被忽略、不会发布，这是正常的。

双链 [[笔记名]] 不跳转

  • 确认目标笔记文件名与双链一致（含中文 / 空格时要完全匹配）。
  • Quartz 默认开启 wikilink 解析，无需额外配置。

自动化没生效 / 线上没更新

按 Quartz/部署与更新 的自动化四块逐一排查：

  1. E: 的笔记根本没 push 出去 → 检查 Obsidian Git 是否启用自动 push，或手动在 E: 跑 git push origin main。
  2. GitHub Action 红了，报 CF_DEPLOY_HOOK 为空 / 未定义 → 笔记仓库 Obisidian-Note 的 Actions secret 里没配 CF_DEPLOY_HOOK，或 workflow 没 push 上去。补上后重跑 Action。
  3. Action 是绿的，但 Cloudflare 没重新构建 → Deploy Hook 分支填错（应填 v5），或 Hook URL 失效（在 Cloudflare 重新生成并更新 secret）。
  4. Cloudflare 构建了，但内容旧 → GH_PAT 失效 / 权限不够，或 Build command 被改回旧的 submodule 版本（见上「私有仓库拉不下来」）。

怎么升级 Quartz 版本

在 Quartz 项目目录执行 npx quartz update（需保留与原仓库的 upstream 关系，即当初用 create-quartz 或正确 clone 的方式）。

Graph View

Backlinks