排查Github Pages部署Jekyll网站无法更新的问题

以下是一套逐步排查的实用方法，覆盖从构建状态到本地验证的全流程：

• 检查GitHub Pages构建状态
  进入仓库的「Settings」→「Pages」页面，拉到最下方查看「Build and deployment」的日志详情。如果构建失败，日志会明确给出错误原因——比如Liquid模板语法错误、缺失依赖、文件命名不符合规范等，这是定位问题最快的方式。

• 本地模拟GitHub构建环境
  本地安装github-pages gem以同步GitHub的官方构建环境：

  gem install github-pages
  

  然后在仓库根目录运行构建命令：

  bundle exec jekyll build
  

  查看终端输出的错误信息，很多线上构建失败的问题都能在本地复现（比如本地用了高版本Jekyll导致语法不兼容）。

• 核对文件与路径配置

  • 确保博客文章文件名符合YYYY-MM-DD-标题.md格式，日期不要设为未来值；避免文件名包含空格、特殊字符或中文（部分场景会触发兼容性问题）。
  • 检查_config.yml中的baseurl配置，如果站点部署在二级路径（比如username.github.io/repo-name），baseurl必须设置为/repo-name，否则页面和资源路径会失效。

• 强制刷新与触发重构

  • 用浏览器快捷键Ctrl+Shift+R强制刷新页面，或在隐私模式下访问，排除本地缓存干扰。
  • 若怀疑CDN缓存未更新，可提交空commit触发GitHub重新构建：

    git commit --allow-empty -m "Trigger Pages rebuild"
    git push
    

• 排查内容与模板问题

  • 检查最近修改的内容是否存在Liquid语法错误（比如未闭合的{% %}标签、无效变量引用）。
  • 确认没有使用GitHub Pages白名单外的自定义插件——GitHub Pages仅支持官方指定的插件，自定义插件会被直接忽略，导致功能失效。
  • 核对_layouts、_includes目录下的模板文件是否完整，有没有缺失关键渲染标签。

• 验证仓库Pages配置
  确认「Settings」→「Pages」中的部署源设置正确：分支选择是否为你的主分支（如main），目录是否为根目录或/docs，避免误改配置导致部署路径错误。

内容的提问来源于stack exchange，提问作者daddyblondlegs