ERR_PNPM_WORKSPACE_PKG_NOT_FOUND 怎麼修？先對齊套件名稱與 workspace glob

先讀懂錯誤裡的套件身份#

假設應用程式宣告：

1
{
2
  "dependencies": {
3
    "@acme/ui": "workspace:*"
4
  }
5
}

pnpm 要找到的不是資料夾名稱，而是某個 workspace package manifest 中完全相同的名稱：

1
{
2
  "name": "@acme/ui",
3
  "version": "1.0.0"
4
}

packages/ui 是路徑，@acme/ui 是 package identity，兩者可以有關聯但不是同一個欄位。scope、大小寫、拼字或連字號只要有一處不同，都可能造成找不到。

workspace: protocol 的價值正在於它會拒絕從 registry 找替代品。pnpm 官方文件說明，當使用 workspace: 時，只有本機 workspace package 能滿足依賴；所以它報錯雖然直接，卻能避免 CI 不小心安裝另一個版本。

確認 workspace root 與 package glob#

pnpm workspace 的 root 必須有 pnpm-workspace.yaml。例如：

1
.
2
├── package.json
3
├── pnpm-lock.yaml
4
├── pnpm-workspace.yaml
5
├── apps/
6
│   └── web/
7
│       └── package.json
8
└── packages/
9
    └── ui/
10
        └── package.json

對應設定可以是：

1
packages:
2
  - 'apps/*'
3
  - 'packages/*'

如果套件更深一層，例如 packages/design/ui，packages/* 不會自動匹配它；要依實際結構加入 packages/** 或更窄的路徑。反過來，過寬的 glob 也可能把測試資料夾或不應加入的 package 納進來，所以不要只靠加 ** 讓錯誤消失。

pnpm 官方設定文件也指出，如果省略 packages 欄位，workspace 只包含 root package。先確認你是在包含這份 YAML 的目錄執行安裝，不要在子資料夾把另一個 package.json 當成 workspace root。

用唯讀檢查依序定位#

從包含 pnpm-workspace.yaml 的根目錄執行：

1
pwd
2
sed -n '1,160p' pnpm-workspace.yaml
3
node -p "require('./packages/ui/package.json').name"
4
node -p "require('./apps/web/package.json').dependencies['@acme/ui']"

把 packages/ui、apps/web 和 @acme/ui 換成錯誤訊息中的實際路徑與名稱。這四個檢查分別回答：目前位置是不是 root、glob 寫了什麼、被引用 package 的 name 是什麼，以及 consumer 要求什麼版本。

接著可用 filter 確認 pnpm 是否已看見該 package：

1
pnpm --filter '@acme/ui' exec pwd
2
pnpm --filter '@acme/ui' list --depth 0

若 filter 也找不到，先修 root、glob 或 name；如果 filter 找得到但 install 仍失敗，再檢查 dependency range、lockfile 與是否在另一個目錄執行指令。

四種常見原因與精確修法#

1
packages:
2
  - 'apps/*'
3
  - 'packages/*'
4
  - 'packages/design/**'

1
{
2
  "name": "@acme/design-system"
3
}

不要先做這些看似有效的修復#

• 不要只把 workspace:* 換成 *，這可能讓 install 下載錯誤版本。
• 不要為了通過一次 CI 就加入沒有邊界的 ** glob。
• 不要把 lockfile 刪掉當成第一個動作；它不會把未被 workspace 發現的 package 變出來。
• 不要從 nested directory 執行修復後，假設 CI 會找到同一個 root。
• 不要把 npm Workspaces 的 workspaces 欄位和 pnpm 的 pnpm-workspace.yaml 混用；兩者的 lockfile、依賴 protocol 與設定位置不同。

如果你正在做 npm 與 pnpm 的 monorepo 選擇，可以搭配 npm Workspaces 整理 Vue 3 多專案 查看兩套工具的界線；本文則只處理 pnpm 已經報出 workspace package 找不到的情況。

修好後再做一次乾淨安裝驗證#

當 identity、glob 和 protocol 都一致後，再從 workspace root 重新安裝：

1
pnpm install
2
pnpm --filter '@acme/ui' run build
3
pnpm --filter '@acme/web' run build
4
git diff -- package.json pnpm-workspace.yaml pnpm-lock.yaml

實際 filter 名稱依 repository 的 name 為準。若只改了 package name 或 glob，diff 應該能清楚說明 workspace 範圍與 lockfile 為何改變；如果出現大量無關版本更新，先停下來確認 pnpm 版本與 registry 設定，不要把噪音一起提交。

這個錯誤的核心不是「pnpm 不會讀資料夾」，而是三個邊界沒有說同一件事：manifest 的 package identity、workspace 的 discovery glob，以及 dependency 的 local-only protocol。讓它們一致，通常不需要特殊 install flag。

常見問題#