Jekyll构建GitHub Pages时资源无法正常显示的问题求助

• 路径配置差异：本地Jekyll默认baseurl为空，GitHub Pages项目页的baseurl是仓库名。如果页面硬编码相对路径（比如/assets/images/xxx.gif），线上会从域名根目录查找，而非仓库目录，可能加载到错误资源；即使路径看似正确，也可能因配置问题导致资源实际未正确映射。
• GIF资源被错误转码/压缩：GitHub Pages自带的Jekyll插件或第三方优化插件（如图片压缩工具）可能对GIF格式支持不佳，部署时自动压缩或转码损坏了文件，导致线上资源变成透明空文件——本地运行时没启用这些插件，所以显示正常。
• 文件名大小写不兼容：本地Windows/macOS系统不区分文件名大小写，能识别Image.gif和image.gif，但GitHub Pages的Linux环境严格区分。若页面引用路径和实际文件名大小写不一致，会加载到错误的（或空的）资源。
• 缓存残留：GitHub Pages的CDN缓存了旧的损坏资源，即使Actions已部署新文件，CDN未及时更新；或是浏览器本地缓存了之前的错误资源。

• 统一路径配置：
  • 在_config.yml里设置baseurl: "/你的仓库名"，页面引用资源时用{{ site.baseurl }}拼接路径，比如{{ site.baseurl }}/assets/images/xxx.gif，避免硬编码路径。
  • 逐一检查所有图片引用路径，确保线上环境下能指向正确的资源位置。
• 调整图片处理插件：
  • 打开_config.yml查看插件列表，若有图片压缩、转码类插件（如jekyll-minifier），先暂时禁用，重新部署验证问题是否消失。
  • 若需要保留优化功能，确认插件支持GIF格式，添加配置规则排除GIF文件（比如在压缩插件里设置exclude: ["*.gif"]）。
• 统一文件名大小写：
  • 把所有资源文件名和页面中的引用路径统一为相同大小写（比如全小写），消除跨环境的识别差异。
• 清除缓存：
  • 浏览器按Ctrl+F5强制刷新，清除本地缓存；
  • 若CDN缓存未更新，可在仓库的Settings -> Pages页面，修改_config.yml加个空格再提交，手动触发重新部署。
• 验证资源完整性：
  • 直接访问线上资源的URL，下载文件和本地原文件对比大小、内容，确认是否在部署中被损坏。如果文件大小明显变小，说明是压缩转码的问题。
  • 仔细查看GitHub Actions的部署日志，确认资源文件是完整复制的，有没有报错或警告信息。

内容的提问来源于stack exchange，提问作者Start-Automating