git子模块+workspaces组合：多仓库协同开发实战指南

先说个场景，你大概率遇过：公司项目从单仓库拆成多个独立仓库之后，公共代码只能靠复制粘贴，每次改个基础库的bug，得跑遍所有下游项目手动同步；反过来，如果死守单仓库，团队一多、权限一拆，又寸步难行。git子模块和package.json工作区这两个东西，分别解决的是“子仓库版本追踪”和“本地多包依赖管理”的问题，但单独用哪一个都不够顺手。把它们配合起来做多项目开发，是我在实际项目中验证过好几轮的做法，这篇文章把完整思路、操作流程和踩坑记录都写出来。

我是从一次真实的项目拆分开始接触这套组合的：当时系统里有三个前台应用、两个后台服务、一个公共SDK，六个仓库之间依赖关系复杂到爆炸。用git submodule管源码版本，用npm workspaces管本地依赖，拆完之后的体验完全不输monorepo，而且保留了多仓库的权限边界。如果你也在纠结多项目怎么组织，或者已经被子模块坑到怀疑人生，这篇文章应该能给你一套能直接落地的方案。

1. 拆仓库和聚仓库的博弈：为什么单靠一种方式都不够

1.1 git子模块的定位与局限

git submodule的本职工作，是在一个主仓库里以“提交引用”的方式挂载另一个独立仓库。它解决的核心痛点是跨仓库的版本锚定：公共SDK发布了v1.2.3，主项目能精确锁定到那个commit，而不是靠“记得上次拷贝的版本”这种原始方式。

但子模块天生有门槛和性格问题。首先是理解成本，刚接触的人会被git submodule update --init --recursive这套命令绕晕，clone不带--recursive就会得到一堆空目录。其次，它管理的是“源码引用”，不是“依赖产物”——如果公共SDK需要先构建才能被主项目使用，子模块拉下来的原始代码并不能直接被引用，你得自己去跑构建、处理产物路径。最头疼的是子模块的commit指针漂移，主仓库记录的是“子模块当时指向哪个commit”，但子模块本身是独立的git仓库，稍不注意就在主仓库里留下修改痕迹，提交时出现意想不到的dirty状态。

我之前见过一个团队用子模块管理公共组件库，结果各种“明明改了却不生效”“拉下来是旧的”“子模块更新把同事的提交冲掉”的现场。不是工具不能用，而是他们只用了子模块去干“依赖管理”的活，这超出了它擅长的范围。

1.2 package.json工作区解决的问题

npm/yarn/pnpm的workspaces（工作区）功能，解决的是另一个维度的问题：本地多个包之间的链接与依赖统一管理。

在workspaces出现之前，如果想在本地同时开发SDK和主项目，最常见的方式是npm link。它好用但脆，经常出现链接错乱、版本对不上的问题，多项目之间还得反复执行。workspaces通过根目录的package.json统一声明下面有哪些子包，安装依赖时自动把它们链接到node_modules里。开发公共SDK时，改完代码，主项目里立刻能用（需要watch或rebuild），不再需要手动link。

但workspaces的前提是“这些项目在同一个根目录下，且被同一套package.json体系管理”。这正好和git submodule形成互补：子模块解决“多仓库如何聚合到主仓库”的问题，workspaces解决“聚合之后，多个包如何共享依赖、互相引用”的问题。两个工具各有边界，组合起来的覆盖范围才完整。

1.3 组合使用的适用场景

这种组合不是银弹，但在以下场景里非常合适：

• 有多个互相依赖但需要独立发版的仓库。比如核心库、业务组件库、应用层，核心库发版节奏慢、业务组件库次之、应用层最快。
• 团队需要不同仓库拥有独立权限。比如第三方外包团队只允许访问某个子模块仓库，不能看主仓库其他业务代码。
• 本地开发时希望跨仓库实时联调。不用每次改公共库都先发布，本地就能验证。
• CI/CD仍希望按仓库分别构建。主仓库可以拉取子模块的最新代码统一打包，也可以让子模块单独构建发布。

