和 Turborepo / Nx 的關(guān)系

pnpm 只負(fù)責(zé)依賴安裝 + 按拓?fù)湫蚺?script；緩存、增量構(gòu)建、遠(yuǎn)程緩存等，可交給 Turborepo、Nx。通常做法是：pnpm 管 install 和 workspace 鏈接，Turbo/Nx 管 build / test 的調(diào)度與緩存，兩者一起用沒問題。

五、優(yōu)缺點(diǎn)一覽（夠直白版）+ 逐條詳解

5.1 優(yōu)點(diǎn)總覽

詳細(xì)說明：

• 省磁盤、安裝快：原理即第二節(jié)的 store + 硬鏈接；workspace 包不進(jìn) store，只做鏈接。典型收益是 monorepo 磁盤占用和 pnpm install 耗時明顯下降。
• 依賴干凈：嚴(yán)格依賴 + 單一 lockfile，少很多「刪了某包就掛」「本地有 CI 沒有」的玄學(xué)問題；注意若用了 public-hoist-pattern 等，要控制范圍，否則又引入隱性依賴。
• 本地聯(lián)調(diào)：改 packages/ui 立刻在 apps/web 里生效，無需 link；注意跑 dev 的終端要在根目錄或?qū)?yīng) app 目錄，且已執(zhí)行過根目錄的 pnpm install。
• monorepo 友好：pnpm -r、--filter 能力足，再配合 Turborepo/Nx 做任務(wù)編排、緩存，體驗(yàn)更好。
• 發(fā)布：按包發(fā)布、changesets 管理版本與 changelog，和現(xiàn)有 registry 流程兼容。

5.2 缺點(diǎn) / 注意點(diǎn)總覽

詳細(xì)說明：

• 和 npm 不完全兼容：
  有些 Webpack 插件、老版 Babel、個別 CLI 會直接去根 node_modules 找包，pnpm 默認(rèn)非扁平就可能找不到。處理辦法：

  • 用 node-linker=hoisted（.npmrc）切回類 npm 扁平結(jié)構(gòu)，會犧牲嚴(yán)格依賴；
  • 或只用 public-hoist-pattern 把有問題的包提升上來，盡量窄配。

• 學(xué)習(xí)與遷移成本：
  團(tuán)隊(duì)至少要會：workspace 概念、pnpm-workspace.yaml、workspace:* 協(xié)議、根目錄 pnpm install、--filter 與 -r 的用法。可以抽半小時過一遍本文 + 官方文檔，再在試點(diǎn)項(xiàng)目跑一遍。

• 舊工具兼容性：
  建議先小范圍試點(diǎn)，遇到具體工具再查 pnpm 兼容性 或社區(qū) issue；大多數(shù)現(xiàn)代前端工具已支持。

• 統(tǒng)一包管理：
  全倉庫只用 pnpm，禁止 npm install / yarn。用 packageManager 鎖版本，CI 里 corepack enable && pnpm install，避免有人用錯包管理器導(dǎo)致 lockfile 或鏈接關(guān)系錯亂。

適合：中大型前端項(xiàng)目、組件庫 + 多應(yīng)用、多包復(fù)用的 monorepo。

不大適合：單應(yīng)用、沒有多包復(fù)用需求的小項(xiàng)目；用 pnpm 單倉也能受益，但 workspace 收益有限。

六、應(yīng)用場景（什么時候上 workspace？）

下面按場景拆：誰用、解決啥問題、推薦結(jié)構(gòu)、關(guān)鍵配置、日常工作流。你對照自己項(xiàng)目，能直接套用或微調(diào)。

6.1 UI 組件庫 + 多個業(yè)務(wù)項(xiàng)目

場景：你們有一個業(yè)務(wù)組件庫，要同時支撐 2～3 個前端項(xiàng)目；組件庫頻繁迭代，需要在各項(xiàng)目里即時驗(yàn)證，而不是先發(fā) npm 再裝。

推薦結(jié)構(gòu)：

packages/
  ui/           # 組件庫
apps/
  web-admin/
  web-h5/
  web-docs/     # 組件文檔

web-admin、web-h5、web-docs 都依賴 @my/ui，用 workspace:*。

關(guān)鍵配置：

• pnpm-workspace.yaml：packages: ['packages/*', 'apps/*']。
• 各 app 的 package.json："@my/ui": "workspace:*"。
• 根 scripts：如 "dev:docs": "pnpm --filter web-docs run dev"，"build:ui": "pnpm --filter @my/ui run build"。

工作流：

