混合模式 Monorepo/Multi-Repo 系统：基于 pnpm 与 GitLab 的深度实践指南

架构一份集成的混合模式 Monorepo/Multi-Repo 系统：基于 pnpm 与 GitLab 的深度实践指南

---

第 1 节：解构双模式开发挑战

1.1. 混合模式导论

在现代软件工程实践中，项目结构的选择对开发效率、代码质量和长期可维护性具有深远影响。两种主流模式——Monorepo（单体仓库）和 Multi-Repo（多仓库）——各有其明确的优势和适用场景。Monorepo 通过将所有相关项目置于单一版本控制仓库中，极大地简化了依赖管理、原子化提交和跨项目重构，从而提升了开发速度。然而，它也可能导致仓库膨胀、构建时间延长以及访问控制复杂化。相反，Multi-Repo 模式为每个项目或库提供了独立的生命周期、清晰的所有权边界和精细的访问控制，但代价是跨仓库协作和依赖管理的复杂性显著增加。

本次报告旨在解决一个更为复杂和精妙的架构需求：构建一个**混合模式（Hybrid Model）**系统。该系统旨在融合 Monorepo 的开发便利性与 Multi-Repo 的模块化和独立性。其核心目标是创建一个能够根据开发者操作上下文动态切换行为的开发环境，具体表现为两种截然不同的操作模式：

1. 工作区模式（Workspace Mode）： 当开发者在包含所有子项目的“超级项目”（super-project）根目录下工作时，pnpm 应以标准的工作区（workspace）形式运行。此时，项目间的内部依赖通过符号链接（symlink）在本地进行关联。这种模式允许开发者无缝地进行跨项目代码修改、调试和联调，享受 Monorepo 带来的集成开发体验。
2. 独立模式（Standalone Mode）： 当开发者仅克隆或在集成开发环境（IDE）中单独打开某一个子项目时，该项目必须表现为一个完全独立、自给自足的实体。在此模式下，执行 pnpm install 命令应从远程包注册表（Package Registry）中获取其所有已发布的依赖包，而非链接到本地文件系统中的其他项目源码。这确保了每个子项目都可以被独立开发、测试、构建和消费，如同一个标准的、非 Monorepo 环境下的独立软件包。

要实现这种双模式的共存，其本质并非在 Monorepo 和 Multi-Repo 之间做出非此即彼的选择，而是要精心设计一套架构，使得工具链（尤其是 Git 和 pnpm）的行为由开发者的当前工作目录（即操作上下文）来决定。本报告将系统性地阐述如何通过组合 Git 的高级功能和 pnpm 的精细化配置，来构建这样一个健壮、高效且可扩展的混合模式系统。

1.2. 基础性前提：包注册表的关键角色

在深入探讨技术实现之前，必须明确一个贯穿整个架构设计的核心前提：“独立模式”的实现，其根本在于将所有子项目视为标准的、遵循语义化版本（SemVer）的软件包。若无此前提，子项目之间将永远无法摆脱源码级别的耦合，从而无法真正实现独立。

这意味着，一个健壮的版本管理、包发布和托管策略并非该架构的附属品或后期优化项，而是其赖以建立的基石。每个子项目（无论是应用还是库）都必须拥有独立的版本号，并通过一个标准化的流程发布到统一的包注册中心。当处于“独立模式”时，pnpm 正是通过查询这个注册中心来解析和下载依赖，从而实现与工作区源码的解耦。

根据用户需求，本报告将以 GitLab Package Registry 作为目标包托管平台。GitLab 提供了一套集成的解决方案，允许将包注册表与源代码、CI/CD 流水线紧密结合，为实现本架构所需的高度自动化提供了理想的环境 1。因此，后续所有关于发布和消费包的讨论，都将围绕 GitLab Package Registry 的工作流展开。

1.3. 需要克服的关键技术挑战

实现上述双模式愿景，需要解决一系列相互关联的技术难题。本报告将逐一攻克以下四个核心挑战：

1. 仓库组合（Repository Composition）： 如何将多个在 GitLab 上拥有独立 Git 历史的仓库，有效地组织成一个逻辑上统一的“超级项目”，以支持“工作区模式”下的集成开发？这需要对 Git 的高级仓库管理模型进行深入分析和选择。
2. 条件化依赖解析（Conditional Dependency Resolution）： 如何配置 pnpm，使其能够根据操作上下文，智能地在“链接本地源码”和“从远程注册表抓取”这两种依赖解析策略之间进行切换？这涉及到对 pnpm 工作区协议和配置文件的精细化控制。
3. 开发者工作流与 Git 操作（Developer Workflow & Git Operations）： 在复合的仓库结构下，如何设计一套清晰、低心智负担的 Git 工作流？这包括代码贡献、版本更新以及父子仓库间的同步，必须避免引入过度的操作复杂性。
4. CI/CD 自动化（CI/CD Automation）： 如何设计和实现一套能够完全自动化测试、版本控制、打包和发布的 CI/CD 流水线？该流水线必须能够理解并正确处理复合的 Git 结构，并与 GitLab 生态系统无缝集成。

第 2 节：架构策略：Git 仓库模型的比较分析

导言