如果你所有项目都长在一个仓库里、权限上也不敏感，那直接monorepo更省事，不需要这套组合。反过来，如果各仓库之间完全独立、没有源码级别的依赖关系，那也不需要子模块，普通npm包引入就够了。这套组合的适用区，恰恰是在“既要有仓库边界，又要有源码协同”的中间地带。

2. 动手前的选型准备：环境、工作区管理器与仓库规划

2.1 环境检查

做这套方案前，先确认本机环境。git版本最好在2.20以上，早期的submodule命令行为和体验有不少差异，新版对--init、克隆策略都有优化。Node.js版本取决于你用哪个工作区管理器：

• npm：Node自带，但npm 7才开始比较稳定地支持workspaces，建议Node 16以上。
• yarn：yarn 1.x需要额外安装，支持workspaces但性能一般；yarn 2+（berry）的workspaces体验更好，但注意和Node版本的兼容。
• pnpm：对workspaces的支持最完整，但需要单独安装，且它的node_modules结构和npm不同，团队需要统一。

我在生产环境里用的是**npm 8 + git 2.30+**的组合，原因很简单：npm是新装Node自带的，不需要额外统一团队工具链。如果你团队统一装了pnpm或yarn，那继续用就行，核心逻辑一致。

2.2 工作区管理器的取舍对比

很多团队卡在“到底用npm、yarn还是pnpm”这一步，我先说结论，再展开对比。

安装速度其实在中小规模项目里感知差别不大，真正常影响的是依赖冲突的解决体验。npm在workspaces里没有完全做到隔离，两个子项目依赖了同一个包的不同版本，它会尝试扁平化，有时候会“帮倒忙”引起奇怪的类型冲突。pnpm用硬链接+符号链接的结构，每个包只存一份，文件级别严格隔离，能从根本上避免这类冲突。

不过有一点要提前警告：pnpm的严格node_modules结构会让很多老工具报错，比如某些旧版storybook、electron工具链、依赖“直接require一个未声明依赖的包”的项目。如果团队负责的项目都比较现代，用pnpm很爽；如果维护的是老项目，从npm迁移到pnpm会遇到不少适配工作。

2.3 仓库结构规划

在动手使用脚本前，先把仓库结构设计好，这是整个方案里最容易返工的部分。我强烈建议从一开始就按“主仓-子仓”关系建立目录规划。

我们当时的产品结构是仓库主仓（一个总的应用，包含管理后台和对外接口）、一个公共SDK仓、一个内部组件库仓，外加几个应用插件仓。规划后主仓库内部目录长这样：

code复制my-main-app/
├── .git/
├── .gitmodules
├── package.json
├── packages/
│   ├── core-sdk/         # git submodule，指向 core-sdk 仓库
│   ├── ui-components/    # git submodule，指向 ui-components 仓库
│   └── plugins/
│       ├── plugin-a/     # git submodule，独立的插件仓库
│       └── plugin-b/     # git submodule
├── apps/
│   ├── admin/            # 业务代码，主仓直接维护
│   └── server/           # 业务代码
└── node_modules/

设计原则有几条：

• 子模块统一收在一个目录下（如packages/），不要东一个西一个，否则日后清理麻烦。
• 子模块的包名要使用npm scope，比如@company/core-sdk、@company/ui-components，全局唯一，后面workspaces的引用就不会混淆。
• 主业务代码和子模块代码分区，apps/放主仓自己维护的业务应用，packages/放子模块。这样.gitmodules、目录权限、CI配置都一目了然。

3. git子模块落地实操：从挂载到日常迭代

3.1 在仓库里添加子模块

假设你已经有主仓库，现在要把公共SDK仓库加进来。基础命令：

bash复制# 进入主仓库根目录
git submodule add git@github.com:company/core-sdk.git packages/core-sdk

这条命令做了三件事：

1. 克隆core-sdk仓库到packages/core-sdk。
2. 在.gitmodules文件中记录子模块路径和URL。
3. 在git索引中记录这个“指向某个commit”的特殊条目（gitlink）。

