企业官网建设流程全解析

搞 Git 子模块这事，说简单其实也简单，说坑也真不少。尤其团队一多、项目一变复杂，公共代码怎么抽、怎么同步、怎么不把同事搞崩溃，就成了实打实要面对的问题。我最早接触 Git submodule 是在一个多仓库协作的项目里，那时候还没什么经验，直接git clone下来发现目录是空的，还以为是传输出问题了。后来把submodule的机制、GitLab 上的协作方式、CI/CD 的集成逻辑摸了一遍，才算是真正用顺手。

这篇教程就围绕 GitLab 环境，把git submodule从创建、克隆、提交、更新到删除、CI/CD 集成整个链路完整拆一遍。不管你是刚开始接触子模块，还是已经在用但经常踩坑，这篇都值得认真过一遍。

1. 先搞清楚：什么时候才需要 git submodule

1.1 子模块到底解决了什么问题

Git Submodule 的官方定义很简短：它允许你在一个 Git 仓库里嵌套另一个 Git 仓库，并且保持两个仓库的独立性。听起来有点抽象，我换个说法你就明白了。

假设你们公司有好几个项目都用到同一套用户中心代码，比如 Web 端、后台管理系统、运营工具。如果直接把这套代码复制到每个项目里，那每次用户中心改个 bug，你都得去两三个项目里同步，漏一个就出线上事故。可如果你把用户中心单独放到一个 GitLab 仓库里，再以子模块的方式“挂”到其他项目里，那每个项目都只是保存了对用户中心某个提交的引用，升级、回滚、多版本共存都能精确控制。

这个“引用”的概念很关键。父项目并不存子模块的完整代码，只记住“子模块仓库的某个 commit 编号”。所以当你看到父项目的git status里显示子模块目录有修改时，本质上是在说“子模块当前不在父项目记录的 commit 上”。

这种机制带来的好处很直接：

• 公共代码统一维护，一处修改、按需更新到各项目。
• 子模块版本由父项目精确锁定，构建可复现，不会出现“昨天还是好的，今天拉下来就变了”的情况。
• 权限边界清晰，子模块仓库可以单独授权给特定团队。

1.2 哪些场景其实不该用子模块

先说句实在的，子模块是工具，不是银弹。如果一个功能用普通依赖管理就能解决，我建议你优先用依赖管理。

比如你用的是 Java，公共代码完全可以拆成一个 Maven 模块发布到私有仓库；用 Go，就拆成独立 module，通过go mod引用版本；前端的话，发布 npm 私有包是最常规的做法。这些东西都有成熟的版本管理、缓存、锁文件机制，团队成员用起来也无感，不需要懂子模块那套“先把父项目推了还是先把子项目推了”的顺序问题。

那什么时候才值得用子模块？我总结下来是这几种情况：

• 公共代码的更新节奏和主项目强耦合，比如配置文件、协议定义、构建脚本，必须和主项目代码同时处于某个一致状态。
• 依赖管理工具解决不了，比如不同语言的混编项目、跨技术栈共享的协议文件。
• 你需要把某个外部项目以“可独立开发、独立回退”的方式嵌入自己的代码库。

还有一类场景我强烈不建议用子模块搞：比如只是想把某个开源库固定版本，那直接用 Git tag + 包管理工具就行，没必要引入子模块，纯粹给自己和同事添乱。子模块的每一个状态变化、分支切换、拉取更新，都对操作者的 Git 水平有隐性要求，团队里只要有一个不太熟的同事，大概率就要出幺蛾子。

2. 在 GitLab 上从零创建一个子模块

2.1 前置准备：仓库、SSH 与权限

创建子模块之前，先在 GitLab 上把仓库建好。这里的“仓库”至少两个：一个是父项目，一个是待嵌入的子模块仓库。

拿一个实际例子来说。父项目叫web-app，子模块仓库叫shared-docs，里面放的是各个项目通用的接口文档和协议定义。子模块代码已经推到了 GitLab 的某个 Group 下，路径类似gitlab.example.com/dev/shared/shared-docs.git。

接下来要确认的就是访问权限。在 GitLab 上，父项目和子模块仓库的可见性最好保持一致，或者至少保证每个需要对父项目进行克隆、更新操作的成员，都对子模块仓库有读权限。这里有个常见的坑：父项目是 internal，子模块仓库是 private，那同事在做 CI 或者在新电脑上初始化子模块时，会在拉取阶段就报权限错误，而且报错信息不太容易联想到权限问题。

