深入 · 读懂 monorepo

一句话：它在你 node_modules 里放了一堆「快捷方式」，让所有包互相都能直接引用。这些快捷方式叫软链（symlink，符号链接）。

软链后的目录长这样

delimao-system/
├─ package.json                ← 声明 "workspaces": ["packages/*", "apps/*"]
├─ node_modules/
│  ├─ @delimao/← 🔑 关键目录
│  │  ├─ db-> ../packages/db        ← 软链，不是真文件
│  │  ├─ engine  -> ../packages/engine
│  │  ├─ server -> ../apps/server
│  │  └─ web    -> ../apps/web
│  ├─ express/                    ← 第三方包是真实文件
│  ├─ drizzle-orm/
│  └─ ...
├─ packages/
│  ├─ db/
│  └─ engine/
└─ apps/
   ├─ server/
   └─ web/

那 4 条 -> 就是软链。@delimao/engine 不是一个真的文件夹，它是「packages/engine 的另一个名字」。

软链 vs 复制：差在哪

片段 A · 根 package.json（delimao-system/package.json）

{
  "name": "delimao-system",         // 仓库自己的名字
  "version": "0.1.0",
  "private": true,                  // ⛔ 私有包：永远不会被误发布到 npm 上去
  "description": "德莉玛淋浴房产供销一体化系统（路线B 生产级重构）",

  "workspaces": [// 🔑 整篇的地基：告诉 npm「下面这些目录里的包都算我的」
    "packages/*",                    // 递归匹配 packages 下所有一级子目录
    "apps/*"                         // 同理，apps 下所有一级子目录
  ],

  "scripts": {
    "build": "npm run build -w @delimao/engine && npm run build -w @delimao/db && npm run build -w @delimao/server",
    //      ↑ -w 就是「在 engine 里跑 build」，&& 串行
    //        顺序不可换：engine 和 db 都是 server 的依赖，必须先出 dist

    "dev:server": "npm run dev -w @delimao/server",   // → tsx watch src/index.ts
    "dev:web":    "npm run dev -w @delimao/web",      // → vite
    "engine:test":"npm run test -w @delimao/engine",  // → tsx test/run.ts
    "db:generate":"npm run db:generate -w @delimao/db",// → drizzle-kit generate
    "db:migrate": "npm run db:migrate -w @delimao/db",  // → tsx src/migrate.ts
    "db:seed":    "npm run db:seed -w @delimao/db",     // → tsx src/seed.ts
    "typecheck":  "npm run typecheck --workspaces --if-present"
    //      ↑ --workspaces = 对所有包各跑一次
    //        --if-present = 没有这个脚本的包直接跳过而不是报错
    //        （web 用 tsc -b，也有 typecheck，所以四个包都会跑）
  },

  "devDependencies": {
    "typescript": "^5.6.3"          // 只在根装一份 TS，各包共用
  }
}

片段 B · packages/engine/package.json（最值得看的一个）

{
  "name": "@delimao/engine",// 🔑 包名 ≠ 目录名。代码里 import '@delimao/engine' 认的是这一行
  "version": "0.1.0",
  "private": true,                  // 内部包，不发 npm
  "type": "module",// ⭐ 声明「本包用 ESM 语法」

  "main": "./dist/index.js",// ⭐ 入口：给运行时用的 JS
  "types": "./dist/index.d.ts",      // ⭐ 入口：给TypeScript 看的类型声明

  "exports": {// ⭐ 白名单：只开了根这一个入口
    ".": {// "." 代表「从包的根进」
      "types": "./dist/index.d.ts",   //   TypeScript 拿类型走这里
      "import": "./dist/index.js"     //   运行时 import 走这里
    }
  },

  "scripts": {
    "build": "tsc -p tsconfig.json",               // 编译出 dist/
    "typecheck": "tsc -p tsconfig.json --noEmit",  // 只检查不产出，CI 用
    "test": "tsx test/run.ts"// ⭐ 不依赖数据库、不依赖服务器
  },

  "devDependencies": {                // ⚠️ 注意：没有 dependencies
    "tsx": "^4.19.2",                 // 只有开发期的工具
    "typescript": "^5.6.3"
  }
}

