Hexo本地预览与部署内容不同步问题求助

我之前也碰到过几乎一模一样的情况！本地用hexo s -g预览完全正常，一部署到GitHub Pages就少内容，当时折腾了好一会儿才找到原因，给你分享几个排查和解决的方向：

• 检查部署分支是否正确
  GitHub Pages默认是从gh-pages分支加载站点内容的，很多新手容易误把内容推到main或master分支。打开你的Hexo配置文件_config.yml，找到deploy区块，确认分支设置：

  deploy:
    type: git
    repo: https://github.com/你的用户名/你的用户名.github.io.git
    branch: gh-pages
  

  如果分支设错了，修改后执行hexo clean && hexo d -g -m "fix deploy branch"重新部署。

• 部署前务必清理缓存
  本地预览时生成的静态文件可能残留缓存，导致部署的是旧的或不完整的内容。每次部署前一定要先运行hexo clean，它会清空public文件夹里的所有旧文件，再执行hexo g -d（hexo d -g也会生成，但先清缓存更稳妥）。

• 检查站点路径配置
  有些主题的资源路径在本地能正常加载，但部署到GitHub Pages后因为路径错误无法显示。检查_config.yml里的核心路径配置：

  url: https://你的用户名.github.io
  root: /
  

  如果你的站点是放在子仓库（比如https://你的用户名.github.io/blog），那root要设置为/blog/。另外主题的配置文件里如果有资源路径（比如图片、CSS的路径），也要确保是相对路径或者匹配站点的绝对路径。

• 查看GitHub Pages的部署状态
  虽然代码提交成功了，但GitHub Pages的构建可能失败了。进入你的GitHub仓库，点击顶部的「Settings」，找到「Pages」选项卡，查看页面底部的「Build and deployment」状态：

  • 如果显示「Success」，等几分钟刷新站点看看（有时候CDN缓存需要时间）；
  • 如果显示「Failed」，点击「Details」查看错误日志，日志里会明确指出问题，比如某个Markdown文件格式错误、依赖缺失等。

• 验证本地生成的静态文件完整性
  先在本地执行hexo clean && hexo g，然后打开public文件夹里的HTML文件，检查是不是所有内容都正常生成了。如果本地public里就缺内容，那问题出在生成阶段：

  • 检查文章的Front Matter是不是有语法错误（比如冒号后面没空格、引号不配对）；
  • 暂时禁用所有第三方插件，换成Hexo默认的landscape主题，重新生成试试，逐步排查是不是插件或主题的兼容性问题。

内容的提问来源于stack exchange，提问作者ching.lin