此时检查git status，会看到新增了.gitmodules和packages/core-sdk（160000类型）。注意，160000是gitlink的模式，不是普通目录，git diff时也会显示得和普通文件差异很像，但本质完全不同。

提示：子模块URL建议在网络层面统一使用SSH、或统一使用HTTP+凭据推送的方式。混用会导致团队成员换个网络环境就clone失败或push被拒。

3.2 新成员克隆主仓库

最常用的是带--recursive参数一键克隆：

bash复制git clone --recursive git@github.com:company/my-main-app.git

它会递归初始化并更新所有子模块。也可以用分开的命令：

bash复制git clone git@github.com:company/my-main-app.git
cd my-main-app
git submodule update --init --recursive

第一次跑的阶段很容易遇到子模块仓库权限问题。如果主仓库有权限，但某个子模块仓库不在你的账号授权范围内，clone会卡在那里报Permission denied。这不是bug，是子模块各自的仓库权限独立，团队需要提前给每个相关人员配置对应子模块仓库的读权限。

3.3 日常迭代中的子模块更新与提交

项目开始运行后，日常操作量最大的两个动作是拉取子模块最新代码和推送子模块修改。

拉取子模块更新（所有子模块都更新到各自远程仓库最新commit）：

bash复制# 进入主仓库
git submodule update --remote

这里有个关键概念要理解：--remote会把子模块的commit指针更新到远程仓库的某个分支（默认是HEAD所在分支，但建议显式在.gitmodules里配branch），你需要在主仓库里git add packages/core-sdk并提交，才算把主仓库的引用锁到新位置。如果不做add，主仓库记录的还是旧commit。

如果只是某个子模块要更新：

bash复制cd packages/core-sdk
git pull origin main
cd ../..
git add packages/core-sdk
git commit -m "chore: update core-sdk to latest"

推送子模块修改（改的是子模块内部代码）：

bash复制cd packages/core-sdk
# 正常修改代码、提交
git add .
git commit -m "fix: xxx"
git push origin main
# 回到主仓库，更新指针并提交
cd ../..
git add packages/core-sdk
git commit -m "chore: bump core-sdk"
git push

整个过程要养成一个习惯：每个子模块都单独维护自己的分支，主仓库只负责锁定commit，不直接在主仓库里改子模块代码。这样版本轨迹清晰，回溯也容易。

3.4 子模块的分支管理

子模块的HEAD默认是“游离的”（detached HEAD），你clone下来后看到的提交指针由主仓库决定，不是最新分支。所以要在子模块里开发时，必须先切到自己的业务分支：

bash复制cd packages/core-sdk
git checkout main  # 或 feature/xxx
git pull

这里要提醒一个非常经典的坑：切到子模块分支前，先确认子模块状态是干净的。如果主仓库刚更新了子模块的commit指针，子模块本地又有未提交修改，执行git checkout main会提示Your local changes would be overwritten。处理办法是先git stash或提交，再切分支。

建议团队约定一个命名规则：主仓库和子模块使用相同的分支名。比如开发feature/payment，主仓库在feature/payment分支上同时拉取子模块的feature/payment。虽然这一点不是必须的（子模块的branch可以在.gitmodules里各自配置），但同名分支能让整个仓库体系的大脑负担小很多。

3.5 子模块报错速查表

做这套方案以来，我收集了几个最高频的报错，统一列一下。很多新人在这一步会以为工具坏了，其实是行为没理解透。

这些坑不是工具设计有问题，而是子模块的工作概念（主仓只记指针，子模块自己是独立仓库）和普通git文件操作差别太大。理解了指针和独立仓库这两条，大部分问题都能自己推出来。

4. package.json工作区搭建：依赖共享与本地联调

4.1 根package.json配置

在子模块规划完成后，主仓库根目录下的package.json增加workspaces字段：

json复制{
  "name": "my-main-app",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "dev": "concurrently \"npm run dev:server\" \"npm run dev:admin\"",
    "dev:admin": "npm run dev --workspace=@company/admin",
    "dev:server": "npm run dev --workspace=@company/server",
    "build": "npm run build --workspaces"
  }
}