构建混合模式系统的第一个、也是最具决定性的架构决策，是选择一种合适的 Git 策略来将独立的子项目仓库组合成一个统一的超级项目。这个选择将直接影响开发者的日常工作流、项目的历史记录管理方式，以及后续 CI/CD 流水线的实现复杂度和健壮性。本节将对两种主流的 Git 复合仓库模型——Git Submodules 和 Git Subtree——进行深度比较，并基于本项目的特定需求做出明确的架构推荐。

2.1. Git Submodules：仓库的联邦

• 核心概念： Git Submodule 的本质是一个引用或指针 2。当您将一个仓库作为子模块添加到父仓库（即超级项目）时，父仓库本身并不存储子模块的任何文件内容或完整的提交历史。它只记录两项关键信息：子模块在父仓库文件系统中的

  路径，以及子模块应该被检出的确切提交哈希（commit hash） 4。这种机制确保了子模块始终是一个独立的、拥有完整历史的 Git 仓库，父仓库只是在特定时间点“引用”了它的某个状态。

• 工作流：

  • 克隆： 克隆一个包含子模块的父仓库时，需要使用 git clone --recurse-submodules 命令，或者在常规克隆后执行 git submodule update --init --recursive 4。这个额外的步骤向开发者明确地揭示了项目间的依赖关系，强调了子模块的独立性。
  • 修改： 开发者需要使用 cd 命令进入子模块的目录。一旦进入该目录，就可以像操作一个普通、独立的仓库一样进行工作——创建分支、提交修改、查看历史等。所有 Git 命令都作用于子模块自身 7。
  • 推送变更： 在子模块中完成的提交必须从子模块目录内部推送到其自己的远程仓库 7。
  • 更新父仓库： 在子模块的变更被推送到其远程后，开发者需要返回到父仓库的根目录。此时执行 git status，会看到子模块的状态显示为“已修改（new commits）”，表明它现在指向了一个新的提交哈希。开发者必须在父仓库中创建一个新的提交，将这个指向新哈希的“指针”更新记录下来。这个提交是父仓库级别的，其内容就是更新子模块的版本引用 3。

• 与用户目标的对齐性： Git Submodule 模型与用户提出的“每个子项目都有独立的 git 仓库”这一核心要求高度吻合。每个子模块自始至终都是一个拥有完整、清晰、不受干扰的提交历史的独立仓库实体 8。父仓库与子模块的关系是一种松散的“联邦”关系，而非紧密的“融合”。

2.2. Git Subtree：历史的融合

• 核心概念： 与 Submodule 相反，git subtree 的工作方式是将另一个仓库的文件内容和提交历史完整地复制到父仓库的一个子目录中 9。这意味着子项目的历史记录被合并进了父仓库的历史记录流中，成为父仓库历史的一部分。

• 工作流：

  • 克隆： 开发者只需执行简单的 git clone 命令。克隆完成后，所有子树的文件都已存在于本地，对于不了解背景的协作者来说，这个依赖关系是隐性的，看起来就像一个普通的文件夹 10。
  • 修改： 对子树内文件的修改会直接在父仓库中进行提交，与其他文件的修改无异。
  • 同步更新： 当需要从子树的上游仓库拉取更新，或将本地对子树的修改推送回其上游时，需要使用 git subtree pull 或 git subtree push 这样复杂且专门的命令。这些命令在后台执行复杂的历史“切片”和合并操作，对于双向同步，这个过程常常被认为是复杂且容易出错的 10。

• 与用户目标的偏离性： Git Subtree 模型与本项目的核心需求存在根本性的冲突。它没有维护独立的仓库历史，而是将它们融合在一起，这使得将子项目作为一个真正独立的实体来对待变得非常困难。其设计初衷更倾向于一次性地“吸收”外部代码，而非持续地、独立地协同演进。

2.3. 推荐框架与决策

在选择 Git 模型时，不能仅仅停留在功能层面的比较，更需要评估其对整个开发与运维生命周期的深远影响，特别是与 CI/CD 工具链的集成能力和对开发者体验的塑造。

选择 Git Submodule 不仅是技术上的偏好，更是基于对项目长期可维护性和自动化效率的战略考量。GitLab CI/CD 对 Submodule 提供了原生的、一等公民级别的支持。在 .gitlab-ci.yml 中，可以通过设置 GIT_SUBMODULE_STRATEGY 变量（如 recursive 或 normal）来指示 GitLab Runner 自动、高效地处理子模块的克隆和检出 12。这是一个经过官方优化和保障的特性。相比之下，GitLab CI 对 Git Subtree 没有任何内建支持。要在 CI 流水线中同步一个子树，将不得不编写脆弱的自定义脚本，手动执行

git subtree pull 命令，并处理随之而来的远程仓库配置、认证和复杂的合并逻辑。因此，选择 Submodule 是在利用平台原生的能力，从而降低实现成本、减少维护负担并提升流水线的可靠性；而选择 Subtree 则意味着引入了需要长期维护的、非标准的自动化技术债。

从开发者体验（DX）的角度来看，Submodule 的工作流虽然在更新父仓库时需要额外一次提交，但这恰恰提供了一种极为清晰和明确的依赖管理语义。父仓库中的一个提交信息，如 feat: update lib-b to commit abc1234，构成了一条可追溯、可审计的依赖版本变更记录。这对于理解系统演进、排查问题和进行代码审查都至关重要。而 Subtree 融合后的历史记录，则很容易模糊掉一个内部依赖是在何时、因为何种原因被更新的，增加了认知负荷。