改 packages/ui → 在 apps/web-docs 或任意 app 里直接看效果；要發(fā)版時用 changesets 給 @my/ui 打 version、寫 changelog、publish，各 app 再決定何時把 workspace:* 換成固定版本（若你們發(fā) npm 的話）。

6.2 多應(yīng)用 + 公共 utils / config

場景：多條產(chǎn)品線、多個前端應(yīng)用，共享 utils、api-client、eslint-config 等，希望統(tǒng)一版本、統(tǒng)一升級。

推薦結(jié)構(gòu)：

packages/
  utils/
  api-client/
  config-eslint/
apps/
  app-a/
  app-b/

apps 按需依賴 @my/utils、@my/api-client；config-eslint 被各 app 的 devDependencies 引用。

關(guān)鍵配置：

• pnpm-workspace.yaml：同上。
• 各包用 workspace:* 互引；根 package.json 可放公共 devDependencies，或用 catalog 統(tǒng)一 React、TypeScript 等版本。
• 根腳本："build": "pnpm -r --filter './apps/*' run build"，只構(gòu)建 apps。

工作流：
公共邏輯在 packages/* 改，各 app 自動用到；發(fā)版用 changesets 按包發(fā)布，各 app 通過 workspace:* 或固定版本消費(fèi)。

6.3 文檔站 + 組件庫

場景：組件庫配套一個文檔站（如 VitePress、Docusaurus），文檔站要直接引用源碼里的組件做 Demo，而不是已發(fā)布的 npm 包。

推薦結(jié)構(gòu)：

packages/
  ui/
apps/
  docs/

docs 依賴 @my/ui，workspace:*。

關(guān)鍵配置：

• 同上，packages + apps；docs 里 "@my/ui": "workspace:*"。
• 文檔站構(gòu)建配置里保證能解析 packages/ui 的源碼（通常 workspace 鏈接后沒問題）。

工作流：

改組件 → 跑 docs 的 dev，文檔里實(shí)時看效果；發(fā)版時先發(fā) @my/ui，再更新文檔站里對版本的說明（若文檔站自己也要發(fā)）。

6.4 全棧 monorepo（前后端同倉）

場景：前端 + Node 服務(wù)同倉，共享類型、常量或少量 utils，用同一套依賴管理。

推薦結(jié)構(gòu)：

packages/
  types/
  shared-utils/
apps/
  web/
  api/          # Node 服務(wù)

api 和 web 都依賴 @my/types、@my/shared-utils，workspace:*。

關(guān)鍵配置：

• pnpm-workspace.yaml 包含 packages/*、apps/*。
• 根 package.json 的 scripts 里分別 --filter web、--filter api 跑 dev/build。

工作流：

改 types 或 shared-utils，前后端同時生效；各自部署時只構(gòu)建對應(yīng) app，公共邏輯通過 workspace 鏈進(jìn)去。

只要你存在「多個包 + 互相依賴 + 要一起開發(fā)」的需求，workspace 就很值得上；上面四種可以組合，比如「組件庫 + 多應(yīng)用 + 文檔站」一起做。

七、詳細(xì)教程：從零搭一個 pnpm workspace

下面按步驟做一遍，每步會寫操作、預(yù)期結(jié)果、常見報(bào)錯與排查。路徑、包名和上文保持一致，你照抄就能跑通。

7.1 環(huán)境準(zhǔn)備

• 安裝 pnpm：

  npm install -g pnpm
  

  或用 Corepack（Node 16.9+）：

  corepack enable
  corepack prepare pnpm@latest --activate
  

  建議用 pnpm 8.x 或 9.x，Node 18+ 更省心。

• 校驗(yàn)：

  pnpm -v
  node -v
  

  看到版本號即成功。

7.2 初始化根項(xiàng)目

mkdir my-workspace && cd my-workspace
pnpm init

會生成根目錄 package.json。編輯成類似：

{
  "name": "my-workspace",
  "version": "1.0.0",
  "private": true,
  "packageManager": "pnpm@9.0.0"
}

• private: true：根包不會被 pnpm publish 發(fā)出去，避免誤發(fā)。
• packageManager：鎖死 pnpm 版本，配合 corepack enable 使用；可選但推薦。

7.3 配置pnpm-workspace.yaml

在項(xiàng)目根目錄新建 pnpm-workspace.yaml：

packages:
  - 'packages/*'
  - 'apps/*'

• packages/*：packages/ 下每個子目錄（如 packages/ui、packages/utils）都算一個 workspace 包。
• apps/*：同理。
• 只有被列出來的目錄才會被 pnpm 當(dāng)成 workspace 成員，才能被 workspace:* 引用。

預(yù)期：保存后暫無輸出；之后 pnpm install 時 pnpm 會掃描這些目錄。

7.4 創(chuàng)建子包目錄并初始化

mkdir -p packages/ui packages/utils apps/web

然后逐個初始化（Windows 用戶可用 PowerShell，mkdir -p 若不可用就分步 mkdir）：

cd packages/utils && pnpm init && cd ../..
cd packages/ui   && pnpm init && cd ../..
cd apps/web      && pnpm init && cd ../..

（Windows：若 mkdir -p 報(bào)錯，可改為 mkdir packages\ui、mkdir packages\utils、mkdir apps\web 等分步創(chuàng)建；cd ../.. 在 PowerShell 中同樣適用。）

每個子包會多一個 package.json。接下來改包名、入口、exports。

packages/utils/package.json：

{
  "name": "@my/utils",
  "version": "0.0.1",
  "main": "index.js",
  "exports": {
    ".": "./index.js"
  }
}

packages/ui/package.json：

{
  "name": "@my/ui",
  "version": "0.0.1",
  "main": "index.js",
  "exports": {
    ".": "./index.js"
  }
}

apps/web/package.json：

{
  "name": "web",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "echo \"dev placeholder\"",
    "build": "echo \"build placeholder\""
  }
}

• exports：現(xiàn)代 Node 和打包器都認(rèn)，用來明確入口，避免多余文件被引用；對 ESM、TS 等更友好。
• web 的 dev/build 先占位，后面驗(yàn)證完 workspace 再換成真實(shí)命令。

7.5 用workspace:*做包間依賴

packages/ui/package.json 里加依賴 @my/utils：

{
  "name": "@my/ui",
  "version": "0.0.1",
  "main": "index.js",
  "exports": { ".": "./index.js" },
  "dependencies": {
    "@my/utils": "workspace:*"
  }
}

apps/web/package.json 里加依賴 @my/ui：

{
  "name": "web",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "echo \"dev placeholder\"",
    "build": "echo \"build placeholder\""
  },
  "dependencies": {
    "@my/ui": "workspace:*"
  }
}

workspace:* 表示「用當(dāng)前 workspace 里的同名包，追蹤源碼」；裝完依賴后會鏈接到對應(yīng)包目錄，改代碼即時生效。

7.6 根目錄執(zhí)行pnpm install

務(wù)必在根目錄執(zhí)行（若不在根目錄，先 cd 到項(xiàng)目根）：

pnpm install

預(yù)期：

• 根目錄出現(xiàn) node_modules/、pnpm-lock.yaml；
• packages/ui、apps/web 的 node_modules 里會有 @my/utils、@my/ui 的鏈接；
• lockfile 里能看到對 workspace: 的解析，例如：

packages:
  '@my/utils@workspace:*':
    resolution: { directory: packages/utils, type: directory }
  '@my/ui@workspace:*':
    resolution: { directory: packages/ui, type: directory }

（省略其他字段；實(shí)際 lockfile 還有 name、version 等。）

若報(bào) ERR_PNPM_NO_MATCHING_PACKAGE：檢查 pnpm-workspace.yaml 的 packages 是否包含對應(yīng)目錄，以及子包 name 是否和依賴?yán)飳懙囊恢隆?/p>

7.7 根package.json里加批量腳本

根目錄 package.json 增加：

{
  "name": "my-workspace",
  "version": "1.0.0",
  "private": true,
  "packageManager": "pnpm@9.0.0",
  "scripts": {
    "dev": "pnpm -r --parallel run dev",
    "build": "pnpm -r run build",
    "build:web": "pnpm --filter web run build"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

• pnpm -r：遞歸在所有 workspace 包里執(zhí)行同名 script。
• pnpm -r --parallel：并行跑，適合 dev。
• pnpm --filter web run build：只對 web 包執(zhí)行 build。

Windows：若使用 PowerShell，scripts 里的雙引號、&& 等和 Unix 略有差異，一般上述寫法沒問題；若遇解析錯誤，可改為 node 跑一小段腳本封裝命令。

7.8 驗(yàn)證 workspace 鏈路

• 在 packages/utils/index.js 寫：

module.exports = { add: (a, b) => a + b };

• 在 packages/ui/index.js 寫：

const { add } = require('@my/utils');
module.exports = { add, hello: 'from ui' };

• 在 apps/web 里加個臨時腳本驗(yàn)證。給 apps/web/package.json 的 scripts 增加一行 "run:check"，例如：

"scripts": {
  "dev": "echo \"dev placeholder\"",
  "build": "echo \"build placeholder\"",
  "run:check": "node -e \"const x=require('@my/ui'); console.log(x.add(1,2), x.hello)\""
}

保存后，在根目錄執(zhí)行：

pnpm --filter web run run:check

預(yù)期輸出：3 'from ui'。

若 Cannot find module '@my/ui'：

• 確認(rèn)在根目錄執(zhí)行過 pnpm install；
• 確認(rèn) apps/web 的 dependencies 里有 "@my/ui": "workspace:*"；
• 看看 apps/web/node_modules/@my 下是否有 ui 的鏈接。

若 ENOENT 等路徑類錯誤：

• 檢查 packages/utils、packages/ui 是否有 index.js，以及 package.json 的 main / exports 是否指向它。

驗(yàn)證通過后，可以把 web 的 dev / build 換成真實(shí)命令（如 Vite、Next 等），繼續(xù)開發(fā)。

八、配置說明（可查閱手冊）

這一節(jié)把 pnpm workspace 相關(guān)配置 拆開講：每項(xiàng)是啥、怎么配、適用場景、注意點(diǎn)。方便你以后查。

8.1pnpm-workspace.yaml

• 唯一性：整個倉庫只放一個在根目錄；pnpm 只認(rèn)根目錄這份。
• packages：
  • 字符串?dāng)?shù)組，每個元素是一個 glob 或具體路徑。
  • 例：'packages/*'、'apps/*'、'tools/*'，或 'packages/ui'、'packages/utils'。
  • 只有匹配到的目錄且其中包含 package.json，才會被當(dāng)作 workspace 包。
• 排除：部分版本支持 ! 排除，如 !'packages/legacy/*'，以你用的 pnpm 文檔為準(zhǔn)。
• 與 package.json 的 workspaces：pnpm 官方推薦用 pnpm-workspace.yaml 定義 workspace，不用 workspaces 字段；若同時存在，以 pnpm-workspace.yaml 為準(zhǔn)。

示例：

packages:
  - 'packages/*'
  - 'apps/*'
  - 'tools/*'

8.2 根目錄package.json

• private: true：根包不發(fā)布，避免誤 pnpm publish。
• packageManager：如 "pnpm@9.0.0"，鎖包管理器 + 版本；需 corepack enable。
• scripts：結(jié)合 pnpm -r、--filter 做批量或定向執(zhí)行（見 8.6）。
• pnpm.overrides：強(qiáng)制某依賴在全 workspace 解析成指定版本。

  {
    "pnpm": {
      "overrides": {
        "lodash": "4.17.21"
      }
    }
  }
  

  裝依賴時 pnpm 會按 overrides 解析，并反映在 lockfile；適合修安全漏洞、解決傳遞依賴沖突。
• catalog（pnpm 9+）：在 pnpm-workspace.yaml 里定義（不是 package.json），子包用 catalog: 引用；見下方示例。

catalog 示例（pnpm-workspace.yaml）：

packages:
  - 'packages/*'
  - 'apps/*'

catalog:
  react: ^18.3.1
  react-dom: ^18.3.1

子包 package.json：

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  }
}

升級時只改 catalog 即可，所有用 catalog: 的包一起變。

8.3workspace:協(xié)議

• workspace:*：用當(dāng)前 workspace 里同名包的任意版本，并鏈接到源碼目錄。開發(fā)聯(lián)調(diào)默認(rèn)用這個。
• workspace:^、workspace:~：按 semver 匹配 workspace 內(nèi)版本；發(fā)布時 pnpm 會把它替換成實(shí)際版本號（如 1.0.0），所以發(fā)布到 npm 的包不會還帶著 workspace:。
• 鎖文件里的表現(xiàn)：

  '@my/ui@workspace:*':
    resolution: { directory: packages/ui, type: directory }
  

  表示解析為本地 packages/ui 目錄。

日常開發(fā) workspace:* 就夠用；若你們有嚴(yán)格的 semver 約束再考慮 ^ / ~。

8.4pnpm-lock.yaml

• 唯一：整份 workspace 共用一個 lockfile，放在根目錄。
• 內(nèi)容：鎖住所有依賴（含 workspace 解析結(jié)果）的版本、完整性校驗(yàn)等。
• 維護(hù)：用 pnpm install、pnpm add 等變更依賴，不要手改。
• CI：務(wù)必把 pnpm-lock.yaml 納入 git；CI 里 pnpm install --frozen-lockfile 可保證和 lockfile 完全一致，復(fù)現(xiàn)構(gòu)建。

8.5.npmrc（項(xiàng)目級）

放在項(xiàng)目根目錄，只影響當(dāng)前倉庫。

常見項(xiàng)：

• node-linker=hoisted：切回類 npm 扁平結(jié)構(gòu)；兼容性好，但失去嚴(yán)格依賴。
• public-hoist-pattern：只把匹配的包提升，例如 ESLint、Prettier 等工具常見需求；能窄就窄，減少幽靈依賴。
• resolution-mode：依賴解析策略（如 lowest-direct）；lockfile-include-tty 等可按需查文檔。

示例（只提升部分工具）：

public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

8.6--filter完整語法

--filter 用來限定要對哪些 workspace 包執(zhí)行命令，常與 pnpm -r、pnpm add 等一起用。

示例：

# 只給 web 裝 lodash
pnpm add lodash --filter web

# 只給名字匹配 @my/* 的包跑 build
pnpm -r --filter '@my/*' run build

# 只給依賴了 @my/ui 的包跑 test（不含 @my/ui 自身，例如 web、docs）
pnpm -r --filter '...^@my/ui' run test

# 只給 web 及其依賴的 workspace 包跑 build（含 web 自身）
pnpm -r --filter '...web' run build

多 filter 可組合，例如 --filter '@my/ui...' --filter web 表示滿足任一條件的包。僅要「依賴了某包」的包且排除該包本身時，用 ...^<pkg>。

8.7 依賴提升（hoisting）

• 默認(rèn)：pnpm 不提升，依賴裝在各自包的 node_modules 或 .pnpm 下，嚴(yán)格隔離。
• public-hoist-pattern：把匹配的包額外提升到根 node_modules，方便某些工具查找；提升范圍越大，幽靈依賴風(fēng)險(xiǎn)越高。
• shamefully-hoist：幾乎全部提升，和 npm 類似；不推薦，除非你只是臨時兼容舊工具。

對比：

• 不提升：根 node_modules 只有直接依賴，子依賴在 .pnpm 里，嚴(yán)格。
• 提升后：根 node_modules 會出現(xiàn)被提升的包，未聲明也可能被引用，所以要想清楚再開。

8.8 只用 pnpm / 鎖包管理

• 全倉庫統(tǒng)一用 pnpm，禁止 npm、yarn，否則 lockfile 和鏈接會亂。
• 根 package.json 設(shè) packageManager，如 "pnpm@9.0.0"。
• 啟用 Corepack：corepack enable；CI 里先 corepack enable 再 pnpm install，保證版本一致。

九、和 npm / Yarn workspace 的簡單對比

何時選 pnpm workspace：

• 你打算認(rèn)真搞 monorepo、多包復(fù)用，且關(guān)注磁盤、安裝速度、依賴干凈。
• 愿意統(tǒng)一用 pnpm，并接受一點(diǎn)學(xué)習(xí)與遷移成本。

何時繼續(xù)用 npm / Yarn：

• 現(xiàn)有 npm/Yarn 腳本、CI 已經(jīng)很成熟，團(tuán)隊(duì)不想動。
• 單倉庫、包很少，workspace 收益有限，用 pnpm 單倉也不錯，不必非上 workspace。

pnpm 的差異主要來自存儲與解析策略，而不是「有沒有 workspace」本身。

十、進(jìn)階與延伸

10.1 發(fā)版：按包發(fā)布 + changesets

• pnpm publish -r：遞歸發(fā)布所有 未 private 的 workspace 包；可加 --filter 只發(fā)改動的，例如先 pnpm -r --filter '@my/ui...' run build 再 pnpm publish -r --filter '@my/ui'。
• changesets：
  • 用 changeset 管理 version bump 和 changelog；
  • 流程大致：改代碼 → pnpm changeset 選包、選版本類型、寫 changelog → pnpm changeset version 更新版本號 → pnpm publish -r 發(fā)布。
    這樣多包獨(dú)立發(fā)版、可追溯，很常見。

10.2 任務(wù)編排：Turborepo / Nx

• 根 package.json 的 build、dev 等可以交給 Turbo 或 Nx 跑：他們按依賴圖做拓?fù)渑判?/strong>，只跑該跑的，且能做遠(yuǎn)程/本地緩存，加速 CI 和本地構(gòu)建。
• pnpm workspace 只負(fù)責(zé)依賴安裝與鏈接；Turborepo/Nx 負(fù)責(zé)任務(wù)調(diào)度，兩者配合良好。