Github Pages无法识别子模块内index.html问题排查咨询

问题原因与解决方案 #

核心原因

你遇到的问题是GitHub Pages默认的自动构建流水线不会递归拉取子模块导致的：
本地运行jekyll serve时你已经提前将子模块内容拉到了本地目录，所以运行正常；但GitHub云端构建时默认不会拉取子模块内容，对应路径实际为空，因此访问子模块路径下的内容会返回404，且不会触发构建报错。

可先修正的配置细节

你当前.gitmodules文件里的子模块配置存在小瑕疵，虽然本地可正常识别，但可能引发GitHub端解析异常，建议调整如下：

[submodule "docs/SimpleLive2dViewer"]
    path = docs/SimpleLive2dViewer
    url = https://github.com/jupiterbjy/SimpleLive2dViewer

去掉子模块名称和path字段前的./相对路径前缀。

两种可行解决方法

你可以根据自己的需求任选一种：

• 方法一：自定义GitHub Actions构建流程（推荐）
  在父仓库的.github/workflows目录下新建pages.yml配置文件，在代码检出步骤增加递归拉取子模块的参数即可。参考配置逻辑如下：

  1. 配置触发规则为推送到主分支时触发构建
  2. 配置Pages读写权限
  3. checkout代码时添加submodules: 'recursive'参数，拉取所有子模块内容
  4. 后续保留原本的静态资源上传、Pages部署步骤即可

• 方法二：将子模块替换为Git Subtree管理
  Subtree会将子仓库的内容直接写入父仓库的提交记录中，不需要额外调整构建流程即可被GitHub Pages正常识别，适合不需要频繁同步子仓库更新的场景。

验证方式

调整完成后，你可以前往仓库的Actions页面，查看对应Pages构建任务的日志，确认Checkout步骤有拉取子模块的相关记录，即可确认问题修复。

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