Clone 方式也要提前统一。如果你用 SSH 地址添加子模块，那所有人的机器上都必须配置好对应的 SSH Key；如果用 HTTP 地址，就要处理好用户名密码或者 Personal Access Token。我的习惯是在 GitLab 上统一用 SSH 地址添加子模块，团队新成员入职时先完成 SSH Key 配置，后续基本不会在权限上卡壳。具体到 GitLab 配置 SSH Key，就是在用户设置里把公钥贴进去，然后把私钥放到本地~/.ssh目录并设置好权限。

2.2 用 git submodule add 添加公共仓库

环境准备好之后，操作其实就一条命令。在父项目根目录执行：

git submodule add git@gitlab.example.com:dev/shared/shared-docs.git shared-docs

命令末尾的shared-docs是你要把子模块放到父项目里的路径后缀，也可以写成别的位置，比如docs/apis。如果目录名和你想要的本地文件夹名不一致，就在命令最后显式指定路径，Git 会按照这个路径来放置子模块。

执行完这条命令后，效果是：

• 新建了一个shared-docs目录，并把子模块仓库代码完整 clone 到了这个目录里。
• 父项目根目录生成了一个.gitmodules文件，记录子模块的映射关系。
• git status里会出现.gitmodules文件和shared-docs目录，后者显示为一种特殊状态，Git 里通常叫 gitlink，文件模式是160000，这和我们平时看到的普通文件、可执行文件都不一样。

当我把修改推送之后，再去 GitLab 网页上看提交记录，会看到shared-docs这一项看起来像是一个不可展开的目录，点击跳转到子模块仓库。父仓库的每次提交，都会把这个 gitlink 指向的 commit 记录在案。

2.3 .gitmodules 文件到底在管什么

.gitmodules是子模块的“总控制文件”，正常添加完子模块之后，它会长得像这样：

[submodule "shared-docs"] path = shared-docs url = git@gitlab.example.com:dev/shared/shared-docs.git

解释一下这里每个字段的含义：

• submodule "shared-docs"：双引号里的名字是子模块的标识符，默认取路径最后一个目录名，也可以手动改成更有意义的名称。
• path：子模块在父项目里的相对路径，本地结构靠它确定。
• url：子模块仓库的克隆地址，不同人克隆父项目时，Git 会依据这个地址去拉取子模块代码。

再补充一个很实用但容易被忽略的参数。如果你希望子模块跟踪远程的某个分支，而不是停留在某个提交上，可以在.gitmodules里这样加：

[submodule "shared-docs"] path = shared-docs url = git@gitlab.example.com:dev/shared/shared-docs.git branch = main

这个branch参数配合git submodule update --remote时特别关键，后面更新部分我会细说。

.gitmodules是需要提交到父项目仓库的，它是团队协作时其他人能否正确还原子模块结构的基础。任何时候手动修改了.gitmodules，记得执行一下git submodule sync，让本地配置和它对齐，否则可能出现本地还能跑、别人一拉就挂的诡异问题。

3. 团队协作：克隆带子模块项目的正确姿势

3.1 普通克隆之后的两条命令

很多第一次接触子模块的同事，拿到的操作指引是这样的：先git clone父项目，然后发现子模块目录是空的，接着一脸懵。

这不怪他们，因为默认状态下 Git 不会自动拉取子模块内容。克隆父项目后，子模块目录里只有一个空的占位目录，你需要额外执行：

git submodule init git submodule update

init的作用是读取.gitmodules里的配置，把子模块 URL 写入本地仓库配置；update则是根据父项目记录的 commit 把子模块代码实际拉取下来。

嫌两条命令麻烦的话，直接合并成一条：

git submodule update --init

或者从一开始就用递归克隆的方式一步到位：

git clone --recurse-submodules git@gitlab.example.com:dev/web-app.git

如果有嵌套子模块的情况，也就是子模块里还有子模块，就再加一个--recursive参数。我办公电脑的新环境初始化一般就是这一套组合拳，省心很多。

这里必须多说一句：git submodule update拉下来的子模块，默认处在一个游离 HEAD（detached HEAD）状态。也就是说，子模块工作区的 HEAD 不指向任何分支，而是直接停留在某个具体的 commit 上。很多人在这里会慌，以为代码出问题了，实际上这是 Git 刻意为之，目的是保证父项目记录的版本不被意外改变。