片段 C · apps/web/package.json（前端怎么引后端类型）

{
  "name": "@delimao/web",
  "private": true,
  "type": "module",

  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",   // 先类型检查，再打包
    "preview": "vite preview",              // 本地预览生产产物
    "typecheck": "tsc -b --noEmit"
  },

  "dependencies": {
    "@delimao/engine": "*",// ⭐ 自家包：写 "*"，走本地软链
    "@trpc/client": "^11.0.0",// 第三方：写 ^版本，走网络
    "@trpc/react-query": "^11.0.0",
    "@tanstack/react-query": "^5.62.11",
    "react": "^19.0.0",// ⭐ React 19
    "react-dom": "^19.0.0",
    "react-router-dom": "^7.1.1",
    "clsx": "^2.1.1",
    "tailwind-merge": "^2.6.0",
    "lucide-react": "^0.468.0"
  },

  "devDependencies": {
    "@delimao/server": "*",// ⭐ 前端居然依赖后端包！
    "@trpc/server": "^11.0.0",        // 只为了拿 AppRouter 这个类型
    "@tailwindcss/vite": "^4.0.0",// ⭐ Tailwind 4：Vite 插件形态
    "tailwindcss": "^4.0.0",
    "@vitejs/plugin-react": "^4.3.4",
    "vite": "^6.0.5",
    "@types/react": "^19.0.2",
    "typescript": "^5.6.3"
  }
}

片段 D · packages/db/package.json（数据层）

{
  "name": "@delimao/db",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },

  "scripts": {
    "db:generate": "drizzle-kit generate",  // 只生成 SQL 迁移文件，不碰数据库
    "db:push": "drizzle-kit push",// 直接把结构推到库（开发期省事）
    "db:migrate": "tsx src/migrate.ts",     // 执行已生成的迁移
    "db:seed":    "tsx src/seed.ts"         // 灌主数据 / 种子数据
  },

  "dependencies": {
    "@libsql/client": "^0.14.0",// ⭐ libSQL 客户端
    "drizzle-orm": "^0.38.4",     // ⭐ drizzle 0.38
    "bcryptjs": "^2.4.3"          // 密码哈希（seed 里建用户用）
  },

  "devDependencies": {
    "drizzle-kit": "^0.30.2",// ⭐ generate/push 用的命令行工具
    "tsx": "^4.19.2",
    "typescript": "^5.6.3"
  }
}

大白话：exports 是包自己画的「对外开放的目录清单」。清单上没写的路径，import 直接报错——哪怕那个文件真实存在。

你 engine 的 exports 只开了 "." 一个入口，所以这行能跑通：

import { workshopBOM } from '@delimao/engine';        // ✅ 走"." 入口

而这行会直接失败，尽管 packages/engine/src/quote.ts 明明存在：

import { quoteModel } from '@delimao/engine/quote';  // ❌ 没在 exports 里声明

报错文案长这样（你以后见到就知道是 exports 的锅）：

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]:
Package subpath './quote' is not defined by "exports"
in file .../packages/engine/package.json
Subpath 说明：这里的 subpath 就是你写的那个「/quote」部分。

// packages/engine/src/index.ts —— 把所有内部模块统一从根导出
export * from './types.js';
export * from './parseModel.js';
export * from './masterData.js';
export * from './skuMaster.js';
export * from './workshopBOM.js';
export * from './validateBOM.js';
export * from './glassDwg.js';
export * from './quote.js';
export * from './mergeConfig.js';

所以不管 quote.ts 在 src/ 里还是在 src/lib/ 下，对外永远只有 @delimao/engine 这一个口。内部随便重构，外部零感知。