字段含义：

• "packages/*"和"apps/*"是glob模式，匹配到所有子目录下的独立package.json。
• 每个匹配到的目录都会被视为一个workspace包。
• npm run <script> --workspace=<包名>可以针对单个包执行脚本；--workspaces是全部包执行。

注意：workspace里的包名必须全局唯一。如果packages/core-sdk/package.json里的name是core-sdk，恰好另一个app也叫core-sdk，npm不会警告，但依赖解析时会出现极其诡异的行为。统一用scope是标准解法。

4.2 依赖安装与自动链接

配置好workspaces后，不再需要分别进子模块目录执行npm install。在主仓库根目录执行一次：

bash复制npm install

npm会扫描所有workspace包的package.json，把依赖统一解析、安装到根目录的node_modules里，同时为workspace包之间建立符号链接。比如packages/core-sdk的package.json里"name": "@company/core-sdk"，主仓库的apps/server里如果声明了"@company/core-sdk": "^1.0.0"，安装完成后，apps/server/node_modules/@company/core-sdk会是一个符号链接，直接指向packages/core-sdk目录。

这意味着本地开发时，改动packages/core-sdk的源码，无需任何额外操作（只要代码支持热更新或自行构建了编译产物）就能在apps/server里实时生效。这就是取代npm link的机制。

4.3 依赖版本冲突的处理策略

workspaces虽然统一了安装，但版本冲突还是要处理好。常见的情况：两个子包分别依赖了lodash@4.x和lodash@3.x。npm会尽量扁平化，把其中一个版本提升到根目录，另一个嵌套进对应包目录。这在大多数时候没问题，但有些包（如原生模块、带类型定义的包）会出现运行期混乱。

处理原则从强到弱：

1. 统一版本。尽量让所有子包对同一个依赖使用相同major版本，这是长期最省心的。
2. 使用overrides字段。npm支持在根package.json里强制覆盖某个依赖的版本。比如：

json复制{
  "overrides": {
    "lodash": "$lodash"
  }
}

3. 使用pnpm的hook级别隔离。如果必须在不同package里用不同版本，pnpm的结构会比你想象中干净得多，因为它是符号链接式隔离的，不同版本装在不同地方，不会“串门”。

我之前遇到过一个典型的类型冲突：@company/ui-components用了@types/react@18，主应用的admin项目用了@types/react@19，结果TS编译时类型互相污染。最后就是靠overrides统一成18解决的。这类问题在workspaces模式下会比单仓库更早暴露，反而是好事。

4.4 脚本优化与复杂命令封装

workspaces模式下，脚本管理不要靠脑子记，建议把根package.json的scripts当做一个“统一入口”。

比如主仓里同时启动server和admin的本地开发，根目录：

bash复制npm run dev

对应的脚本内部可以使用npm-run-all或concurrently并行执行：

json复制{
  "scripts": {
    "dev": "concurrently -n server,admin -c blue,green \"npm run dev --workspace=@company/server\" \"npm run dev --workspace=@company/admin\"",
    "build": "npm run build --workspaces --if-present"
  }
}

--if-present很实用，有些包没有build脚本，加上它就不会报错。构建顺序有讲究的话，需要显式控制：先构建依赖，再构建应用。

json复制{
  "build": "npm run build --workspace=@company/core-sdk && npm run build --workspace=@company/ui-components && npm run build --workspaces --if-present"
}

如果不控制顺序，应用模块可能在SDK产物还没生成时就集成失败。尤其子模块里如果是TS源码需要先编译成JS，顺序控制是必需项。

4.5 子模块产物与会话边界

这里有一个关键点要特别说明：workspaces链接的是“子模块目录里的源码/产物”，不是git层面引用的那个commit。也就是说，即使主仓库锁定子模块到了旧版本，但只要子模块本地工作区还是新代码，workspace链接到的就是本地新代码。

这是开发期最大的便利，也是发布期最大的风险。本地联调时，你要的是“本地最新代码实时生效”；发布时，CI环境里应该严格用主仓库锁定的版本构建，不能依赖本地未提交的修改。

