无法发布站点到GitHub Pages及添加Jekyll主题的问题咨询

一、404 Not Found 问题排查 #

• 确认仓库配置：用户/组织主页仓库必须命名为 用户名.github.io；普通项目仓库需进入「Settings > Pages」，选择正确的发布分支（如main/gh-pages）和源目录（根目录或/docs），未开启Pages或配置错误会直接导致404。
• 检查文件位置：确保入口HTML文件（如index.html）在你指定的Pages源目录下，若放在子文件夹，访问路径需对应。
• 查看构建状态：去仓库的「Actions」页面，检查GitHub Pages的构建日志。如果构建失败，页面不会更新；若日志正常，可能是CDN缓存延迟，可多等15-30分钟再刷新。

二、Jekyll主题添加问题 #

GitHub Pages确实内置Jekyll，但已移除直接选择主题的可视化入口，现在只能通过配置文件手动设置：

• 内置主题配置：在仓库根目录创建 _config.yml 文件，添加一行配置：theme: minima（minima是GitHub官方默认主题，也可替换成其他内置主题如jekyll-theme-cayman）。
• 第三方主题配置：若想用非内置主题，可在 _config.yml 中使用 remote_theme: 主题作者/主题仓库名，或者将主题代码直接克隆到你的仓库中，按主题文档完成配置。
• 之前的“一键添加主题”功能已下线，所以你看到的教程链接是当前唯一的配置途径。

三、Jekyll与GitHub Pages的关联逻辑 #

GitHub Pages默认支持Jekyll自动构建，无需额外关联操作，只需满足两个条件：

• 仓库根目录存在 _config.yml 文件（哪怕只有基础配置），且没有 .nojekyll 文件（这个文件会强制跳过Jekyll构建，直接托管静态文件）。
• 你的文件结构符合Jekyll要求（比如页面放在根目录或 _posts 文件夹等），提交后GitHub会自动触发Jekyll构建，生成静态页面并发布到Pages。

如果你的仓库只有纯HTML/CSS，也可以不用Jekyll，直接托管静态文件——此时不需要添加任何Jekyll相关配置，只要开启Pages即可。

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