3.2 分支与更新：子模块的 detached HEAD 困局

游离 HEAD 带来的典型问题就是：你在子模块目录里基于当前提交改代码，改完后想推送到 GitLab 的子模块仓库，但是发现git push没有把改动推到期望的分支上，或者切分支变得很别扭。

正确的协作方式应该是这样的：

第一次克隆或者 update 完之后，先在子模块目录里切到你想要开发的分支。比如你想在develop分支上改代码：

cd shared-docs git checkout develop git pull origin develop

然后再正常开发和推送。这样你本地的工作区就和子模块仓库的某个分支建立了联系，游离 HEAD 问题就绕开了。

另外就是子模块的更新策略。日常开发中，我们经常会遇到“父项目记录的子模块版本太旧，我想把子模块更新到最新再开发”的情况。你可以这样操作：

git submodule update --remote

这个命令会去每个子模块的远程仓库拉取最新提交。这里有个前提要记牢：--remote默认拉取远程origin上那个 git 默认分支的最新提交，如果你想跟踪特定分支，就必须在.gitmodules里配置branch字段。

比如.gitmodules里写成branch = main，那么执行git submodule update --remote时，Git 就会拉取子模块仓库 main 分支的 HEAD，并把本地子模块移动到这个提交上。之后如果你对这个新版本满意，就在父项目里提交子模块指针的更新；不满意，就回到之前记录的 commit。

这个更新机制在多人协作时特别容易产生冲突，因为每个人可能会在父项目里推进不同的子模块 commit。所以我的习惯是：父项目里子模块指针的更新，尽量由专人负责，或者在合并代码前去统一跑一次更新，避免每个分支都带着不同的子模块版本，合并的时候一堆冲突。

4. 日常开发的完整闭环：改代码、提交、同步

4.1 修改子模块代码的流程与提交顺序

日常开发和子模块打交道，最典型的工作流是这样：

1. 进入子模块目录，切到自己开发用的分支。
2. 改代码，常规的git add、git commit。
3. 把子模块代码推送到 GitLab 上的子模块仓库。
4. 回到父项目目录，这时你会发现git status里子模块目录变了，多了一个箭头和新的 commit 信息。
5. 在父项目里git add这个子模块路径，然后提交，再推送到父项目的 GitLab 仓库。

这个顺序看起来很自然，但有个点必须反复强调：先推子模块，再推父项目。

原因很简单。父项目记录的是子模块某个 commit 的引用，如果你先推送父项目，GitLab 上父项目的最新提交指向了一个在子模块仓库中并不存在的 commit，别人一克隆或者 CI 一构建，子模块拉取就会失败，直接报错。这种错误排查起来也比较烦，因为报错信息往往很含糊，GitLab 网页上也没法直观看出问题在哪。

如果是走 Merge Request 流程，那就更要小心了。子模块代码的 MR 和父项目指针更新的 MR 最好分开提交，并且在合并时先合并子模块仓库的那个 MR，等它合并进目标分支后，再合并父项目里的指针更新 MR。否则就算你在本地测试通过了，合并顺序一乱，线上构建照样挂。

4.2 子模块指针更新与父仓库的提交

在父项目里，子模块状态的变化是“整体提交”的形式。你在父项目里执行：

git add shared-docs git commit -m "chore: update shared-docs to latest"

这时候提交的是子模块目录的指针，而不是子模块内部文件的 diff。你可以在父项目的提交详情里看到类似这样的信息：

Subproject commit c4a2f8e... (更新说明)

有的时候你只是进子模块目录看了一眼，没有改任何东西，但回到父项目却发现git status提示子模块目录有修改。这种情况一般有两个原因：一是子模块当前处在一个不是父项目记录的 commit 上，哪怕只是切换了分支也会产生这个提示；二是子模块工作区里有未提交的改动，包括新建文件、修改文件、甚至删除文件。排查办法很简单，进子模块目录执行git status，看看到底是什么状态，然后该提交的提交、该清理的清理。

另一个容易模糊的是“本地子模块版本比父项目记录的要新”的情况。比如你在子模块仓库里多提交了几个 commit，但父项目里的指针还停留在旧提交上。这时父项目的git status同样会提示子模块有修改。确认子模块代码没问题之后，按上面流程把指针更新一下再提交父项目即可。

