自建git服务器中子模块路径错乱，主因是core.autocrlf破坏.gitmodules哈希与路径一致性、相对url解析失败、uploadpack.allowreachablesha1inwant未启用及协议/权限不统一。
git config --system core.autocrlf 导致模块路径错乱
自建 Git 服务器（如 Gitea、GitLab Self-Managed 或裸仓库 + hook 方案）中，若客户端执行 git clone 后发现子模块路径解析失败（例如 git submodule update 报错 fatal: not a git repository: .git/modules/path/to/submodule），很可能是服务端或客户端启用了全局 core.autocrlf 并作用于 .gitmodules 文件。该配置会强制转换换行符，破坏 .gitmodules 中的 SHA-1 哈希值和路径字段的原始二进制一致性。
实操建议：
- 服务端裸仓库应禁用所有自动换行处理：在
/path/to/repo/.git/config中显式设置core.autocrlf = false - 客户端统一关闭该行为：
git config --global core.autocrlf false（Linux/macOS 必须关；Windows 若需保留换行兼容，仅对项目目录单独设core.autocrlf = input） - 检查
.gitmodules文件是否被修改过：用git ls-files --stage .gitmodules查看其 blob hash，再比对原始提交中的 hash 是否一致
子模块 URL 解析失败：relative url 与 server base path 不匹配
自建 Git 服务器常将仓库托管在非根路径下（如 https://git.example.com/group/project.git），而 .gitmodules 中子模块 URL 写的是相对路径（../lib/utils.git）。Git 客户端解析时会以当前仓库 URL 为基准拼接，但若服务端未正确重写或代理 rewrite 规则缺失，就会生成错误的请求地址（如拼成 https://git.example.com/lib/utils.git 而非 https://git.example.com/group/lib/utils.git）。
实操建议：
- 禁止在
.gitmodules中使用../类相对路径；全部改用绝对 URL（协议+域名+完整路径），例如https://git.example.com/group/lib/utils.git - 若必须用相对路径，确保反向代理（Nginx/Apache）开启
sub_filter或类似模块，在响应中动态重写.gitmodules内容（不推荐，维护成本高） - Gitea 用户可启用
DISABLE_SUBSCRIPTIONS = true并配合MODULES_DISABLED = false避免路径预解析干扰
git submodule init 失败：server 端未启用 uploadpack.allowReachableSHA1InWant
当子模块指向一个轻量标签（lightweight tag）或未推送的本地 commit 时，git submodule init 和后续 update 可能卡在 “remote: Counting objects” 阶段，最终超时。这是因为 Git 默认只允许 fetch 已有 ref（branch/tag）指向的 commit，而子模块记录的 commit ID 若不在任何 ref 上，服务端会拒绝传输 —— 这是安全默认行为，但对子模块场景不友好。
实操建议：
- 在 Git 服务器（裸仓库）的
config文件中添加：[uploadpack]<br> allowReachableSHA1InWant = true
- 该配置仅影响
upload-pack（即 clone/fetch），不降低安全性：它只允许获取“可达”的 SHA-1（即从已有 ref 可遍历到的 commit），不会暴露孤立对象 - 重启 Git 服务（如
systemctl restart gitea）或确认服务已重载配置（Gitea 需在 UI 中点击 “Admin Panel → Config → Save”）
权限与钩子导致 submodule sync 权限拒绝
用户执行 git submodule foreach 'git pull' 或 CI 流水线中触发子模块同步时，报错 Permission denied (publickey) 或 fatal: could not read Username for 'https://...'，常见于自建服务器未统一认证方式：主仓库用 SSH 克隆，子模块却配置为 HTTPS 地址，或反之。
实操建议：
- 保持所有子模块 URL 协议与主仓库一致；可用
git config --file .gitmodules submodule.XXX.url批量修正 - 若使用 SSH，确保部署密钥（deploy key）同时添加到主仓库和所有子模块仓库中（Gitea/GitLab 支持“共享 deploy key”）
- CI 场景下避免交互式认证：GitLab CI 推荐用
CI_SERVER_TLS_CA_FILE+CI_JOB_TOKEN访问 HTTPS 子模块；GitHub Actions 则用${{ secrets.GITHUB_TOKEN }}注入git config --global url."https://${{ secrets.GITHUB_TOKEN }}@github.com/".insteadOf "https://github.com/"
uploadpack.allowReachableSHA1InWant 这个开关 —— 它默认关闭，且错误日志里几乎不提示，只会表现为静默超时或 fetch 卡死。
