pnpm 安装发布包报 WORKSPACE_PKG_NOT_FOUND：检查包内未转换的 workspace 协议

项目安装一个已发布的组件包，pnpm 却提示 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND，指出该组件依赖的另一个包使用了 workspace:*，当前工作区里找不到它。项目本身甚至没有这两个工作区成员时，应先检查下载到的组件包清单，而不是给自己的仓库补一批空目录。

workspace 协议表示只从本地工作区解析依赖，不会因包名存在于远程仓库就自动退回下载。发布包仍带着发布者的本地协议，和自己的工作区配置漏掉成员，是两个不同分支。本文针对 pnpm 工作区包的打包与消费，不将旧版本中从成员目录安装的个案直接视为当前版本通用缺陷。

看报错指向哪一层 package.json

保留错误中的项目路径、失败包名与依赖声明，确认这条 workspace 依赖来自自己的成员包，还是来自下载的第三方包。

若来自自己的源码，检查 pnpm-workspace.yaml 的成员范围、目标包是否真的在当前检出或构建上下文里，以及 package.json 的 name 是否与依赖名一致。目录叫 utilities，不代表包名就是 utilities；带 scope 的名称也需要匹配。CI 只复制了应用目录而遗漏共享包时，切换安装参数不会产生缺失源码。

若来自发布包，查看实际收到的包内容及 package.json，记录版本、注册表或 Git 来源。不要只查看上游仓库当前分支：发布归档的清单可能与源码清单不同。

例如，已下载组件里仍然有下面的清单片段，名称仅作示例：

{
  "name": "@example/component",
  "dependencies": {
    "@example/utilities": "workspace:*"
  }
}

在不含 @example/utilities 的消费工作区，这个协议不能按普通远程版本解析。另一种报错是工作区确有同名包但版本范围不符，应按具体错误核对版本，不能都归为“没有这个包”。

发布流程应转换协议，而不是要求消费者复制整个仓库

pnpm 在打包工作区包时，会把 workspace 依赖替换为相应版本或版本范围。pnpm pack 以及 pnpm publish 的打包流程支持这种转换。例如目标 utilities 版本为 1.5.0 时，workspace:* 会转成 1.5.0，workspace:^ 会转成 ^1.5.0。

因此修复点通常在发布产物：确认实际流程使用了支持转换的打包方式，并检查最终归档的 manifest。仅在源码目录中测试两个工作区包互相能导入，无法证明发布包能被外部项目安装。

可在隔离目录使用现有发布工具准备归档，再将这个归档安装进不包含发布者工作区的测试项目。这里只说明验证过程，不能把 pnpm publish 当作无影响的检查命令；真实发布会写入注册表，需要按项目版本与发布流程执行。

配套依赖还必须已经发布到正确注册表，声明的版本范围能被消费者取得，所需权限也应具备。协议成功转换后，若变成版本不存在或认证错误，应继续处理该分支，而不是重新改回 workspace:*。

Git 子目录依赖也要核对交付边界

直接安装另一个 monorepo 的 Git 子目录，不等于把那个仓库的所有工作区成员导入当前项目。它带来的内部依赖如果仍以本地 workspace 协议声明，也不能保证在消费项目中自动找到兄弟包。

这类依赖应明确交付方式：使用已正确打包发布的版本，或在受维护流程中构建并交付其所需产物。不要仅因手动安装某个兄弟包暂时成功，就宣布整套跨仓库工作区解析已经可靠。

也不要直接编辑 node_modules 里的清单作为修复。重新安装会覆盖它，锁文件与真实依赖契约也可能脱节。必须临时使用补丁或固定替代版本时，把它放到项目认可的依赖管理流程中，并核对兼容性和最终发布修复后的退出办法。

用外部消费项目验收

保存原清单、锁文件、pnpm 版本和发布流程配置。改动后，最终归档中的普通远程依赖不再残留指向发布者私有工作区的协议；在独立消费项目中安装应能解析到预期版本，并完成组件构建及关键功能检查。

安装阶段可能运行包的生命周期脚本，应使用项目正常的隔离验证环境。不要删掉锁文件或清空所有缓存来替代对归档内容的核对。

已发布的错误版本不能通过恢复本地源码自动修好。按注册表与项目规则发布新的修正版，并让消费者选择明确版本；回退时一起恢复审定的依赖声明、锁文件与配置，避免留下一套只在某台机器上可用的手工补丁。