为了直观地展示这一决策过程，下表对两种模型进行了多维度比较：

表 2.1: Git Submodule 与 Git Subtree 的架构选型对比分析

特性	Git Submodule	Git Subtree	本项目推荐
历史管理	独立的提交历史，父仓库仅存储引用。	合并的提交历史，子仓库历史成为父仓库的一部分。	Submodule。符合独立仓库的核心要求。
初次克隆	需 clone --recurse-submodules 或额外步骤。	简单的 git clone，所有文件立即可用。	Submodule。显式操作有助于开发者理解项目结构。
贡献工作流	在子目录中执行标准 Git 操作，然后在父仓库提交引用更新。	直接在父仓库提交，推送/拉取需专门的 subtree 命令。	Submodule。工作流更符合标准 Git 心智模型，操作更清晰。
依赖可见性	显式，通过 .gitmodules 文件定义。	隐式，表现为普通目录，无特殊元数据文件。	Submodule。明确的依赖声明更利于自动化和管理。
GitLab CI 集成	原生支持，通过 GIT_SUBMODULE_STRATEGY 变量。	无原生支持，需要复杂的自定义脚本。	Submodule。极大降低 CI/CD 实现和维护成本。
核心复杂性	概念层面：理解指针和引用的关系。	操作层面：掌握并正确使用复杂的 push/pull 命令。	Submodule。概念上的学习成本低于操作上的风险成本。

最终推荐：

综合考量，Git Submodules 是构建本混合模式系统的唯一合理架构基础。它在仓库独立性、贡献工作流清晰度以及与 GitLab CI/CD 生态系统的原生集成能力上，均表现出无可比拟的优势，完美契合了项目的核心设计目标。

第 3 节：pnpm 配置蓝图：实现条件化链接

在确定了使用 Git Submodules 作为仓库组合模型之后，架构的第二个关键支柱便是配置 pnpm，以实现核心的“双模式”依赖解析行为。本节将详细阐述如何通过组合使用 .npmrc 配置文件和 workspace: 协议，来精确控制 pnpm 的链接策略。

3.1. .npmrc 文件：链接行为的主开关

• 核心概念： pnpm 的行为受到一系列配置文件的高度影响，其中 .npmrc 文件扮演着重要的角色 15。在这些配置项中，

  link-workspace-packages 是控制工作区链接行为的关键开关 17。默认情况下（即不设置此项或设为

  true），pnpm 在安装时会检查工作区内是否存在与依赖声明的版本范围相匹配的包，如果存在，则优先使用本地符号链接。

• 关键配置： 为了实现“独立模式”作为默认行为，必须在超级项目的根目录下创建一个 .npmrc 文件，并包含以下内容：

  Ini, TOML

  link-workspace-packages=false
  

• 配置效果： 这行配置指令强制 pnpm 在默认情况下，即使工作区内存在同名包，也总是从远程包注册表解析和下载依赖。这一设定是实现“独立模式”行为的基础。当一个开发者单独克隆某个子项目时，由于该子项目目录下没有覆盖此设置的 .npmrc，pnpm 会自然地遵循其默认的、非链接的行为。

3.2. workspace: 协议：显式覆盖链接行为

• 核心概念： 仅仅关闭默认链接是不够的，我们还需要一种方法在“工作区模式”下重新启用链接。pnpm 为此提供了 workspace: 协议，这是一个强大而明确的指令 17。当一个依赖的版本号前缀为

  workspace: 时，它告诉 pnpm：“对于这一个特定的依赖，请忽略 .npmrc 文件中 link-workspace-packages=false 的设置，并强制从本地工作区中寻找并链接这个包。”

• 实现方式： 在定义子项目之间的依赖关系时，应在它们的 package.json 文件中使用 workspace: 协议。例如，如果 app-a 依赖于 lib-b：

  JSON

  // 在 packages/app-a/package.json 中
  {
    "name": "@my-group/app-a",
    "version": "1.0.0",
    "dependencies": {
      "lib-b": "workspace:^1.0.0"
    }
  }
  

  这里的 workspace:^1.0.0 表示 app-a 依赖于工作区内一个名为 lib-b 且其版本与 ^1.0.0 兼容的包。

• 发布的魔法： workspace: 协议最精妙之处在于它与发布流程的无缝集成。当执行 pnpm publish 命令时，pnpm 会在打包发布前，自动将 package.json 中的 workspace: 协议依赖转换为标准的版本号依赖 17。例如，如果

  lib-b 的当前版本是 1.0.2，那么发布到注册表的 app-a 的 package.json 中，依赖会变成：

  JSON

  "dependencies": {
    "lib-b": "^1.0.2"
  }
  

  重要的是，这个转换只发生在发布的包里，而您本地 Git 仓库中的源代码文件保持不变，依然是 workspace:^1.0.0。这个特性是实现双模式架构而无需手动干预的关键。

3.3. pnpm-workspace.yaml：定义工作区的边界

