部署在GitHub Pages的Jekyll网站样式丢失（疑似缓存问题）

1. 检查资源路径配置 #

• 确保CSS、JS、图片等资源引用使用适配GitHub Pages的路径格式：
  • 如果你的项目是子路径部署（如xxx.github.io/Quokka），在_config.yml中设置baseurl: "/Quokka"，然后资源引用改为{{ site.baseurl }}/css/style.css这类带baseurl的格式。
  • 避免使用相对路径（如css/style.css），本地部署无baseurl时正常，但线上会因为子路径导致路径错位。
• 本地测试时用bundle exec jekyll serve --baseurl "/Quokka"模拟线上环境，提前验证路径是否正确。

2. 核对文件名大小写 #

GitHub Pages服务器区分文件名大小写，而Windows等本地系统不区分。如果资源文件实际是CSS/Style.css，但引用写的css/style.css，线上就会触发404。统一所有资源文件和引用的大小写格式。

3. 排查Jekyll插件兼容性 #

GitHub Pages仅支持官方白名单内的插件，自定义插件会被线上构建忽略，可能导致资源路径生成异常。检查_config.yml的plugins列表，移除非官方插件，改用GitHub支持的替代方案。

4. 查看GitHub Pages构建日志 #

进入仓库Settings → Pages → 点击"View deployment"查看构建日志，里面会显示资源是否未被正确复制、路径错误或构建报错的细节，直接定位问题根源。

5. 确认gh-pages分支文件结构 #

检查gh-pages分支的实际目录，确认CSS、JS等资源是否存在于预期位置。有时Jekyll构建时会出现资源未复制到目标目录的情况，比如自定义assets目录的处理逻辑是否正确。

6. 检查.gitignore规则 #

确保.gitignore没有误屏蔽需要部署的资源目录，比如css、js、images等关键目录被误加进忽略列表，导致线上缺失资源。

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