🔍 故障排查

遇到问题时，先确认错误类型，再按对应章节排查。常见问题一般可在 5 分钟内解决。

按症状分类

1. 网站样式不更新

症状：推送了新 CSS/JS，但网站显示旧样式。

排查步骤（按顺序）

Step 1：强制刷新浏览器

Step 2：禁用浏览器缓存（DevTools）

1. 按 F12 打开 DevTools
2. Network 面板 → 勾选 Disable cache
3. 保持 DevTools 打开状态下刷新页面

Step 3：确认 CDN 缓存

访问 https://www.gifgit.com/（或清缓存工具）清除 CDN 缓存。

Step 4：检查 GitHub Pages 最新 commit

打开 https://github.com/mornikar/mornikar.github.io/commits/main，确认最新 commit 是你的推送。

2. Wiki 文章没出现在博客

症状：编辑了 .wiki/ 文件，但博客上没有这篇文章。

排查步骤

Step 1：检查 frontmatter 是否完整

---
    title: 文章标题          # ✅ 必须有
    type: concepts            # ✅ 必须与目录名一致
    tags: [AI, 学习]         # ✅ 至少一个标签
    created: 2025-09-12      # ✅ 必须是 YYYY-MM-DD
    updated: 2025-09-12      # ✅ 必须是 YYYY-MM-DD
    ---
    

⚠️ 常见错误：date: 2025/09/12 — 斜杠格式会导致 Hexo 无法生成文章！

Step 2：预览转换结果（不修改文件）

wiki-sync.bat --dry-run
    

检查输出中是否包含目标文件。

Step 3：检查 source/_posts/ 是否生成了文件

# Windows
    dir /s /b "source/_posts/*.md" | findstr "关键词"
    
    # 或者直接查看目录
    explorer source/_posts/
    

Step 4：检查 Hexo 编译是否有错误

hexo generate 2>&1
    

观察输出中是否有 [error] 字样。

Step 5：检查文章路径

生成的 URL 应为 /YYYY/MM/DD/标题/ 格式，如： https://mornikar.github.io/2025/09/12/RAG检索增强生成/

3. CI 构建失败

症状：GitHub Actions 显示红色 ❌。

排查步骤

Step 1：查看 CI 日志

1. 打开 https://github.com/mornikar/mornikar.github.io/actions
2. 点击失败的 workflow
3. 点击失败的步骤，查看报错信息

Step 2：常见错误及解决方案

Step 3：手动触发 CI 重试

1. 进入 Actions 页面
2. 点击「Wiki-Hexo 自动部署」
3. 点击右侧「...」→「Re-run all jobs」

Step 4：本地复现 CI 环境

# 清理后重新构建
    hexo clean
    npm install
    node scripts/wiki-to-hexo.js
    hexo generate
    

4. wiki-chat 侧边栏没生效

症状：页面右下角没有出现 🔵 AI 对话按钮。

排查步骤

Step 1：检查 JS 是否加载

在浏览器 Console 中执行：

document.querySelector('.footer-credit a')?.innerHTML
    

• 返回 <span>...</span> → JS 正常 ✅
• 返回带 <br> 或普通文本 → JS 未生效 ❌

Step 2：检查 JS 文件是否存在

访问以下 URL，确认返回 200：

• https://mornikar.github.io/js/wiki-chat.js
• https://mornikar.github.io/js/wikilink.js

Step 3：检查 GitHub Pages 上的 JS 内容

// 在 Console 中执行
    fetch('/js/wiki-chat.js')
      .then(r => r.text())
      .then(t => console.log(t.substring(0, 200)))
    

确认文件内容是最新的（不是旧版本）。

Step 4：检查 CSS 文件

访问 https://mornikar.github.io/css/arknights.css，确认包含 wiki-chat 相关样式。

5. AI 助手对话失败

症状：AI 助手显示但无法发送消息，或收到错误回复。

5.1 检查接入方式

确认当前配置的接入方式与实际需求匹配：

5.2 检查 API 配置

Step 1：打开登录页 /login/

Step 2：检查当前接入模式配置

Step 3：验证各项参数：

• API 地址是否正确
• API 密钥是否有效
• 模型名称是否匹配

5.3 检查 CORS 问题

如果是在线 API 模式出现跨域错误：

1. 确认使用 Cloudflare Worker 代理
2. 检查代理地址是否正确
3. 验证 Worker 是否正常响应

// 测试代理
    fetch('https://dify-proxy.1548324254.workers.dev/health')
      .then(r => r.json())
      .then(console.log)
    

5.4 检查浏览器 Console

