Hexo 博客部署常见问题排查指南

发表于 更新于 分类于
Hexo 博客部署过程中常见问题及解决方案，包括 Git 克隆失败、npm 安装超时、防火墙配置等问题的排查指南。

问题现象

部署 Hexo 博客时遇到各种错误，无法正常运行。

常见问题 1: Hexo init 失败

症状

1
2
3
FATAL {
  err: Error: Command failed: git clone ...
}

原因

  • 网络连接问题
  • Git 配置错误
  • GitHub 访问受限

解决方案

1
2
3
4
5
6
7
8
9
10
11
# 方案 1: 清除 git 配置
cat > ~/.gitconfig << 'EOF'
EOF

# 方案 2: 手动下载主题
cd /root/tech-blog
rm -rf themes/next
git clone https://github.com/next-theme/hexo-theme-next themes/next

# 方案 3: 使用镜像
git clone https://gitee.com/next-theme/hexo-theme-next themes/next

常见问题 2: npm install 失败

症状

1
2
npm ERR! network timeout
npm ERR! code ETIMEDOUT

原因

  • npm 源速度慢
  • 网络连接不稳定

解决方案

1
2
3
4
5
6
7
8
# 切换到淘宝镜像
npm config set registry https://registry.npmmirror.com

# 重新安装
npm install

# 验证
npm config get registry

常见问题 3: 博客无法访问

症状

  • 浏览器显示”无法连接”
  • curl 返回失败

原因分析

原因 检查方法 解决
服务未启动 ps aux | grep http.server 启动服务
端口未开放 firewall-cmd --list-ports 开放端口
阿里云安全组 控制台检查 添加规则

解决方案

1
2
3
4
5
6
7
8
9
10
11
# 1. 启动服务
cd /root/tech-blog/public
nohup python3 -m http.server 8080 &

# 2. 开放防火墙
firewall-cmd --zone=public --add-port=8080/tcp --permanent
firewall-cmd --reload

# 3. 验证
netstat -tlnp | grep 8080
curl http://localhost:8080

常见问题 4: hexo generate 失败

症状

1
ERROR Asset render failed: ...

原因

  • 主题配置错误
  • 缺少依赖

解决方案

1
2
3
4
5
6
7
8
9
# 1. 检查主题配置
cat _config.yml | grep theme

# 2. 确认主题存在
ls -la themes/next

# 3. 重新生成
hexo clean
hexo generate

常见问题 5: 文章不显示

症状

  • 首页没有文章内容
  • 只有 hello-world

原因

  • 文章 draft 状态
  • 日期设置错误
  • 格式不正确

解决方案

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 检查文章状态
cat source/_posts/*.md | head -10

# 2. 确保 published: true
# 文章开头应该是：
# ---
# title: 标题
# date: 2026-04-12
# published: true
# ---

# 3. 重新生成
hexo clean
hexo generate

完整排查流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 1. 检查 Node.js
node --version
npm --version

# 2. 检查 Hexo
hexo version

# 3. 检查主题
ls -la themes/

# 4. 检查文章
ls -la source/_posts/

# 5. 清理并重新生成
hexo clean
hexo generate

# 6. 检查服务
ps aux | grep http.server
netstat -tlnp | grep 8080

# 7. 测试访问
curl http://localhost:8080

日志查看

1
2
3
4
5
6
7
8
# Hexo 日志
hexo generate --debug

# 服务日志
tail -f /tmp/blog-server.log

# 系统日志
journalctl -u hexo-blog -f

预防措施

1. 使用 systemd 服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# /etc/systemd/system/hexo-blog.service
[Unit]
Description=Hexo Blog Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/tech-blog/public
ExecStart=/usr/bin/python3 -m http.server 8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

2. 配置日志轮转

1
2
3
4
5
6
7
8
9
# /etc/logrotate.d/hexo-blog
/tmp/blog-server.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

3. 定期备份

1
2
# 备份博客内容
tar -czf /backup/hexo-blog-$(date +%Y%m%d).tar.gz /root/tech-blog

总结

博客部署问题通常是配置或网络问题，按照上述流程排查即可解决。

建议：

  • 使用 systemd 服务管理博客
  • 配置防火墙规则
  • 定期备份博客内容

遇到问题？在评论区留言！