GitHub Pages部署Jekyll博客子页404、首页样式异常如何解决？

核心原因 #

该问题是Project类型GitHub Pages的路径配置不匹配导致的：Project站点默认部署在域名的子路径下，和本地运行的根路径环境不一致，资源加载和页面跳转路径错误就会出现样式失效、子页404。

具体修复步骤 #

• 修正_config.yml配置
  打开项目根目录下的_config.yml文件，修改两个核心配置项：
  • baseurl设置为你的仓库名，格式为baseurl: "/你的仓库名"，注意前面加斜杠，末尾不要加斜杠
  • url设置为你的GitHub Pages个人根域名，格式为url: "https://你的GitHub用户名.github.io"

本地测试时执行jekyll serve --baseurl ""即可保持本地根路径访问正常，不会和线上配置冲突

• 确认站内资源引用格式
  所有站内CSS、JS、图片资源以及博文跳转链接，都需要使用Jekyll自带的relative_url过滤器生成路径，比如：
  • 样式引用：<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
  • 博文链接：[博文标题]({{ post.url | relative_url }})
    你通过jekyll new生成的默认minima主题已经适配了该规则，只要配置正确无需手动修改主题文件。
• 重新部署生效
  将修改后的_config.yml提交推送到GitHub仓库，等待2-3分钟待GitHub Pages自动构建完成后，清理浏览器缓存再访问站点即可恢复正常。

额外排查项 #

如果修改后仍未解决问题，可检查以下配置：

• 确认仓库的GitHub Pages部署分支设置正确，默认使用main分支根目录，如果你使用master分支需要对应调整设置
• 不要将本地生成的_site目录提交到仓库，GitHub Pages会自动完成构建，本地生成的错误路径文件会覆盖线上构建结果
• 确认_config.yml中没有自定义错误的permalink规则，默认规则即可满足需求

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