所以建议：本地开发用workspaces享受实时联动，CI构建时单独跑一个脚本，先将子模块切到主仓锁定的commit（也就是git submodule update），然后再执行workspaces构建。这样发布的内容和本地开发是有清晰边界的。

5. 主仓库与子模块的协作模式：版本锚定与发布策略

5.1 什么时候该更新子模块指针

很多人刚上手时把子模块更新当成家常便饭，每次子模块一有新东西就拉。这会导致主仓库历史里一堆“bump submodule”的commit，回溯时非常恼人。

我的建议是，更新子模块指针遵循以下几个时机：

• 功能模块开发开始时：确认当前feature分支依赖的核心库版本。
• 子模块有紧急fix并需要集成时：单点更新，提交信息里写明原因。
• 发布前：统一确认所有子模块的版本，冻结后打release tag。

日常开发中，不希望子模块频繁漂移。因为每次更新都可能引入行为变化，影响正在开发的feature。尤其多人并行开发时，一个人跑了git submodule update --remote，直接改变了所有人本地子模块的commit，如果配合不当，会引发大量冲突。

5.2 主仓锁定与子模块单独发布的配合

子模块本身可以是独立发版的。比如@company/core-sdk维护自己的版本，发布到npm仓库。主仓做集成构建时，可以选择：

1. 用git submodule的commit引用，走源码集成；
2. 用npm的版本范围（如^1.2.0），走包管理器集成，不拉子模块源码。

这两种方式可以并存，但必须明确分工。我在项目里的约定是：

• 开发期：使用workspaces链接本地子模块源码，做快速迭代。
• CI打包：根据发布的tag，在CI里统一使用“git submodule update + workspace构建”，保证构建产物完全对应已提交的源码。
• 对外发布公共SDK时：SDK仓库自己走npm发布流程，主应用不一定实时跟进。

这套约定解决了一个典型矛盾：主应用需要SDK修复某个bug，但SDK还没有发布新npm包。开发期直接用本地源码修复并验证；等SDK发版后，主应用再升级npm依赖即可。

5.3 发布流程中的版本冻结

走到发布阶段，必须做“版本冻结”。我的操作方式是：

1. 在主干分支上，git submodule update，让所有子模块指向各自main分支的最新提交。
2. 测试通过后，git add .gitmodules packages/提交，打上发布tag，比如v2.3.0。
3. 发版后，如果线上需要hotfix，直接开hotfix分支，在hotfix分支上更新特定子模块的commit（比如只更新SDK，组件库不动），提交后测试并部署。

这里有一个重要原则：永远不要在主仓库的发布分支上忘记add子模块的指针变化。我见过不止一次：有人改了子模块代码，测试通过，但在主仓只提交了业务代码，忘了git add packages/core-sdk，结果发布时线上拿到的还是旧的子模块代码，线上环境完全复现不了测试环境。

规避办法也很简单：提交前用git status检查有没有modified: packages/xxx (new commits)类的变更，有就一并提交。CI里最好再配置一个“检查主仓和子模块是否一致”的环节，比如构建前强制git submodule update并检测工作区是否变脏。

5.4 多分支并行下的子模块同步

多分支并行时，子模块的问题会放大。假设主仓库同时在开发release/2.0和feature/login-redesign两个分支，各自依赖不同版本的core-sdk。branch切换时，子模块的commit指针也会跟着主仓的记录切换，如果子模块本地有未提交修改，会直接报错。

我的习惯是，在切主仓库分支前，先确保所有子模块目录是干净状态。可以用一次命令检查所有子模块状态：

bash复制git submodule foreach 'git status --short'

如果输出为空，说明全部干净，可以安全切换。如果有修改，先stash或提交。在分支管理严格的项目里，我给团队定的要求在切分支前必须执行这个命令，否则不准切。

6. 本地开发环境与调试：工作区联动实操

6.1 子模块与workspaces同时启用的开发体验

开发时最顺滑的体验是这样的：你打开两个窗口，一个在packages/core-sdk里改代码，另一个在apps/server里跑开发服务。

