应使用 Git 子模块或私有 npm 包管理公共组件，因直接 merge 会破坏依赖链、引发版本不一致和 CI 构建失败；子模块支持按需指定 commit/tag，npm 包则通过语义化版本与 lockfile 保障环境一致性。
跨分支同步公共组件，不能靠 merge 或 cherry-pick 硬搬，否则依赖链会断裂、版本不一致、CI 构建失败是大概率事件。
为什么直接 merge 公共组件分支会出问题
公共组件（比如 shared-components）通常被多个业务分支（feature/login、release/2.1.x、hotfix/2.0.5）同时引用。如果对组件做升级后，直接用 git merge 把组件变更合入某个业务分支：
- 该分支可能只依赖组件的某几个 API，而 merge 进来的是一整套变更，包含未测试过的内部重构
- 不同业务分支使用的组件版本本就不一致，强行统一会导致编译报错或运行时
TypeError: xxx is not a function - CI 流水线里
npm install或yarn install依赖的是 lockfile 中的精确版本，merge 不会自动更新它
用 git submodule 管理组件版本更可控
把公共组件作为子模块接入各业务分支，每个分支可独立指定所用的组件 commit 或 tag，避免“一刀切”式同步：
- 初始化时：在业务仓库根目录执行
git submodule add https://gitlab.example.com/team/shared-components.git shared-components - 升级指定分支：进入
shared-components目录，git checkout v2.3.1，再回到主仓库git add shared-components提交 - CI 中需显式执行
git submodule update --init --recursive，否则构建会找不到组件代码 - 注意：子模块的
.gitmodules文件必须提交，否则其他协作者拉取后无法自动初始化
用 npm/yarn workspace + versioned packages 替代子模块
当组件已发布为私有 npm 包（如 @org/auth-kit@2.3.1），业务分支通过 package.json 声明依赖，比子模块更轻量、更易 CI 集成：
- 升级只需改
package.json中对应字段，例如："@org/auth-kit": "2.3.1" - 执行
yarn install或npm install后，lockfile 自动更新，确保所有环境依赖一致 - 关键点：组件包必须带语义化版本（SemVer），且每次发布都打 tag，如
v2.3.1，否则无法精准回滚 - 风险点：如果组件包未启用
publishConfig.access: "restricted"，可能误推送到公开 registry
同步策略选型要看团队成熟度和发布节奏
子模块适合组件尚未封装成包、或需要调试源码的场景；npm 包方案要求有私有 registry 和规范的发布流程。最容易被忽略的是：
- 组件升级后，必须同步更新所有使用它的业务分支的 lockfile，否则
npm ci仍会装旧版 - CI 中若用缓存（如 GitHub Actions 的
actions/cache），需把node_modules和yarn.lock都纳入 key 计算，否则缓存命中导致版本错乱 - GitLab EE 用户可配置
Push Mirror自动同步组件仓库到私有 registry，但 CE 版只能靠脚本轮询触发发布
