常见问题

本页收集博客使用中的常见报错与解决。每个问题按 症状 → 原因 → 解决 组织，命令可直接复制。内容提炼自项目排障手册（docs/TROUBLESHOOTING.md 25 条）与经验库（docs/EXPERIENCE.md），更完整的场景见这两份文档。

1. 缓存不生效（改了没变化）

症状：改了配置/样式/文章，构建后页面还是旧的；或浏览器、PWA 一直显示旧版本。

原因：三层缓存叠加——Hexo 增量缓存（db.json）、hexo server 内存缓存、浏览器/PWA Service Worker 缓存。逐层排除，从最外层开始：

解决：

# ① 先确认是构建产物的问题还是浏览器问题
curl -s http://localhost:4000/ | grep "关键词"   # server 返回新旧？

# ② 构建缓存：hexo clean 是官方清理（删 db.json + public + 重置内部缓存）
#    ⚠️ 不要用 rm -rf public db.json 代替——它不会重置 hexo 内部缓存状态
hexo clean && hexo generate

# ③ server 内存缓存（Docker 容器内）：pm2 restart 不够，需删 db.json
pm2 stop hexo_run && rm -f /app/db.json && pm2 start hexo_run

// ④ 浏览器/PWA 缓存：改 JS/CSS 后必须递增版本号（-r 发布），否则 SW 命中旧版
navigator.serviceWorker.getRegistrations()   // 控制台查看 SW，验证前可注销

预防：改 JS/CSS 用 tools/cicd.sh -r 递增版本号；只改内容用 -c（见「部署」篇发布流程选择）。

2. db.json 权限 / 数据缓存冲突

症状：

FATAL Error: EACCES: permission denied, open '/app/db.json'
FATAL Error: EACCES: permission denied, unlink '/app/db.json'

或：改了 source/_data/*.yml 数据文件后页面空白（site.data.xxx undefined）。

原因：Docker 容器默认以 root 运行，bind mount 挂载的宿主机目录里创建的文件属主是 root，宿主用户删不掉 → EACCES。数据文件空白是 Hexo 增量缓存误判"已缓存未变化"（Cache 哈希更新但 Data model 未写入）。

解决：

# 权限：容器内修复属主
fix_perms() {
    local owner=$(stat -c '%u:%g' /app)
    chown -R "$owner" /app/db.json /app/public/ /app/.cache/
}
fix_perms && hexo clean

# 数据缓存：必须删 db.json 再 generate
rm -f db.json && hexo generate
# 容器 4000 预览：pm2 stop → rm -f /app/db.json → pm2 start（只 restart 不删 db 没用）

# 治本：docker-compose.test.yml 里指定 user
# services.hexo.user: "${PUID:-1000}:${PGID:-1000}"

验证数据加载先删 db.json，否则读到旧缓存假通过。

3. 构建失败（post_link / unknown block tag）

症状：

Cannot find post with slug: xxx          # 文章链接失效
Error: Unable to locate template: xxx     # 模板找不到
unknown block tag: xxx                    # 自定义 tag 拼写/注册失败

原因：post_link 指向的文章不存在或 slug 变了；{% xxx %} 用了未注册的 tag 或写错名；模板路径写错。

解决：

# ① 先定位报错文件与行号（构建输出会给出）
npx hexo generate 2>&1 | grep -A2 "FATAL\|Error"

# ② post_link：确认目标文章存在，slug 用文件名或 front-matter 的 slug
#    博客用 abbrlink 永久链接，文章间链接建议用 post_link + 标题
{% post_link 文章标题 %}

# ③ unknown block tag：检查 themes/matery/scripts/tags/ 下是否注册了该 tag，
#    以及是否写成了行内形式（{% tag %} 无闭合 vs {% tag %}...{% endtag %}）

# ④ 构建卡住：hexo generate 无输出时，用 --debug 看进度
npx hexo generate --debug

预防：改 scripts/ 下脚本后必须 hexo clean 再 generate（普通 generate 可能用旧产物，排查过 1 小时）。

4. 评论不显示

症状：文章底部没有评论框，或评论区空白。

原因：三层开关——全局开关、front-matter 开关、Waline serverURL 配置。

解决：

# ① 主题配置（userConfig/_config.tmp.yml）：
#    查找 waline 段，确认 enable: true 且 serverURL 正确
serverURL: 'https://waline.17lai.site'   # 评论服务地址

# ② 文章 front-matter：是否关闭了评论
---
comments: true    # false 或缺失（取决于模板默认）都会不显示
---

# ③ 验证服务可达
curl -sI https://waline.17lai.site | head -3

注意：评论区注入点（postComments）在模板中调用，确认 layout/_partial/comments/ 下的 waline 模板未被注释；改配置后按第 1 节清缓存验证。

5. 暗色模式异常（–font-scale / CSS 变量）

症状：切到暗色后文字看不清、颜色错乱；或字体大小异常（--font-scale 被重置）。

原因：主题用 CSS 变量实现暗色（[data-user-color-scheme="dark"]），字号是 rem 制随 --font-scale 缩放。异常多为：CSS 变量被硬编码颜色覆盖、字号刻度被改动、或浏览器缩放偏好干扰。

解决：

// ① 控制台确认暗色变量是否生效
getComputedStyle(document.documentElement).getPropertyValue('--body-bg-color')

// ② 字号异常：检查是否动过字号刻度（rem 制，随 --font-scale 缩放）
//    themes/matery/_config.yml 或模板的 font_size_* 系列
//    --font-scale 由 JS 根据浏览器/用户偏好设置，确认 localStorage 无残留旧值

// ③ 样式覆盖排查：不要用 !important 硬覆盖主题变量（会导致下层样式失效），
//    自定义样式用 var(--xxx) 引用 CSS 变量

原则：自定义颜色一律用 var(--card-bg-color) 这类 CSS 变量（三层架构：配置 → Stylus 变量 → CSS 变量），不要写死 #333（详见「自定义」篇）。

6. 语言切换不生效（localStorage）

症状：点了繁简转换/语言切换按钮，页面不变化或刷新后恢复。

原因：语言偏好存在 localStorage，切换逻辑在对应 JS 里读 theme.preference 配置。不生效通常是：JS 被缓存（旧版无此功能）、localStorage 被清理/禁用、或配置开关被关。

解决：

// ① 控制台看偏好值与配置
localStorage.getItem('language')            // 语言偏好（实际 key 以代码为准）
localStorage.removeItem('xxx')              // 清掉残留旧值后刷新

// ② 确认开关：主题配置 preference 段
//    translate: 中文繁简转换（2026-08-16 已聚合至 preference.translate）
//    旧配置 footer.translate 保留兼容读取，改配置请到 preference 段

// ③ 还是不生效 → 走第 1 节缓存排查（版本号没递增，浏览器跑旧 JS）

预防：涉及 JS 行为的配置改动，用 -r 发布让版本号变化（?v=xx 更新，浏览器拉新版）。

附：问题定位顺序（先按此排查）

步骤	检查	命令
1	构建日志有无报错	`npx hexo generate 2>&1 \\| grep -i error`
2	构建产物是否更新	`curl -s 站点URL \\| grep 关键词`
3	缓存清理	`hexo clean && hexo generate`
4	server 内存缓存	`pm2 stop && rm -f db.json && pm2 start`
5	浏览器/PWA 缓存	版本号递增（`-r`）+ 注销 SW
6	配置真实值	`grep 键名 userConfig/_config.tmp.yml`