由于workspaces的软链，apps/server引用的@company/core-sdk就是本地源码目录。如果core-sdk是纯JS或者有watch模式（比如tsc --watch、vite build --watch），改动保存，服务自动热更新。这样一套开发流程下来，所有改动都是即时反馈的，不需要中间产物，不需要手动拷贝，不需要发布。

如果你的SDK是TS写的，建议在SDK的package.json里同时设置main指向编译后的产物、types指向编译后的d.ts，然后在SDK仓库内启动构建watch：

bash复制cd packages/core-sdk
npm run watch

主应用开发服务如果是基于webpack或vite的，通常会自动监听依赖目录的文件变化。如果遇到“改了源码但服务不刷新”的情况，大概率是因为构建工具默认只监听入口依赖的node_modules里被链接的包，需要额外配置：

• webpack：watchOptions.ignored: /node_modules/，但要确保被链接的包解析到的是真实目录而不是node_modules缓存。可以试着移除解析中的symlinks: false。
• vite：默认支持monorepo，但server.fs.allow需要包含上一级目录或整个workspace根目录。

6.2 多包并行开发时dev server的调优

多包并行开发时，最占资源的是每个包的watch模式。如果三个子模块都开watch，再加两个应用的dev server，笔记本风扇会疯狂。我的建议：

• 不是每次都要开启所有watch。只watch正在改的那个子模块。
• 用concurrently把必要服务统一管理，但不用把watch全部开起来。
• 如果子模块具备“懒构建”能力，比如在应用dev server请求时才编译，优先使用。像ESM+TS的包可以用tsx或tsup踩点编译，而不是全量watch。

6.3 npm workspace范围内的debug技巧

有些疑难杂症，比如某个子包里的代码没生效，排除法要分几步：

1. 确认workspaces链接是否存在。
2. 确认实际执行的代码路径。
3. 确认构建产物与源码的对应关系。

快速定位链接是否正确：

bash复制npm ls @company/core-sdk

它会在workspaces树里显示包的解析路径。如果路径是my-main-app/packages/core-sdk，说明链接正确；如果是node_modules/@company/core-sdk（真实安装的npm包），说明workspace链接没生效或npm把链接替换成了实际安装。

有一个我踩过两次的坑：子模块的package.json里name字段和主仓库依赖里的包名不一致。看起来是小问题，但npm不报任何错，只是默默从npm源安装一个同名但完全不同内容的包。排查时反而找不到原因。解决方式：命名统一，用scope前缀，并且保持主仓库dependencies的版本范围和子模块自己发版的版本一致。

6.4 前端项目里处理静态资源与public目录

子模块如果是前端组件库，组件里会引用静态资源（图片、字体等）。在workspaces链接下，主应用dev server处理这些静态资源的路径往往不同。常见表现：子模块代码里import logo from './logo.png'能工作，但如果主应用运行时去拼/static/绝对路径，就会404。

处理原则：子模块组件库不要写基于自身目录的绝对引用，尽量让静态资源由主应用统一代理或转发。如果组件库确实需要内置资源，推荐把资源打成base64，或通过CSS引用相对地址并保证构建工具能将其当作依赖处理。这块设计不好，会让整个workspaces联动体验大打折扣。

7. 常见坑位清单：这几种报错我全都现场踩过

7.1 git子模块相关

1. git submodule update --remote和主仓库指针不同步

执行--remote后，子模块的commit已经变了，但主仓库还记录旧指针。你直接push主仓库，业务代码提交了，但子模块那部分没提交，CI会拿到旧的。规避：更新--remote后，必须立刻git add packages/子模块目录并提交。

2. 子模块游离HEAD下提交后找不到commit

在子模块里处于detached HEAD状态，如果这时候commit，这个commit挂在无名分支上，切走就找不到了。解决：进入子模块后先git checkout <分支>，再改代码。如果你习惯在子模块里直接改，建议配一个pre-push钩子，在检测到HEAD处于游离时直接拒绝push。

3. 删除子模块是反人性操作

