GitHub Pages仅能加载minima主题，更换其他主题失效求助

• Windows 10.0.19044.2364
• ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x64-mingw-ucrt]
• gem v3.3.26
• jekyll 4.3.1

使用默认的minima主题时，GitHub Pages站点运行完全正常，但更换为任意其他主题（比如midnight）后，站点无法正常加载：要么显示空白白屏，要么仅渲染出主题头部，其余内容缺失。

默认正常配置 #

Gemfile #

source "https://rubygems.org"
# gem "jekyll", "~> 4.3.1"

# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima"

gem "github-pages", "~> 227", group: :jekyll_plugins

# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-remote-theme"
end
...

_config.yml #

title: default theme...
email: email@example.com
description: ...description...
domain: "chrisxfire.github.io"
url: "http://chrisxfire.github.io"

# Build settings
theme: minima

# remote-theme: pages-themes/midnight@v0.2.0
plugins:
- jekyll-feed
- jekyll-remote-theme

此时站点显示正常：

更换主题后的异常操作 #

尝试直接修改主题配置 #

1. 修改Gemfile，将gem "minima"替换为：

   gem "jekyll-theme-midnight"
   

2. 修改_config.yml，将theme: minima替换为：

   theme: jekyll-theme-midnight
   

提交后GitHub Actions执行成功，但站点显示空白白屏。

尝试使用remote-theme配置 #

修改_config.yml：

# theme: jekyll-theme-midnight
remote-theme: pages-themes/midnight@v0.2.0

提交后GitHub Actions执行成功，但页面仅渲染出蓝色头部，其余内容缺失：

1. 移除Gemfile中的单独主题声明
   github-pages gem已经预装了所有GitHub官方支持的主题，单独添加jekyll-theme-midnight会导致版本冲突。修改Gemfile，删除gem "jekyll-theme-midnight"，保留github-pages和必要插件即可：

   source "https://rubygems.org"
   # gem "jekyll", "~> 4.3.1"
   
   gem "github-pages", "~> 227", group: :jekyll_plugins
   
   group :jekyll_plugins do
     gem "jekyll-feed", "~> 0.12"
     gem "jekyll-remote-theme"
   end
   

2. 使用正确的主题配置方式
   对于GitHub官方主题，直接在_config.yml中设置theme: jekyll-theme-midnight即可，无需使用remote-theme（除非你需要主题的特定版本，且该版本未包含在当前github-pages版本中）。

3. 检查页面布局设置
   不同主题的布局名称可能不同，比如minima的默认首页用home布局，而midnight主题的默认布局是default。检查你的index.md等页面的Front Matter，确保使用了主题支持的布局：

   ---
   layout: default
   ---
   

   若不确定主题支持的布局，可以查看主题的仓库文件，找到_layouts目录下的文件名称。

4. 本地测试排查错误
   本地执行bundle exec jekyll serve，查看终端输出的日志信息，比如是否存在布局找不到、模板变量未定义等错误，这些信息能快速定位问题（GitHub Actions执行成功不代表没有渲染逻辑错误）。

5. 清除缓存重新构建

   • 本地测试时，删除_site文件夹和.jekyll-cache文件夹，再重新执行构建命令。
   • GitHub Pages端，在仓库的「Settings -> Pages」页面点击「Deploy branch」按钮，手动触发重新构建，避免缓存导致的异常。

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