这里我分享一个实际操作中的小技巧：每次更新完子模块，我会在父项目提交信息里写清楚子模块从哪个 commit 更新到哪个 commit，以及更新的原因。比如：

git commit -m "chore: update shared-docs c4a2f8e -> 91b3d5d; 新增 API 鉴权字段说明"

这样做的好处是以后排查问题、回滚版本时，一眼就能定位到该看哪一次提交。

5. 删除、替换与迁移：子模块的维护操作

5.1 完整移除子模块的步骤

很多团队说子模块“请神容易送神难”，其实是因为移除步骤不全，导致模块残留或者 Git 配置混乱。完整移除一个子模块需要执行以下步骤：

先反注册子模块：

git submodule deinit -f shared-docs

这一步会让本地配置里移除该子模块的记录，Git 还会删除本地 work tree 中的内容。如果这里提示 work tree 还有本地改动，加上-f强制清理。

再从父项目索引和磁盘中删除：

git rm -f shared-docs

git rm在这里会清理目录，并暂存这个删除操作。

接着把.git/modules/shared-docs文件夹删掉，这个是子模块在父项目 .git 目录里缓存的本地裸仓库数据。如果不删，子模块相关的 object、config 还会留在本地。

最后记得清理.gitmodules文件里对应的段落。如果.gitmodules里没有其他子模块了，直接把整个文件删掉；如果还留着别的子模块，就只删除对应的那一段配置。

完成以上操作后，正常提交推送，这个子模块就算彻底拔干净了。

5.2 修改子模块远程地址

还有一种常见需求：子模块仓库从旧地址迁移到了新地址。比如 GitLab 上改了 Group 路径，或者整个仓库迁移到了新的 GitLab 实例。

这时候只改.gitmodules文件是不够的，因为本地仓库的配置里也缓存了一份子模块 URL，不更新的话，git submodule update还是会尝试连接旧地址。

主流程是这几步：

git config -f .gitmodules submodule.shared-docs.url 新地址 git config submodule.shared-docs.url 新地址 git submodule sync

然后进入子模块目录更新远程地址并拉取：

cd shared-docs git remote set-url origin 新地址 git fetch origin

修改完成后记得提交git submodule sync对人本地配置做的更新。如果团队其他人还没有同步，他们拉取父项目的新提交时，git submodule update会根据.gitmodules里的新 URL 去拉取，但是本地 config 可能还是旧地址。所以如果你们改了子模块地址，一定要提醒同事先在本地运行git submodule sync，这个问题可以说是我见过“团队内发生率最高”的子模块困惑之一。

6. GitLab CI/CD 里子模块的自动构建

6.1 用 GIT_SUBMODULE_STRATEGY 控制拉取策略

如果你在 GitLab 上配置了 CI/CD，那子模块处理就是一个绕不开的环节。默认情况下，GitLab Runner 拉取代码时也不会自动拉子模块，你必须在.gitlab-ci.yml里显式配置。

我常用的配置是这样的：

variables: GIT_SUBMODULE_STRATEGY: recursive

这个变量告诉 GitLab Runner：在拉取父项目代码之后，要同步去拉取子模块。取值主要有这几个：

• none：不拉取子模块，默认策略。
• normal：只拉取一级子模块。
• recursive：递归拉取所有嵌套的子模块，对应本地命令git submodule update --init --recursive。

如果子模块仓库的可见性允许 CI 直接访问，那配置到这里基本就够了。如果不行，你可能需要为 CI 配置专门的部署凭证或者 Deploy Token，然后在 CI 变量里设置访问权限相关的内容。

项目里如果用到了其他 CI 工具，比如 Jenkins，思路也类似。在 Jenkins 的 SCM 配置里，通常有一个 "Additional Behaviours" 的选项，可以添加 "Recursively update submodules" 或者 "Advanced sub-modules behaviours"。本质上都是让 CI 在构建前把子模块代码准备齐全，这一步是很多自动化构建脚本里最容易遗漏的。

6.2 Docker 镜像构建时子模块代码怎么进容器

CI 里还有一个常见场景是构建 Docker 镜像。构建时最稳妥的方式是让 Docker 构建上下文包含子模块目录，因为上文提到的GIT_SUBMODULE_STRATEGY已经帮我们把子模块拉取到了 Runner 的工作目录里。

