如何在GitHub Actions中使用子模块并访问其内部文件

Hey 👋，你遇到的这个找不到子模块文件的问题，我之前帮不少开发者解决过——本质上是GitHub Actions默认不会自动拉取子模块内容，再加上可能的路径或权限配置问题。下面一步步来帮你搞定：

1. 先确认本地子模块配置没问题 #

在本地仓库里先跑一遍 git submodule status，如果能看到子模块的哈希值和对应的本地路径，说明子模块已经正确添加并提交到主仓库了。要是没看到，得先执行 git submodule add <子模块仓库URL> <本地目标路径> 添加子模块，然后把生成的 .gitmodules 文件和子模块的引用提交到GitHub主仓库。

2. 在GitHub Actions的checkout步骤中开启子模块拉取 #

默认的 actions/checkout 动作只会拉取主仓库的代码，不会管子模块。你需要在checkout步骤里加上参数，让它自动拉取子模块：

steps:
  - name: 拉取代码（包含子模块）
    uses: actions/checkout@v4
    with:
      submodules: true  # 启用拉取所有子模块
      fetch-depth: 0    # 拉取完整仓库历史，避免子模块浅克隆导致的问题

如果你的子模块还有嵌套的子模块，把 submodules 的值改成 recursive 就能递归拉取所有层级的子模块了。

3. 私有子模块要处理权限问题 #

如果你的子模块是私有GitHub仓库，默认的 GITHUB_TOKEN 没有访问权限，这时候得搞个PAT（Personal Access Token）：

• 生成一个拥有私有仓库读取权限的PAT，然后在主仓库的「Settings → Secrets and variables → Actions」里添加这个PAT，命名比如 PRIVATE_SUBMODULE_TOKEN。
• 修改checkout步骤，用这个PAT来拉取子模块：

steps:
  - name: 拉取代码（含私有子模块）
    uses: actions/checkout@v4
    with:
      submodules: true
      token: ${{ secrets.PRIVATE_SUBMODULE_TOKEN }}

4. 验证文件路径是否准确 #

报错里的 directory_in_sub_module/requirements.txt 路径，得确认和子模块在主仓库里的实际路径完全一致。可以在Actions里加个步骤打印目录结构，快速排查路径问题：

- name: 查看目录结构
  run: |
    ls -la  # 查看根目录所有内容
    ls -la directory_in_sub_module  # 查看子模块目录里的内容

5. 额外检查：子模块的分支或哈希是否正确 #

如果你的子模块指定了特定分支，要确保 .gitmodules 文件里的 branch 配置是对的。另外，要是子模块有更新，记得在本地运行 git submodule update --remote 把子模块拉到最新版本，然后把主仓库里的子模块引用提交到GitHub。

按照这些步骤配置完，应该就能顺利访问子模块里的 requirements.txt 文件了。要是还出问题，看一下 ls 步骤的输出，就能快速判断是子模块没拉下来，还是路径写错了。

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