• 核心概念： pnpm 需要知道哪些目录是工作区的一部分，以便在解析 workspace: 协议时能够找到对应的本地包。pnpm-workspace.yaml 文件的作用就是定义工作区的根目录以及其所包含的包的路径范围 17。

• 配置方式： 在超级项目的根目录下，创建一个 pnpm-workspace.yaml 文件。使用 packages 字段和 glob 模式来声明所有子模块所在的目录。

  YAML

  packages:
    # 假设所有子模块都位于 'packages/' 目录下
    - 'packages/*'
  

  这个文件为 pnpm 提供了必要的上下文，使其能够在“工作区模式”下正确地将 workspace: 协议映射到本地的文件路径。

3.4. 架构综合：各部分如何协同创造双重模式

现在，我们将上述三个配置部分组合起来，阐明它们如何协同工作，从而根据上下文实现模式的自动切换。

这个系统的行为切换机制，其核心在于上下文的改变。pnpm 的行为完全取决于它在执行时所能“看到”的配置文件。

• 场景一：工作区模式（集成开发）

  1. 开发者通过 git clone --recurse-submodules 克隆整个超级项目。
  2. 此时，开发者的当前工作目录是超级项目的根目录。这个目录下同时存在 pnpm-workspace.yaml 文件和包含 link-workspace-packages=false 的根 .npmrc 文件。
  3. 开发者在根目录执行 pnpm install。
  4. pnpm 读取 pnpm-workspace.yaml，识别出这是一个工作区，并获知了所有子包（如 app-a, lib-b）的位置。
  5. 当解析 app-a 的依赖时，它遇到 "lib-b": "workspace:^1.0.0"。
  6. workspace: 协议作为一个高优先级指令，覆盖了根 .npmrc 文件中的 link-workspace-packages=false 设置。
  7. pnpm 随即在工作区内查找 lib-b，找到后便在 app-a/node_modules 中为其创建一个符号链接，指向本地的 lib-b 源码目录。
  8. 结果： 所有内部依赖都被本地链接，实现了高效的工作区模式。

• 场景二：独立模式（独立开发或消费）

  1. 另一位开发者（或 CI/CD 作业）仅需要 app-a。他执行 git clone 只克隆了 app-a 的独立仓库。
  2. 此时，工作目录是 app-a 的根目录。这个目录中不存在 pnpm-workspace.yaml 文件，也不存在那个设置了 link-workspace-packages=false 的根 .npmrc 文件。
  3. 开发者在 app-a 目录中执行 pnpm install。
  4. pnpm 在当前及其父目录中找不到 pnpm-workspace.yaml，因此它不会以工作区模式运行。
  5. 它读取 app-a 的 package.json 来解析依赖。这里有一个关键点：用于独立开发的 package.json 是已经发布到 GitLab Registry 的版本。如前所述，在发布过程中，"lib-b": "workspace:^1.0.0" 已经被自动转换成了 "lib-b": "^1.0.2"。
  6. 因此，pnpm 看到的是一个标准的版本依赖。它会查询配置的注册表（GitLab Package Registry），下载 lib-b 的 1.0.2 版本并安装到 node_modules。
  7. 结果： app-a 作为一个独立的包，其依赖从远程注册表获取，实现了独立模式。

这个架构的精妙之处在于，它利用了 pnpm 对环境配置的敏感性，实现了零手动切换的无缝体验。开发者只需通过选择克隆哪个仓库（超级项目 vs. 子项目），就自然地进入了对应的开发模式。

第 4 节：端到端实施指南

本节将提供一个详尽的、按部就班的实践指南，引导您从零开始，一步步构建起前述设计的混合模式架构。每个步骤都包含具体的命令和最佳实践说明。

4.1. 阶段一：在 GitLab 中进行基础仓库设置

此阶段的目标是在 GitLab 上创建项目所需的基础设施。

1. 创建 GitLab Group：

   • 登录您的 GitLab 实例。
   • 创建一个新的 Group，例如 my-hybrid-workspace。所有相关的项目都将存放在这个 Group 内，便于权限管理和逻辑组织。

2. 创建子项目仓库：

   • 在 my-hybrid-workspace Group 内，为每一个子项目创建一个独立的 Git 仓库。这些仓库将作为 Git Submodules 存在。
   • 例如，创建 app-a 和 lib-b 两个项目。
   • 确保这些项目的可见性（Private/Internal/Public）符合您的安全要求。

3. 创建超级项目仓库：

   • 同样在 my-hybrid-workspace Group 内，创建一个用于容纳所有子模块的父仓库，即“超级项目”。
   • 例如，创建 workspace-root 项目。这个仓库将包含 .gitmodules 文件、根 pnpm 配置以及 CI/CD 流水线定义。

4.2. 阶段二：使用 Git Submodules 组合超级项目

此阶段的目标是将独立的子项目仓库作为子模块集成到超级项目中。

1. 克隆超级项目：

   • 在您的本地开发环境中，克隆刚刚创建的空的超级项目仓库。

   Bash

   git clone git@gitlab.com:my-hybrid-workspace/workspace-root.git
   cd workspace-root
   