假设你的 Dockerfile 在父项目根目录，你希望在镜像中存有shared-docs里的协议文档，可以直接写：

COPY shared-docs /app/shared-docs

只要.dockerignore没有把shared-docs目录排除掉，构建时子模块内容就能正常打进镜像。

如果你是在docker build过程中才去拉取子模块，比如 RUN 阶段里执行git clone，那就要注意镜像内是否有 Git、SSH Key 或者认证凭据，还要处理网络访问 GitLab 的连通性。这种方式比较绕，我一般不建议，能直接用 build context 就把事情解决的话，就尽量直接用。

这里还容易碰到一个细节问题：GitLab Runner 拉取子模块时，因为父项目 clone 通常是 HTTP 方式，子模块如果配置的是 SSH URL，Runner 可能没有对应的 SSH Key 来认证。解决方式有两个方向：一是调整.gitmodules里的 URL 为 CI 可访问的 HTTP 地址，同时处理好 Deploy Token；二是给 Runner 单独配置可以访问子模块仓库的 SSH Key。实际配置时，我个人偏向第一种，在 CI 链路里尽量少碰 SSH 密钥管理，用 Deploy Token 和 HTTP URL 会更透明、也好排查。

7. 高频问题与避坑清单

7.1 我遇到过的真实坑与排查过程

这里挑几个我真实踩过、也在多个团队里见别人踩过的坑，按“现象 → 原因 → 处理方式”讲清楚。

第一个坑：克隆父项目后子模块目录为空。有时候同事反馈“代码拉下来了但目录是空的”，大部分情况都是没有执行git submodule update。解决办法就是补上初始化命令，或者直接用--recurse-submodules重新克隆。个别情况下，.gitmodules里的 URL 写错了，那就要先修正 URL 再同步，不然update会一直失败。

第二个坑：子模块代码改了，推不上 GitLab。最常见的原因是子模块工作区处于游离 HEAD，你的 commit 推到了“匿名分支”上。解决方式很简单，在编码之前先git checkout到目标分支，否则你本地生成的提交虽然在，但参考不到任何远程分支，自然推不上去。如果已经做了这个操作也没解决，那就去看 SSH Key 或者 token 对该子模块仓库有没有 push 权限。

第三个坑：CI 构建报fatal: could not read Username for 'https://gitlab.com'或者类似权限错误。这个基本就是 Runner 拉子模块时没有认证信息。去检查.gitmodules的 URL 是什么形式，再看 CI 变量里是否配置了 Deploy Token，以及 GitLab 上子模块仓库的权限设置。GitLab CI 里用 HTTP URL + Deploy Token 的方式，可以直接把用户名密码写在 CI 变量里，然后存入.gitmodules对应字段，虽然这样做有明文嫌疑，但在内网和短期 token 的前提下，还是有不少团队这么干。

第四个坑：删除了子模块但 GitLab 上还显示有子模块文件夹。这就是删除步骤不全的问题。只在文件系统里删了目录、或者只用了git rm，没有执行git submodule deinit，没有清理.gitmodules，那父项目里随时可能再次把子模块“拉回来”。按前面那个完整移除流程走一遍就行。

7.2 问题速查表

对应关系整理成一张表，遇到问题先来这里对号入座：

这张表基本覆盖了使用 GitLab + Git Submodule 时 80% 的日常问题，剩下的基本都是一些环境或权限层面的特殊问题，排查思路也是从“父项目记录了什么、子模块实际状态是什么”入手。

8. 再说几句实操体验

就我自己这些年的使用感受来说，git submodule 是个能用好也能用崩的功能。团队规模小、公共仓库稳定、大家 Git 操作都比较熟练的时候，子模块比依赖管理更直观、更好控制版本；团队一旦扩大或者成员水平参差不齐，子模块带来的复杂度就会迅速凸显。所以我的建议一向是：能用依赖管理就用依赖管理，确实需要子模块的场景，一定要把操作流程和更新规范固化下来，定期提醒团队按统一的流程来。

最后再分享一个小技巧。如果你希望团队从搭建环境到日常更新的流程足够顺滑，可以考虑把常用命令封装成脚本或者 Makefile target，比如make init对应克隆加git submodule update --init --recursive，make update-submodules对应git submodule update --remote再自动提交。这样能把容易出错的步骤变成稳定的命令，同事用起来基本无脑，也更愿意遵守约定，自然就少了很多互相踩坑的后续。