"exports": {
  ".": {// 根入口：类型 + 运行时
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js"
  },
  "./quote: {// ⭐ 新开的子路径
    "types": "./dist/quote.d.ts",   // 给 TS 看
    "import": "./dist/quote.js"     // 给运行时 import 用
  },
  "./package.json": "./package.json"// 常开的一个特例：有些工具要读包元信息
}

循环依赖 = A 要 B 的东西，同时 B 也要 A 的东西。大白话：A 找 B 要东西的时候，B 正在初始化、A 又回头找 A要东西——这时候谁都没准备好，你拿到的就是 undefined。

# 找出循环依赖（不用装成依赖，直接 npx 跑）
npx madge --circular apps/server/src
npx madge --circular packages/db/src
npx madge --circular apps/web/src

# 输出示例（有问题时）：
✖ Found 3 circular dependencies!
1) router.ts → engineService.ts → router.ts
2) schema.ts → client.ts → schema.ts

# 顺带看依赖图（想搞清谁依赖谁时用）
npx madge --image graph apps/server/src     # 生成 svg 图
npx madge --depends quote.ts packages/engine/src   # 反查：谁依赖了 quote.ts

大白话：后端把「我有哪些接口、每个接口要什么参数、返回什么」写成一份 TypeScript 类型，导出给前端。前端拿到这份类型，就等于拿到了接口清单——后端一改，前端立刻编译报错。这就是「类型即契约」。

后端：定义并导出 AppRouter

// apps/server/src/routers/index.ts —— 汇总所有 router
import { router } from '../trpc.js';
import { healthRouter } from './health.js';
import { authRouter } from './auth.js';
import { productRouter } from './product.js';
import { engineRouter } from './engine.js';

export const appRouter = router({
  health:  healthRouter,
  auth:   authRouter,
  product: productRouter,
  engine:  engineRouter,
});

export type AppRouter = typeof appRouter;   // ⭐⭐⭐ 就这一行是全部魔法所在

typeof appRouter 的意思是「把这个 router 的类型原样抠出来」。于是 AppRouter 这个类型里，精确记录了每一个接口的名字、参数校验规则、返回类型。

前端：拿这个类型直接推导

// apps/web/src/trpc.ts —— 客户端，类型是从后端 import 过来的
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@delimao/server';// ⭐ 只引类型，不引实现

export const trpc = createTRPCReact();  // ⭐ 把类型灌进去

const TOKEN_KEY = 'delimao_token';

export function getToken(): string | null {
  return localStorage.getItem(TOKEN_KEY);
}
export function setToken(token: string | null) {
  if (token) localStorage.setItem(TOKEN_KEY, token);
  else localStorage.removeItem(TOKEN_KEY);
}

export const trpcClient = trpc.createClient({
  links: [
    httpBatchLink({
      url: '/trpc',// ⭐ 所有 tRPC 请求都走这一个地址
      headers() {// ⭐ 身份凭证：JWT 走 Authorization 头
        const t = getToken();
        return t? { authorization: `Bearer ${t}` } : {};
      },
    }),
  ],
});

因为 createTRPCReact<AppRouter>() 拿到了 AppRouter，TypeScript 就能推导出 trpc.engine.xxx、trpc.product.xxx 每一个方法的名字和参数类型。你在页面里写 trpc.engine.quote.useQuery(...) 时，编辑器能自动补全、参数写错立刻飘红。

联动效果：改后端，前端立刻炸给你看

先给结论：你的项目里，四个包全部 private: true，一个都不需要发版。所以上面那些「发版流程」对你来说不适用——这是 monorepo 内部包最省事的地方。

那版本号什么时候需要动

按「对外可见性」分三种情况：

npm workspaces 必须在根目录装。你在 apps/web/ 里单独 npm install，会在子目录里生成一个独立的 node_modules，软链结构就断了，之后 workspace:* 式的引用和 -w 全都不对。规矩：永远在根目录 install，永远用根脚本跑。出问题时第一反应就是「是不是有人在子目录里装过东西」。