2. 添加子模块：

   • 使用 git submodule add 命令，将每个子项目仓库添加为子模块。建议将它们统一放置在一个目录下，如 packages/，以便于管理 4。

   Bash

   # 创建用于存放子模块的目录
   mkdir packages
   
   # 添加 app-a 子模块
   git submodule add git@gitlab.com:my-hybrid-workspace/app-a.git packages/app-a
   
   # 添加 lib-b 子模块
   git submodule add git@gitlab.com:my-hybrid-workspace/lib-b.git packages/lib-b
   

3. 配置相对路径（最佳实践）：

   • git submodule add 默认会在 .gitmodules 文件中记录完整的 SSH 或 HTTPS URL。为了提高在 GitLab CI/CD 环境中的可移植性和认证便利性，强烈建议手动将其修改为相对路径 13。

   • 打开生成的 .gitmodules 文件，其内容可能如下：

     Ini, TOML

     [submodule "packages/app-a"]
         path = packages/app-a
         url = git@gitlab.com:my-hybrid-workspace/app-a.git
     [submodule "packages/lib-b"]
         path = packages/lib-b
         url = git@gitlab.com:my-hybrid-workspace/lib-b.git
     

   • 将其修改为：

     Ini, TOML

     [submodule "packages/app-a"]
         path = packages/app-a
         url =../app-a.git
     [submodule "packages/lib-b"]
         path = packages/lib-b
         url =../lib-b.git
     

   • 这种相对路径格式允许 GitLab CI 在使用 CI_JOB_TOKEN 进行鉴权时，能自动解析出正确的 HTTPS URL，避免了复杂的 SSH 密钥配置。

4. 提交并推送变更：

   • 将 .gitmodules 文件和新添加的子模块引用提交到超级项目。

   Bash

   git add.gitmodules packages/app-a packages/lib-b
   git commit -m "feat: Add app-a and lib-b as submodules"
   git push origin main
   

4.3. 阶段三：pnpm 工作区配置

此阶段的目标是配置 pnpm 以实现条件化链接。所有操作都在超级项目 workspace-root 的根目录进行。

1. 配置根 package.json：

   • 初始化一个根 package.json 文件。这个文件主要用于定义整个工作区的开发依赖（如 TypeScript, ESLint, Changesets 等），并标记该项目为私有，防止被意外发布。

   Bash

   pnpm init
   # 编辑 package.json，设置 "private": true
   # 并添加 devDependencies
   pnpm add -D -w typescript eslint prettier @changesets/cli changesets-gitlab
   

   • -w 或 --workspace-root 标志告诉 pnpm 将依赖安装到工作区的根目录。

2. 创建 pnpm-workspace.yaml：

   • 创建此文件以正式定义工作区的范围。

   YAML

   # pnpm-workspace.yaml
   packages:
     - 'packages/*'
   

3. 创建根 .npmrc：

   • 创建此文件以设置默认的非链接行为。

   Ini, TOML

   #.npmrc
   link-workspace-packages=false
   save-workspace-protocol=false # 推荐设置为 false，避免 pnpm add 自动添加 workspace: 前缀
   

4. 配置子模块的 package.json：

   • 进入每个子模块的目录，为其创建或修改 package.json。

   • 对于 packages/lib-b/package.json：

     JSON

     {
       "name": "@my-hybrid-workspace/lib-b",
       "version": "1.0.0",
       "main": "dist/index.js",
       "scripts": {
         "build": "tsc"
       },
       "devDependencies": {
         "typescript": "*" // 版本可以从根目录继承
       }
     }
     

   • 对于 packages/app-a/package.json：

     JSON

     {
       "name": "@my-hybrid-workspace/app-a",
       "version": "1.0.0",
       "dependencies": {
         "@my-hybrid-workspace/lib-b": "workspace:*"
       },
       "scripts": {
         "start": "node dist/index.js",
         "build": "tsc"
       },
       "devDependencies": {
         "typescript": "*"
       }
     }
     

   • 注意 @my-hybrid-workspace/lib-b 的依赖使用了 workspace:* 协议。* 表示接受工作区内任意版本的 lib-b。您也可以使用更具体的范围，如 workspace:^1.0.0。

   • 在每个子模块内提交 package.json 的变更并推送到它们各自的远程仓库。

4.4. 阶段四：验证开发工作流

此阶段的目标是模拟两种核心工作流，以确保架构按预期工作。

1. 验证工作区模式：

   • 在一个新的目录中，完整地克隆超级项目。

   Bash

   git clone --recurse-submodules git@gitlab.com:my-hybrid-workspace/workspace-root.git
   cd workspace-root
   

   • 安装依赖。

   Bash

   pnpm install
   

   • 验证： 检查 packages/app-a/node_modules/@my-hybrid-workspace/lib-b。您会发现它是一个指向 ../../lib-b 的符号链接。这证明了“工作区模式”已成功激活。

2. 验证独立模式（发布后）：

   • “独立模式”的真正验证发生在一个包被发布到 GitLab Registry 之后。在 CI/CD 章节（第 5 节）实现发布流程后，您可以按以下步骤验证：
   • 在一个全新的目录中，创建一个测试项目。
   • 配置 .npmrc 以指向您的 GitLab Group Registry。
   • 运行 pnpm add @my-hybrid-workspace/app-a。
   • 验证： pnpm 将从 GitLab Registry 下载 app-a 和 lib-b 的压缩包，而不是链接本地源码。app-a 的 package.json 中的依赖将是标准版本号，而非 workspace: 协议。