git rm packages/core-sdk只会删除gitlink条目，但本地目录还在，.gitmodules也不会自动清理。完整删除子模块需要三步：

bash复制# 第一步：移除索引中的子模块条目
git rm -r packages/core-sdk
# 第二步：编辑.gitmodules，删除对应条目
vim .gitmodules
# 第三步：清理子模块模块目录（根目录）
rm -rf .git/modules/packages/core-sdk

第三件事很多文档不提，但如果不做，以后重新添加同名子模块会有怪异冲突。

**4. **子模块目录被误提交了内部文件

子模块在git索引里是gitlink（160000），它内部的所有文件由子模块自己的git管理。但如果你在主仓库里执行git add packages/core-sdk/，git会提示这是一个gitlink，无法把内部文件加入主仓库。此时不要强行加，应该进入子模块操作。这个提示对很多新手是个“错误”，其实是对的设计。

7.2 package.json工作区相关

1. npm install后workspace包没有链接

检查：

• 根目录package.json是否包含workspaces字段。
• 子包目录下是否有合法的package.json。
• 是否之前单独在各个子目录下执行过npm install，生成的node_modules干扰了链接。

标准化操作：删除根目录node_modules和各workspace里的node_modules，重新在根目录安装。

bash复制rm -rf node_modules packages/*/node_modules apps/*/node_modules
npm install

2. 使用pnpm时overrides字段报错

你可能会在网络上看到类似这样的一段警告：

code复制pnpm dev [warn] the "pnpm" field in package.json is no longer read by pnpm.
the following keys were ignored: "pnpm.overrides".

这是新版pnpm在迁移配置位置时的行为：以前在package.json里写pnpm.overrides，现在需要把这类配置挪到pnpm-workspace.yaml。迁移后的内容类似：

yaml复制packages:
  - "packages/*"
  - "apps/*"
overrides:
  lodash: "4.17.21"

如果团队还是习惯在package.json里写pnpm配置，务必确认pnpm版本对应的配置文件位置，否则配置不会生效。这个警告本身不算报错，但一旦overrides没生效，依赖版本可能和预期不一致，埋坑很深。

3. 构建时找不到bin命令

workspaces模式下，每个workspace包自己的node_modules/.bin默认不会暴露到其他包里（除非配了nohoist或依赖提升策略）。如果某个包的devDependencies里装了eslint，但你想在根目录统一跑lint，可能会提示eslint: command not found。

解决有几种：

• 依赖提升到根目录：不推荐，不够明确。
• 在具体workspace包目录下运行npm run lint，脚本会从该包的node_modules/.bin里找命令。
• 在根package.json里把eslint提升为devDependencies。

如果希望workspace间共享某个cli工具，推荐第3种，同时注意版本统一。

7.3 子模块+workspaces组合的独有坑

1. 子模块目录初始为空导致workspaces安装失败