1. 按 F12 打开 DevTools
2. 切换到 Console 面板
3. 查看是否有错误信息

常见错误：

• Failed to fetch — 网络问题或 CORS
• 401 Unauthorized — API 密钥错误
• 404 Not Found — API 地址错误

5.5 常见问题解决

6. CSS 样式不完整

症状：arknights.css 体积很小（几 KB），WikiLink、wiki-chat 样式丢失。

原因：hexo-renderer-stylus 已从依赖中移除，Stylus 源文件不会被自动编译进 arknights.css。

解决方案

compile_css.js 在 CI 中独立运行（hexo generate 后），本地也通过 Hexo after_generate hook 自动触发：

# 本地手动触发
    node scripts/compile_css.js
    

验证编译成功：检查 public/css/arknights.css 是否存在且 > 50KB。

7. Pug 渲染错误

症状：页面空白或显示 500 Internal Server Error。

排查步骤

Step 1：检查 hexo7-pug-fix 是否生效

# 检查 patch 文件是否存在
    dir themes/arknights/scripts/
    
    # 检查 node_modules 中是否被 patch
    findstr /s "page" node_modules/hexo-renderer-pug/lib/pug.js | findstr "compile"
    

Step 2：检查 layout.pug 语法

// 正确写法：使用 page 局部变量
    - const _page = page || {}
    if _page.title
      title= _page.title + ' | ' + config.title
    
    // 错误写法：直接调用 is_post()
    // 原因：pug 的 extends 链里 helpers 变量注入有作用域限制
    //- title= is_post() ? page.title + ' | ' + config.title : config.title
    

Step 3：本地测试

hexo clean
    hexo generate
    hexo server
    # 访问 http://localhost:4000 确认页面正常
    

8. GitHub Pages 404

症状：访问 mornikar.github.io 或 /docs/ 返回 404。

排查步骤

Step 1：确认 GitHub Pages 配置

gh api repos/mornikar/mornikar.github.io/pages
    

确认返回：

{
      "source": { "branch": "main", "path": "/" }
    }
    

如果显示 gh-pages 或其他分支，需要切换（见 BRANCHES.md）。

Step 2：确认 CI 已成功推送

1. 打开 https://github.com/mornikar/mornikar.github.io/actions
2. 确认最新的 workflow 显示 ✅
3. 打开 https://github.com/mornikar/mornikar.github.io/tree/main，确认文件存在

Step 3：检查 Pages 构建状态

GitHub Settings → Pages页面显示 built 即为正常。如果显示 deploying，等待 2-3 分钟。

10. Dify 无法访问

症状：http://localhost/v1 无法打开。

排查步骤

Step 1：检查 Docker Desktop 是否运行

1. 打开 Docker Desktop 应用
2. 确认状态显示「Running」
3. 确认 Dify 容器在运行：docker ps | findstr dify

Step 2：重启 Dify 容器

docker restart $(docker ps -q --filter "name=dify")
    # 或
    docker-compose -f D:\path\to\dify\docker-compose.yml restart
    

Step 3：检查端口占用

netstat -ano | findstr ":80 "
    

确认没有其他程序占用 80 端口。

Step 4：检查容器日志

docker logs $(docker ps -q --filter "name=dify" | head -1) --tail 50
    

9. Giscus 评论不显示

症状：文章底部没有 Giscus 评论区。

排查步骤

Step 1：检查配置是否启用

确认 themes/arknights/_config.yml 中 giscus 已启用：

giscus:
      enable: true
    

Step 2：检查 Giscus App 安装

1. 打开 https://github.com/apps/giscus
2. 确认 App 已安装到你的仓库
3. 如果未安装，点击 "Install" 并授权

Step 3：检查 Discussions 功能

1. 进入仓库 Settings → Features
2. 确认 Discussions 已勾选开启
3. 如果未开启，勾选并确认

Step 4：检查浏览器 Console

1. 打开博客文章页面
2. 按 F12 打开 DevTools
3. 切换到 Console 面板
4. 刷新页面，查看是否有 Giscus 相关错误

Step 5：检查网络请求

1. DevTools → Network 面板
2. 筛选 giscus.app 请求
3. 确认请求成功返回（无 CORS 错误）

常见错误及解决

11. Live2D 看板娘问题

症状：看板娘不显示、设置页关闭后消失、移动端无法加载。

排查步骤

Step 1：确认版本

v8.5 及之前版本存在两个已知 Bug：

• 设置页关闭(✕)按钮后看板娘消失 — v8.6 已修复
• 移动端(screen.width < 768)跳过 Live2D 初始化 — v8.6 已修复