3. 演练贡献与同步工作流（对团队至关重要）：

   • 这是开发者日常工作中最重要的流程，必须清晰地传达给团队。

   1. 进入子模块并修改：

      Bash

      cd packages/lib-b
      git checkout -b feat/new-utility
      #... 进行代码修改...
      git add.
      git commit -m "feat(lib-b): add a new utility function"
      git push origin feat/new-utility # 推送到 lib-b 的远程仓库
      

   2. 在 lib-b 项目中创建合并请求（Merge Request）并完成合并。

   3. 返回父仓库并更新引用：

      Bash

      cd../../ # 返回 workspace-root 根目录
      git submodule update --remote packages/lib-b # 拉取 lib-b 的最新变更
      

   4. 检查状态并提交父仓库：

      Bash

      git status
      # 输出会显示：
      # modified:   packages/lib-b (new commits)
      

      这表明父仓库检测到 lib-b 的引用指针需要更新。

   5. 提交引用更新：

      Bash

      git add packages/lib-b
      git commit -m "feat: update lib-b to latest version with new utility"
      git push origin main # 推送到 workspace-root 的远程仓库
      

   这个两阶段提交（先在子模块中提交并推送代码，再在父仓库中提交并推送引用更新）是使用 Git Submodules 的核心工作流 7，必须成为团队的标准操作规程。

第 5 节：自动化与运维：GitLab CI/CD

在手动搭建并验证了基础架构后，本节将重点转向如何通过 GitLab CI/CD 实现完全自动化的测试、版本管理和发布流程，打造一个生产级的运维体系。

5.1. 根 .gitlab-ci.yml：流水线总编排

所有 CI/CD 的核心逻辑都定义在超级项目 workspace-root 的根 .gitlab-ci.yml 文件中。

• 子模块拉取策略：

  • 这是与子模块集成的首要步骤。必须在 .gitlab-ci.yml 的全局 variables 部分或具体作业中，定义 GIT_SUBMODULE_STRATEGY 变量。推荐值为 recursive，以确保 GitLab Runner 能够正确、递归地拉取所有层级的子模块 12。

  YAML

  variables:
    GIT_SUBMODULE_STRATEGY: recursive
  

• 认证与授权：

  • 由于子模块是独立的私有仓库，CI 作业需要权限来克隆它们。通过在第 4.2 节中将子模块 URL 设置为相对路径，GitLab Runner 可以利用内置的 CI_JOB_TOKEN 变量自动进行 HTTPS 认证 13。
  • 如果由于某些原因仍在使用 SSH 格式的 URL，可以设置 GIT_SUBMODULE_FORCE_HTTPS: "true"，强制 Runner 将 SSH URL 转换为 HTTPS URL 进行克隆，从而利用 CI_JOB_TOKEN 12。

• pnpm 缓存配置：

  • 为了大幅提升流水线执行速度，必须对 pnpm 的内容可寻址存储（store）进行缓存。缓存的 key 应与项目的依赖锁定文件 pnpm-lock.yaml 相关联，这样只有在依赖发生变化时缓存才会失效 27。

  YAML

  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      -.pnpm-store
    policy: pull-push
  
  before_script:
    - pnpm config set store-dir.pnpm-store
    - pnpm install --frozen-lockfile
  

5.2. 使用 Changesets 实现弹性的版本与发布流程

在 Monorepo 环境下，手动管理版本号和生成发布日志（Changelog）是一项繁琐且易错的任务。Changesets 工具提供了一套优雅的、以开发者为中心的工作流来自动化此过程。

• 关键选型：changesets-gitlab

  • 标准 changesets/action 是为 GitHub Actions 设计的，无法直接在 GitLab CI 中使用。经过研究，社区提供了功能对等的 changesets-gitlab CLI 工具，它专门为 GitLab 的 Merge Request 工作流进行了适配 30。这是实现本节自动化流程的关键技术选型。

• Changesets 工作流与 GitLab CI 集成：

  1. 开发者工作流：

     • 当开发者完成一项有意义的变更（如新功能或 bug 修复）后，在提交代码前，于超级项目根目录运行 pnpm changeset。
     • CLI 会以交互方式询问本次变更影响了哪些包、变更的类型（major, minor, patch）以及一段变更描述。
     • 这会生成一个唯一的 Markdown 文件存放在 .changeset/ 目录下。开发者需要将这个文件与代码变更一同提交并推送到功能分支。

  2. 创建合并请求（Merge Request）： 开发者为功能分支创建一个指向 main 分支的 MR。

  3. 合并到 main 分支： 当 MR 被审查通过并合并后，.changeset/ 目录下的变更文件也随之进入了 main 分支。

  4. “版本”作业（The "Version" Job）：

     • 此作业被配置为仅在 main 分支上运行。它执行 pnpm changesets-gitlab 命令。

     • 该命令会扫描 .changeset/ 目录，消费所有变更文件，然后：

       • 根据变更类型自动提升相关包的 package.json 中的版本号。
       • 更新每个包的 CHANGELOG.md 文件。
       • 自动创建一个名为 "Version Packages" 的新分支，并将上述文件变更提交。
       • 最后，基于这个新分支，自动向 main 分支发起一个新的**“发布合并请求”（Release MR）** 30。

  5. “发布”作业（The "Publish" Job）：

     • 此作业被配置为仅在“发布 MR”被合并到 main 分支后触发。
     • 它的核心任务是执行 pnpm publish -r，将所有版本已更新但尚未在注册表中的包发布出去。