新的clone默认不会拉取子模块内容，packages/*里的目录是空的，此时根目录执行npm install，npm会尝试扫描空的子模块目录，可能报“No package.json found”或跳过。这不是致命错误，但一旦之后git submodule update --init拉取完目录，需要重新执行一次npm install，让workspaces正确链接到子包。

规范化的做法是：把子模块初始化纳入安装流程，或者写一个初始化脚本：

bash复制# 脚本：init.sh
git submodule update --init --recursive
npm install

2. 子模块分支和主仓库分支不同导致的版本错乱

主仓库切到release/2.0时，子模块按主仓库锁定的commit切换，这没问题。但如果你在子模块里手动改了分支到main，然后执行npm install，workspaces会链接到这个“本地main分支版本”，而不是主仓库锁定的版本。这种不一致极难排查：代码在本地运行正常，CI却不对。

应对方案：在本地开发环境，子模块的分支切换完全由主仓库的submodule机制管理，不要手工去改分支。如果确实需要改子模块分支，至少要在工作记录里标注清楚，并在发布前恢复。

3. 构建产物提交到子模块的冲突

子模块代码大多需要编译，有些人习惯把dist目录提交到子模块仓库（虽然通常不建议）。workspaces链接时，本地引用的是dist产物。如果子模块更新了dist，主应用自动生效；但如果主仓库锁定子模块commit时该commit的dist还旧呢？就会产生“本地链接是最新dist，CI锁定的commit里的dist是旧的”。

我的建议：子模块仓库一律不提交dist产物，主应用构建时从源码构建。这样就不会出现源码和产物不一致的问题。

8. 一套完整的工程化初始化脚本参考

这部分直接给一个可落地的最小工程脚手架，方便快速复现整套方案。假设公司域名是git.company.com，公共SDK仓库是core-sdk，主应用仓库是my-main-app。

创建主仓库并挂载子模块：

bash复制# 创建主仓库
mkdir my-main-app
cd my-main-app
git init

# 添加子模块
git submodule add git@git.company.com:platform/core-sdk.git packages/core-sdk
git submodule add git@git.company.com:platform/ui-components.git packages/ui-components

# 初始化package.json
npm init -y

修改根package.json，填入workspaces：

json复制{
  "name": "my-main-app",
  "private": true,
  "workspaces": ["packages/*", "apps/*"],
  "scripts": {
    "postinstall": "git submodule update --init --recursive",
    "dev": "concurrently -n server,admin -c blue,green \"npm run dev --workspace=@company/server\" \"npm run dev --workspace=@company/admin\"",
    "build": "npm run build --workspace=@company/core-sdk && npm run build --workspace=@company/ui-components && npm run build --workspaces --if-present"
  }
}

这里postinstall是为了保证npm install时如果子模块还没初始化，会自动拉取。但要注意：postinstall在CI环境里如果没有子模块权限会直接失败，所以CI环境通常单独跳过或保持环境变量。

创建目录结构：

bash复制mkdir apps server admin

各自初始化package.json，记得包名必须带scope：

json复制// apps/admin/package.json
{
  "name": "@company/admin",
  "version": "0.0.1",
  "dependencies": {
    "@company/core-sdk": "*",
    "@company/ui-components": "*"
  }
}

依赖版本直接写"*"在workspaces开发期可以，但如果要发版，应改成具体版本范围。开发期*的好处是link永远是最新本地代码，坏处是依赖树解析时不明确。我自己测试下来，开发阶段用"*"反而方便，发布前再统一替换为真实版本号。

子模块初始化并安装：

bash复制git submodule update --init --recursive
npm install

验证workspaces链接：

bash复制npm ls @company/core-sdk

输出中看到my-main-app/packages/core-sdk即可。然后执行总的开发启动命令，正常情况就能看到两个应用起来，子模块的改动会实时联动。

9. 最后的经验总结

这套方案我前前后后使用了两个多季度，最大的体会有三点。

第一，理解子模块和workspaces各自的边界比记住命令更重要。子模块管“仓库引用”，workspaces管“依赖链接”。两者是互补的，不要试图让其中一个干所有的活。很多团队觉得子模块难用，是因为硬拿它当包管理器用；反过来说，觉得workspaces效率低，是因为没有源码级别的跨仓库联动。

第二，仓库结构规划要在写第一行代码之前定死。我在项目里吃过规划不完整的亏：最初子模块目录分散在apps和libs下，后来统一迁到packages，迁移成本不算高，但要处理一堆历史commit里的子模块路径变更，CI配置也要同步改。定好目录结构后，团队约定写进README，后续新仓库直接照搬。

第三，CI环境必须严格复现锁定的版本。本地联调可以随意，发布构建必须保证和主仓锁定的一致。否则线上出了bug，排查方向都会被带偏。我的做法是在CI的构建脚本里，构建前强制执行一遍git submodule update，并检查git status是否变脏，一旦有未提交的指针变化直接fail掉构建。

如果你正在多项目协同的泥潭里挣扎，这套git子模块加package.json工作区的组合值得一试。不夸张地说，它让我从“复制粘贴公共代码然后到处同步”的噩梦里解脱了出来，也让团队协作边界清晰了很多。按上面的步骤搭一次，你会感受到多仓库开发原来也可以这么顺。