更新到 v8.6+ 即可解决。

Step 2：检查 Live2D 是否加载

在浏览器 Console 中执行：

document.querySelector('#waifu') ? 'Live2D 已加载' : 'Live2D 未加载'
    

Step 3：移动端确认

• 移动端看板娘在 Wiki 聊天面板内显示，不在页面左下角浮动
• 打开聊天面板即可看到看板娘区域

Step 4：检查浏览器 Console 错误

常见错误：

• CubismCore not found — live2dcubismcore.js 加载失败
• model3.json 404 — 模型文件路径错误
• Canvas is already in use — 重复初始化

12. 联系方式

如果以上方法都无法解决问题：

1. 查看 CI 日志：https://github.com/mornikar/mornikar.github.io/actions
2. 查看 Wiki 日志：.wiki/log.md
3. 搜索已知问题：检查本文档其他章节是否已有记录
4. 联系维护者：通过 GitHub Issue 反馈

13. URL 异常（双横线/转义字符）

症状：文章 URL 中出现 --（双横线）、\_（下划线转义）、首尾多余横线。

示例：

• ❌ /2026/04/18/LearningNote/2026-04-18--Matplotlib基础-/
• ✅ /2026/04/18/LearningNote/2026-04-18-Matplotlib基础/

排查步骤

Step 1：确认 wiki-to-hexo.js 版本

# 检查脚本头部版本号
    Get-Content scripts/wiki-to-hexo.js -TotalCount 5 | Select-String "version"
    

版本应为 **v4.2+**。旧版本的 slugify() 不清洗首尾横线和下划线。

Step 2：强制重新生成

# --force 会自动清理含双横线的旧文件
    node scripts/wiki-to-hexo.js --force
    

Step 3：重建 Hexo

npx hexo clean
    npx hexo generate
    

Step 4：验证 wiki-index.json

# 检查 URL 字段是否干净
    Select-String -Path source/wiki-index.json -Pattern '"url":' | Select-String "\-\-|\\_"
    

如果输出为空，说明所有 URL 已修复。

Step 5：推送部署

git add -A
    git commit -m "fix: URL卫生修复"
    git push origin source
    

根因

14. WikiLink 跳转 404

症状：点击 WikiLink [[页面名]] 跳转后显示 404。

排查步骤

Step 1：确认 wiki-index.json 存在且格式正确

// 浏览器 Console 执行
    fetch('/wiki-index.json').then(r => r.json()).then(d => console.log(d.length, 'entries'))
    

Step 2：确认目标页面在索引中

// 搜索目标页面
    fetch('/wiki-index.json').then(r => r.json()).then(d => d.filter(e => e.title.includes('搜索词')).forEach(e => console.log(e.title, e.url)))
    

Step 3：检查 URL 格式

URL 应为 /YYYY/MM/DD/Category/YYYY-MM-DD-标题/ 格式，不能有双横线或转义字符。

Step 4：清浏览器缓存

v4.2 更改了 WikiLink 的 URL 来源（从客户端计算改为读取 wiki-index.json），旧缓存的 wiki-chat.js 可能还在用旧逻辑。

根因

15. CMS 保存 wiki 文件格式错误

症状：在 CMS 中编辑 .wiki/ 下的文件后，保存时被额外包装了 Hexo 格式的 frontmatter。

示例： ```yaml # 错误：wiki 文件被双重包装

title: 页面标题 date: 2026-04-25 # ← 不应该有，wiki 文件用 created/updated category: xxx # ← 不应该有 tags: [...]

title: 页面标题 # ← 这是原始 wiki frontmatter type: concepts tags: [...] created: 2026-04-25 updated: 2026-04-25

    ### 排查步骤
    
    **Step 1**：确认 CMS 版本
    
    访问 `https://mornikar.github.io/admin/`，检查是否能看到 Wiki 集合（📚 Wiki 概念、✍️ Wiki 随笔等）。
    
    如果没有 Wiki 集合，说明 CMS 版本过旧。
    
    **Step 2**：确认保存的文件内容
    
    在 GitHub 上查看对应文件，确认 frontmatter 格式正确。
    
    **Step 3**：手动修复
    
    如果文件已被错误包装，删除多余的 Hexo frontmatter 块，只保留 wiki 格式的 frontmatter。
    
    ### 预防
    
    v4.2 的 CMS 会根据集合类型自动选择保存逻辑：
    - **Posts 集合**：自动包装 Hexo frontmatter
    - **Wiki 集合**：原样保存，不包装