• .gitlab-ci.yml 中的 Changesets 配置示例：

  YAML

  stages:
    - build
    - version
    - publish
  
  #... build and test jobs...
  
  version-packages:
    stage: version
    image: node:18-alpine # 使用 alpine 镜像以包含 git
    script:
      - apk add --no-cache git # 安装 git
      - pnpm changesets-gitlab
    rules:
      - if: '$CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE!= "merge_request_event"'
        # 确保有 changeset 文件存在才运行
        exists:
          -.changeset/*.md
  
  publish-packages:
    stage: publish
    script:
      # 认证脚本见下一节
      - #... authentication script...
      - pnpm publish -r --no-git-checks
    rules:
      - if: '$CI_COMMIT_BRANCH == "main" && $CI_COMMIT_MESSAGE =~ /^chore: release/ && $CI_PIPELINE_SOURCE!= "merge_request_event"'
  

5.3. GitLab Package Registry 集成

• 认证配置：

  • 为了让 pnpm publish 能够成功推送到 GitLab Package Registry，必须在作业运行前配置好认证信息。这通过动态生成一个临时的 .npmrc 文件来实现，使用 CI_JOB_TOKEN 进行安全认证 27。
  • 重要： 认证配置必须是**作用域（scoped）**的，即只为您在 GitLab 上的 Group 配置私有源。

  YAML

  # 在 publish-packages 作业的 before_script 或 script 部分
  before_script:
    - echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/" >>.npmrc
    - echo "${CI_API_V4_URL#https?}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >>.npmrc
  

• 包命名规范：

  • 重申，所有子项目的 package.json 中的 name 字段必须使用与 GitLab Group 匹配的作用域，例如 @"my-hybrid-workspace/app-a"。这是将包发布到 Group 级别注册表的必要条件。

5.4. 使用 rules:changes 优化流水线

在 Monorepo 中，一个常见的低效问题是每次提交都触发所有项目的测试和构建。rules:changes 关键字可以根据文件变更范围来决定是否执行某个作业，从而实现流水线的精细化控制 34。

• 关键机制： 当父仓库中更新一个子模块的引用时，从 Git 的角度看，这是一个对“文件”的修改——这个“文件”就是子模块在 Git 树中的条目。rules:changes 可以捕获到这个变更 36。

• 实现示例：

  YAML

  test:app-a:
    stage: test
    script:
      - pnpm --filter @my-hybrid-workspace/app-a test
    rules:
      # 在 MR 中，如果 app-a 的源码文件发生变化，则运行测试
      - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
        changes:
          - packages/app-a/**/*
      # 在 main 分支上，如果 app-a 的子模块引用发生变化（即版本更新），则运行测试
      - if: '$CI_COMMIT_BRANCH == "main"'
        changes:
          - packages/app-a
  

  这个配置实现了智能触发：

  • 在开发过程中，对 app-a 的修改只触发 app-a 的测试。

  • 在发布流程中，当 app-a 的版本被提升（子模块引用被更新）并合并到 main 分支时，也会触发其测试，确保新版本是可靠的。

    这种策略可以极大地节省 CI/CD 资源，并缩短反馈周期。

表 5.1: GitLab CI/CD 关键变量配置清单

变量名称	作用域	推荐值/来源	用途
GIT_SUBMODULE_STRATEGY	全局/作业	recursive	指示 Runner 递归地克隆所有 Git 子模块。
GIT_SUBMODULE_FORCE_HTTPS	全局/作业	true	（可选）当 .gitmodules 使用 SSH URL 时，强制转为 HTTPS 以便使用 CI_JOB_TOKEN。
GITLAB_TOKEN	项目 CI/CD 变量	手动创建的 Project Access Token (api scope)	供 changesets-gitlab 使用，以创建版本发布 MR 和 GitLab Releases。
CI_JOB_TOKEN	GitLab 内置	由 GitLab 提供	用于向 GitLab Package Registry 和其他项目仓库进行认证。
pnpm store 缓存路径	作业 cache	.pnpm-store	缓存 pnpm 下载的包，加速后续作业的 pnpm install。

第 6 节：高级主题与长期维护

本节将探讨在架构稳定运行后可能遇到的一些高级场景，并提供相应的解决方案和长期维护的最佳实践，以确保系统的健壮性和可扩展性。

6.1. 子项目应用的 Docker 化策略

将 Monorepo 中的单个应用打包成独立的、轻量级的 Docker 镜像是一个常见的需求，但 pnpm 的符号链接机制给标准 Dockerfile 写法带来了挑战 37。推荐的解决方案是利用

pnpm deploy 命令，它能创建一个不含符号链接、只包含生产依赖的纯净副本 38。

• 策略： 在超级项目的根目录创建一个多阶段 Dockerfile，通过 pnpm deploy 为目标应用生成一个可部署的目录结构，然后将这个纯净的目录复制到最终的镜像中。

