Jekyll部署GitHub Pages异常：本地正常线上无法访问

嘿，我来帮你捋捋这个问题——本地跑Jekyll正常但GitHub Pages部署后挂掉，这种情况我碰到过好多次，给你列几个最可能的原因，你可以挨个排查：

• 相对路径配置错误
  本地开发时Jekyll默认用localhost:4000根路径，所以你写的/css/style.css这种绝对路径在本地能正常加载，但如果你的站点是部署在username.github.io/repo-name这种子路径下（不是你的用户主页仓库），绝对路径就会指向错误的位置。
  解决方法：在_config.yml里设置baseurl: "/你的仓库名称"，然后引用资源时用{{ site.baseurl }}/css/style.css这种方式，确保路径适配线上的子目录结构。

• 依赖版本不兼容
  GitHub Pages用的是固定版本的Jekyll及相关gem，而你本地可能装了更新的版本，导致一些语法或特性不被支持。
  解决方法：本地安装github-pages gem来模拟线上环境：

  gem install github-pages
  

  然后用bundle exec jekyll serve启动本地服务，这样就能提前发现版本差异带来的问题。另外，建议在项目根目录添加Gemfile，指定github-pages版本，确保本地和线上环境一致。

• 不支持的Jekyll插件
  GitHub Pages对Jekyll插件有严格限制，自定义Ruby插件或部分第三方插件（比如jekyll-admin）是不被支持的，线上构建时会直接失败。
  解决方法：去仓库的「Pages」设置页查看构建日志，里面会明确指出哪个插件违规，要么替换成支持的插件，要么改用静态生成后再部署的方式。

• 大小写敏感问题
  本地系统（比如Windows）文件名大小写不敏感，Style.css和style.css在本地没区别，但GitHub Pages运行在Linux环境下，大小写是严格区分的。如果你的引用路径和实际文件名大小写不匹配，线上就会出现404错误。
  解决方法：检查所有资源文件的命名和引用路径，确保大小写完全一致。

• 缓存干扰
  有时候浏览器缓存了旧的页面资源，或者GitHub Pages本身的缓存还没更新，导致看起来页面没加载成功。
  解决方法：用Ctrl + Shift + R（Windows/Linux）或Cmd + Shift + R（Mac）强制刷新浏览器，清除本地缓存；如果还是不行，等个5-10分钟再刷新，给GitHub Pages的部署缓存一点更新时间。

• 查看构建日志找具体错误
  这是最直接的排查方式！去你的GitHub仓库→「Settings」→「Pages」，拉到「Build and deployment」区域，查看「Latest deployment」的状态。如果构建失败，点击「Details」就能看到详细的错误信息——比如模板语法错误、缺失文件、配置项错误等，跟着提示修复就行。

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