使用Cloudflare Pages部署含Git子模块仓库报错如何解决

触发fatal: could not read Username for 'https://github.com'报错的核心原因是：Cloudflare Pages默认仅给主仓库的拉取操作注入内置鉴权凭据，拉取HTTPS格式配置的子模块时不会自动传递权限，本地运行正常是因为本地环境已经存储了GitHub的访问凭据，和子模块是否同属一个组织没有关系。

以下是按优先级排序的可落地方案： #

方案1：子模块路径改相对格式（同组织/同账号仓库首选，零额外密钥配置） #

• 打开本地项目根目录的.gitmodules文件，把所有同组织下子模块的HTTPS绝对地址替换为相对路径
• 原配置示例：

[submodule "src/components/common"]
	path = src/components/common
	url = https://github.com/your-org/common-components.git

• 修改后配置：

[submodule "src/components/common"]
	path = src/components/common
	url = ../common-components.git

• 提交.gitmodules的变更推送到主仓库，重新触发部署即可。Git会自动继承主仓库的拉取鉴权上下文，Cloudflare拉主仓库用的内置权限会直接复用到子模块拉取流程，不需要额外配置任何密钥。

方案2：注入GitHub PAT凭据（跨组织/私有子模块通用） #

如果子模块和主仓库不在同一GitHub组织，用下面的配置：

1. 在GitHub生成具备repo权限的个人访问令牌（PAT），确认令牌能访问所有需要拉取的子模块；如果组织开启了SAML单点登录，记得给PAT授予对应组织的访问权限
2. 进入Cloudflare Pages对应项目的环境变量配置页，给生产、预览环境都添加以下变量：
   • GIT_SUBMODULE_FORCE_HTTPS = true
   • GIT_TERMINAL_PROMPT = 0
3. 修改项目构建命令，在原有构建命令前拼接Git凭据全局配置逻辑，注意PAT和用户名不要硬编码到代码里，要引用Cloudflare加密环境变量传值：

   git config --global url."https://$GH_USERNAME:$GH_PAT@github.com/".insteadOf "https://github.com/" && 原有的构建命令
   

   这里的GH_USERNAME、GH_PAT是你提前在环境变量里存的GitHub用户名、生成的PAT值。

方案3：关闭默认子模块拉取，构建阶段手动控制 #

如果前两种方案不生效，可以直接关掉平台默认的子模块拉取逻辑，自己控制拉取流程：

1. 添加环境变量SKIP_SUBMODULES=true，禁用Cloudflare Pages默认的子模块拉取动作
2. 修改构建命令，在最前面手动执行子模块初始化拉取，再执行原有构建逻辑：

   git submodule update --init --recursive && 原有的构建命令
   

   拉取需要的鉴权逻辑可以自己在这一步灵活配置，公开子模块甚至不需要额外加鉴权参数。

注意：所有访问凭据都要存在Cloudflare的加密环境变量里，不要硬编码到代码或者构建脚本明文提交到仓库，避免凭据泄露。

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