如何在GitHub Pages启用Git子模块？Astro站点构建报错排查

核心问题定位 #

构建日志里明确显示submodules: false，这说明GitHub Actions的checkout步骤默认没启用子模块拉取——你试的两种HTTPS URL都是合法的GitHub只读地址（带不带.git后缀都可以），问题根本不在URL格式上。

解决步骤 #

1. 修改GitHub Actions的checkout配置 #

找到站点仓库里的.github/workflows/pages.yml（或其他部署用的Workflow文件），把actions/checkout@v3的submodules参数从false改成true，确保拉取代码时同步子模块：

- name: Checkout repository
  uses: actions/checkout@v3
  with:
    repository: LiquidZulu/liquidzulu.github.io
    submodules: true # 关键：启用子模块拉取
    # 如果你的子模块还有嵌套子模块，再加一行 recursive: true

2. 验证子模块分支配置（可选） #

如果修改后仍有问题，检查.gitmodules是否指定了正确分支（如果子模块不是用默认的main/master分支）：

[submodule "src/content/brain"]
    path = src/content/brain
    url = https://github.com/LiquidZulu/brain.git
    branch = main # 替换成你的子模块实际分支名

3. 本地验证排查 #

在本地执行以下命令，确认子模块能正常拉取且Astro构建正常：

git submodule update --init --recursive
npm run build # 或你用的pnpm/yarn build

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