基础 15 · 读懂 monorepo

一个仓库里放多个互相依赖的包，一次提交，一起改，一起发版。

「mono」是「单一」，「repo」是「仓库」。所以 monorepo = 单体仓库：所有代码住在一个仓库里，而不是拆成四个仓库。

不是为了赶时髦，是因为你的业务要求这四块必须同时改：

你根目录的 workspaces 声明了两个通配符：

"workspaces": ["packages/*", "apps/*"]

就一行，但含义很明确：所有子目录我都收，packages/* 归一类，apps/* 归另一类。分法不是随便定的，是按「有没有自己的启动方式」来分。

你代码里写 import { workshopBOM } from '@delimao/engine'，Node 凭什么知道去磁盘上哪个文件？靠三样东西配合：

为什么依赖写 "*" 而不是具体版本号

// apps/server/package.json
"dependencies": {
  "@delimao/db": "*",← 用的是本地的 db 包
  "@delimao/engine": "*",    ← 用的是本地的 engine 包
  "express": "^4.21.2",      ← 这才是从网上装的
  "@trpc/server": "^11.0.0"
}

"*" 的意思是「任意版本都行，我要的就是我本地这个」。因为这些包不会发布到 npm（private: true），npm 装依赖时看到 @delimao/db: "*"，会直接在本仓库里找到这个包，做个软链（快捷方式）指过去——而不是去网上下载。

-w @delimao/engine 就是「在 engine 这个包里执行命令」。它等价于你先 cd 进那个包目录，再执行，只是不用真的切目录。

"scripts": {
  "dev:server": "npm run dev -w @delimao/server",
  "engine:test": "npm run test -w @delimao/engine",
  "db:migrate": "npm run db:migrate -w @delimao/db"
}

所以下面这两条命令做的事完全一样：

# 写法一：从根目录用 -w（推荐，你项目就是这么写的）
npm run dev:server -w @delimao/server
# 内部实际发生：去 apps/server/ 里执行它的 dev 脚本 = tsx watch src/index.ts

# 写法二：手动切目录
cd apps/server && npm run dev

这 8 条全部来自你项目真实的根 package.json，不是编的：

packages/ 里的东西没有独立启动方式。把 server 放进去，等于宣布「这个库不能启动」——虽然它其实能。判断方法很简单：能不能敲一条命令把它跑起来对外服务？能→ apps，不能 → packages。

这是你项目刻意避开的雷。packages/engine/package.json 里一个 dependencies 都没有，只有 devDependencies（typescript、tsx）。这不是省事，是自检：只要 engine 里 import 了 express 或 drizzle，node:assert 之外的东西就会被拉进来，engine:test 立刻变慢甚至跑不起来。你的纯包优势是靠「不 import」守住的。

A 依赖 B，B 又依赖 A。运行时表现为其中一个是 undefined，而且报错位置经常离真正的原因很远。你项目里 server → engine 是对的，engine → server 绝对不行。发现方法：npx madge --circular apps/server/src。

你这里 packages/engine 目录 ↔ @delimao/engine 包名，apps/web 目录 ↔ @delimao/web 包名。npm 认的是 package.json 里的 name，不是目录名。所以 -w 后面必须写包名（-w @delimao/engine），不能写目录名（-w packages/engine）。

npm workspaces 要在根目录装。你在 apps/web/ 里敲 npm install，装出来的node_modules 结构和根目录装的不一样，子包里就可能报「Cannot find module 'vite'」这类莫名其妙的错。正确做法：永远回根目录装、永远用根脚本跑。

• ✓我能说出 delimao-system 是 npm workspaces，workspaces: ["packages/*", "apps/*"]
• ✓我能说出四个包的名字和职责（server / web / db / engine）
• ✓我能用「有没有独立启动方式」区分 apps/ 和 packages/
• ✓我能画出 web → tRPC client → server → db → engine 的数据流
• ✓我知道 engine 不能依赖 server，也说过纯 TS 无框架依赖换来了单测能力
• ✓我讲得出 workspaces + name + exports 三者怎么配合解析 @delimao/engine
• ✓我知道自家包写 "*"、第三方包写 ^版本号，并知道为什么
• ✓我知道 -w 后面跟的是包名不是目录名
• ✓8 条命令我都能解释，尤其分清 db:generate（生成文件）和 db:migrate（写进库）