Hexo 部署后出现白屏问题

发表于 分类于 阅读次数：

在使用 Hexo 部署博客后，访问网站时出现白屏现象，即页面完全空白，没有任何内容显示。这是一个比较常见的问题，本文将介绍几种常见的解决方案。

常见原因及解决方法

1. 配置文件中的 URL 设置问题

检查 _config.yml 文件中的 URL 配置：

1
2
3
# URL 配置
url: https://你的用户名.github.io
root: /

确保 URL 设置正确，特别是如果你使用自定义域名，需要将 URL 改为你的域名。

2. 主题路径问题

检查主题文件夹是否存在，以及 _config.yml 中的主题配置是否正确：

1
theme: your-theme-name

如果使用 git 子模块方式安装主题，确保主题文件已正确克隆：

1
2
git submodule init
git submodule update

我更新 hexo 遇到的是这个问题，暴力的解法是删除子模块目录下的 .git 文件夹，再重新提交代码，然后发布

3. 资源文件路径问题

确保所有资源文件（CSS、JavaScript）的路径正确。可以：

  1. 清理缓存后重新生成

  2. 部署

1
2
3
hexo clean
hexo generate
hexo deploy
  1. 检查主题配置文件中的资源路径是否正确，特别是 CDN 链接。

4. Node.js 版本兼容性

某些情况下，Node.js 版本可能会导致部署问题。建议：

  • 使用 LTS 版本的 Node.js
  • 确保 Node.js 版本与 Hexo 及主题兼容

5. 部署配置问题

检查部署配置是否正确：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:用户名/用户名.github.io.git
  branch: main  # 或者 master，取决于你的默认分支

调试方法

  1. 使用浏览器开发者工具（F12）查看控制台错误信息
  2. 检查网络请求，查看资源加载情况
  3. 尝试清除浏览器缓存后重新访问
  4. 本地预览是否正常：hexo server

预防措施

  1. 部署前先在本地预览
  2. 保持主题和 Hexo 版本更新
  3. 做好配置文件备份
  4. 使用版本控制管理源文件

结语

遇到白屏问题不要慌，按照以上步骤逐一排查，大多数情况下都能找到解决方案。如果问题仍然存在，可以：

  • 查看 Hexo 官方文档
  • 检查主题的 GitHub Issues
  • 在社区寻求帮助