部署在GitHub Pages的Jekyll博客推送后数分钟无法正常渲染

核心问题现象 #

• 本地通过jekyll serve构建运行完全正常
• 推送至GitHub Pages后，初始渲染正常，但约10分钟后全站显示异常
• 初始部署阶段：HTTP协议下渲染正常，HTTPS协议下异常；一段时间后HTTP/HTTPS均无法正常渲染

针对性排查与修复步骤 #

1. 检查GitHub Pages构建日志 #

进入你的代码仓库，依次点击Actions标签，找到最新的GitHub Pages构建工作流，查看完整日志：

• 重点确认构建过程中是否存在警告或错误，比如依赖缺失、路径引用错误、Liquid模板解析失败等
• 排查Lanyon主题依赖的模板变量是否在部署时未正确生成

2. 修复混合内容问题（HTTPS初始异常） #

初始阶段HTTPS渲染异常，几乎都是混合内容拦截导致：

• 检查博客源码中所有资源（CSS、JS、图片）的引用路径，排查是否存在硬编码的http://开头链接
• 将这类链接统一改为相对路径（如/assets/css/main.css）或协议无关路径（如//xxx/assets/xxx），避免HTTPS页面加载HTTP资源被浏览器拦截

3. 排查CDN缓存与域名配置问题 #

10分钟后全站异常，大概率和GitHub Pages的CDN缓存或域名解析有关：

• 确认仓库根目录的CNAME文件是否正确配置了你的子域名
• 检查子域名的DNS解析记录是否为CNAME类型，指向你的GitHub Pages默认域名
• 手动触发一次重新构建（比如修改_config.yml中某个无关配置后推送），强制刷新CDN缓存

4. 对齐Jekyll与主题依赖版本 #

本地与GitHub Pages环境依赖版本不一致常引发部署问题：

• 查看GitHub Pages官方指定的Jekyll版本，确保本地Jekyll版本与之匹配
• 在仓库根目录添加Gemfile.lock文件，锁定主题与插件的依赖版本，避免构建时拉取不兼容版本
• 尝试更新Lanyon主题到最新稳定版，修复已知的部署适配问题

5. 验证静态文件完整性 #

本地执行jekyll build生成_site目录，将该目录内容与GitHub Pages部署后的实际文件对比：

• 确认所有静态资源（CSS、JS、HTML）是否完整上传
• 检查HTML文件中的链接是否为部署环境的正确路径，无本地绝对路径残留

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