• Dockerfile 示例（为 app-a 打包）：

  Dockerfile

  # --- 基础阶段 ---
  FROM node:20-slim AS base
  ENV PNPM_HOME="/pnpm"
  ENV PATH="$PNPM_HOME:$PATH"
  # 启用 corepack 来管理 pnpm
  RUN corepack enable
  
  # --- 构建阶段 ---
  # 此阶段安装所有依赖，包括 devDependencies，并构建整个工作区
  FROM base AS builder
  WORKDIR /app
  # 仅复制 lockfile 和 package.json 文件以利用 Docker 缓存
  COPY pnpm-lock.yaml.
  COPY package.json.
  COPY pnpm-workspace.yaml.
  # 安装所有依赖
  RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
  # 复制所有源代码
  COPY..
  # 构建整个工作区（或按需构建）
  RUN pnpm run -r build
  
  # --- 部署物生成阶段 ---
  # 使用 pnpm deploy 创建一个纯净的、生产就绪的 app-a 副本
  FROM builder AS deploy-stage
  WORKDIR /app
  # --prod 表示只包含生产依赖
  RUN pnpm deploy --filter @my-hybrid-workspace/app-a --prod /prod/app-a
  
  # --- 最终镜像阶段 ---
  FROM base AS final
  WORKDIR /app
  # 从部署物生成阶段复制纯净的应用副本
  COPY --from=deploy-stage /prod/app-a.
  
  EXPOSE 8080
  CMD [ "pnpm", "start" ]
  

• 构建命令：

  Bash

  docker build. --target final -t my-hybrid-workspace/app-a:latest
  

  通过 --target final，我们确保了最终镜像只包含 final 阶段的内容，体积小且安全。

6.2. 处理复杂场景

• 循环依赖： pnpm 在安装时能够检测并警告工作区内的循环依赖 17。本架构强制要求所有包都必须能够独立发布，而包管理器通常不允许发布带有循环依赖的包。因此，这个架构将迫使开发团队在开发早期就解决循环依赖问题，这实际上是一种架构上的约束，有利于维持健康的依赖关系图。

• 破坏性变更（Breaking Changes）： Changesets 工作流为处理破坏性变更提供了强大的流程保障。当开发者通过 pnpm changeset 将一个变更标记为 major 时，changesets-gitlab 创建的“发布 MR”将明确显示一个主版本号的跃升（例如，从 1.5.0 变为 2.0.0）。这为团队提供了一个清晰、强制性的审查关口，在破坏性变更被合并和发布之前，所有相关人员都有机会进行评估和准备。

• 团队成员引导与文档（Onboarding & Documentation）：

  一个成功的架构离不开清晰的文档和流程。超级项目的根目录 README.md 必须成为团队的“单一事实来源”，其中应详细说明以下关键信息：

  • 初始设置： 明确指出必须使用 git clone --recurse-submodules 来克隆项目。
  • 贡献流程： 详细图解或文字描述在子模块中修改代码后，必须遵循的“两阶段提交”工作流。
  • 版本管理： 强制要求所有非琐碎的变更都必须通过 pnpm changeset 命令来记录，并解释其重要性。
  • 发布流程： 简要说明 CI/CD 是如何自动处理版本和发布的，以及如何审查“发布 MR”。

6.3. 架构总结与最佳实践清单

本报告提出并详细论证了一套用于构建混合模式开发系统的综合架构。其核心由三大支柱构成：

1. 仓库组合层： 采用 Git Submodules 模型，确保各子项目拥有独立的 Git 历史，同时又能被统一管理。
2. 依赖管理层： 采用 pnpm，通过在根目录设置 link-workspace-packages=false 并结合在包依赖中使用的 workspace: 协议，实现了依赖解析的条件化切换。
3. 自动化运维层： 采用 Changesets (changesets-gitlab) 与 GitLab CI/CD 相结合，实现了从代码变更到包发布的端到端自动化版本管理。

为了确保该系统长期健康、高效地运行，建议遵循以下最佳实践清单：

• 坚持 Changeset 流程： 对于所有需要记录在更新日志中的代码变更，开发者都必须在提交的合并请求中包含一个 changeset 文件。
• 遵循两阶段提交： 对子模块的任何修改，都必须严格执行先在子模块内推送、再在父仓库更新引用的两步操作。
• 严肃对待发布 MR： 定期审查由 CI 自动创建的“发布合并请求”，将其视为一个重要的发布关口。
• 规范化新项目引入： 添加新的子项目时，确保已正确更新 .gitmodules 和 pnpm-workspace.yaml 文件，并配置好其 package.json。
• 保障 CI/CD 安全： 妥善保管 GITLAB_TOKEN 等 CI/CD 变量，实施最小权限原则，并定期轮换令牌。
• 持续完善文档： 随着团队和项目的发展，不断更新超级项目根目录的 README.md，确保新成员能够快速上手。

通过实施这一架构，您的团队将能够在一个统一的工程体系下，同时享受到 Monorepo 带来的开发协同效率和 Multi-Repo 带来的独立部署与治理能力，从而在应对复杂项目挑战时获得显著的竞争优势。