常见问题与解决方案

构建问题

问题：npm install 失败

原因: 依赖版本冲突或网络问题

解决方案:

1
2
3
4
5
6
7
8
9
10
# 清除缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

# 使用国内镜像
npm config set registry https://registry.npmmirror.com
npm install

问题：hexo generate 报错

原因: Node.js 版本不兼容

解决方案:

1
2
3
4
5
# 检查 Node 版本
node -v

# 使用 nvm 切换版本
nvm use 22

问题：主题样式丢失

原因: 主题未正确安装或 CDN 问题

解决方案:

1
2
3
4
5
6
7
8
# 重新安装主题
npm install hexo-theme-butterfly

# 检查 CDN 配置
# _config.butterfly.yml
CDN:
  internal_provider: local
  third_party_provider: jsdelivr

问题：代码块不显示或高亮异常

原因: 代码高亮插件配置问题

解决方案:

1
2
3
4
5
# _config.yml
syntax_highlighter: prismjs
prismjs:
  preprocess: true
  line_number: true

部署问题

问题：GitHub Actions 构建失败

检查项:

  1. Node.js 版本是否为 22
  2. 依赖是否正确安装
  3. 构建命令是否正确

查看日志: GitHub 仓库 → Actions → 查看失败的 workflow

问题：SSH 部署失败

原因: SSH 密钥配置错误

解决方案:

1
2
3
4
5
# 测试 SSH 连接
ssh -i private_key root@dhongli.cloud

# 检查 GitHub Secret
# Settings → Secrets → SERVER_SSH_KEY

问题：网站更新后未生效

原因: 浏览器缓存

解决方案:

  • 强制刷新: Ctrl+F5
  • 清除浏览器缓存
  • 等待 CDN 缓存过期

文章问题

问题：文章显示乱码

原因: 文件编码问题

解决方案:

  • 确保文件使用 UTF-8 编码
  • 检查 Front-matter 格式

问题：图片不显示

原因: 图片路径错误

解决方案:

1
2
3
4
5
6
# 正确路径 (相对于 source 目录)
![描述](/img/image.png)

# 错误路径
![描述](../img/image.png)
![描述](D:/img/image.png)

问题：Markdown 渲染异常

原因: Markdown 语法错误

解决方案:

  • 标题前后留空行
  • 列表缩进正确
  • 表格格式正确
  • 代码块使用正确的围栏

问题：Front-matter 格式错误

常见错误:

1
2
3
4
5
6
7
8
9
# 错误：冒号后没有空格
title:文章标题

# 错误：值包含冒号但没有引号
date: 2026-06-19 12:00:00

# 正确
title: 文章标题
date: '2026-06-19 12:00:00'

主题问题

问题：搜索功能不工作

解决方案:

1
2
3
# 重新生成搜索索引
hexo clean
hexo generate

问题：暗黑模式不生效

检查配置:

1
2
3
4
# _config.butterfly.yml
darkmode:
  enable: true
  button: true

问题：TOC 目录不显示

检查配置:

1
2
3
toc:
  post: true
  page: false

确保文章有二级以上的标题

问题：侧边栏不显示

检查配置:

1
2
3
aside:
  enable: true
  hide: false

性能问题

问题：网站加载慢

优化方案:

  1. 启用图片懒加载
  2. 使用 CDN
  3. 压缩 CSS/JS
  4. 启用 Gzip
1
2
3
4
5
6
# _config.butterfly.yml
lazyload:
  enable: true

CDN:
  third_party_provider: jsdelivr

问题：构建速度慢

优化方案:

  1. 减少不必要的插件
  2. 使用缓存
  3. 排除大文件
1
2
3
4
# _config.yml
ignore:
  - source/**/*.psd
  - source/**/*.ai

Git 问题

问题：push 被拒绝

解决方案:

1
2
3
4
5
# 拉取最新代码
git pull origin master

# 解决冲突后推送
git push origin master

问题：不小心提交了敏感信息

解决方案:

1
2
3
4
5
6
7
# 从历史中移除
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch 敏感文件' \
  --prune-empty --tag-name-filter cat -- --all

# 强制推送 (谨慎使用)
git push origin master --force

本地开发问题

问题：localhost:4000 无法访问

解决方案:

1
2
3
4
5
# 检查端口占用
netstat -ano | findstr :4000

# 使用其他端口
hexo server -p 8080

问题：热重载不工作

解决方案:

1
2
3
# 重启服务器
# Ctrl+C 停止
hexo server

问题：端口被占用

解决方案:

1
2
3
4
5
6
7
# Windows
netstat -ano | findstr :4000
taskkill /PID <进程ID> /F

# Mac/Linux
lsof -i :4000
kill -9 <进程ID>

插件问题

问题：插件安装后不生效

解决方案:

1
2
3
4
5
6
7
8
# 清除缓存
hexo clean

# 重新生成
hexo generate

# 重启服务器
hexo server

问题：插件冲突

解决方案:

1
2
3
4
5
# 查看已安装插件
npm list --depth=0

# 逐个禁用插件排查
npm uninstall 问题插件

调试命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 查看详细日 DEBUG=* hexo generate

# 查看配置
hexo config

# 清除缓存
hexo clean

# 查看版本
hexo version

# 安全模式（禁用插件）
hexo --safe server

# 调试模式
hexo --debug server

获取帮助

官方文档

社区资源

提交问题

在 GitHub Issues 提交问题时，请包含：

  1. Hexo 版本 (hexo version)
  2. Node.js 版本 (node -v)
  3. 错误日志
  4. 复现步骤

下一步