Inquirer.js 单仓包隔离实战：isolate-monorepo-package 的发布流程模拟与依赖验证

isolate-monorepo-package 是 Inquirer.js 仓库内置的一个命令行工具，用于把单体仓库（monorepo）中的某个工作区包“隔离”出来，在本地复刻一次发布到 npm 后的真实消费场景，从而提前验证目标包与所有工作区依赖在构建之后能否协同工作。读完本文，你将掌握该工具的完整用法、命令行参数、stdout 输出约定与故障排查方法，并能从源码级理解它自动发现依赖、打包 tarball、改写 package.json 的完整工作流，将其复用到你自己的 Yarn/npm 工作区项目中进行发布前验证。

这个工具解决什么问题

在多包 monorepo（如本仓库，见根目录 package.json 中 workspaces: ["packages/*", "integration/*", "tools/*"]）中，开发期包之间通过 workspace:* 协议互相引用，依赖解析与链接都由包管理器在本仓库内完成。但发布后，每个包是独立存在于 npm 上的，消费者只会按 dependencies 中声明的版本号去解析依赖。

这种差异带来一个经典隐患：开发时能跑通，不代表发布后能跑通。例如某包发布后依赖了尚未发布的新版本兄弟包，或 peer 依赖与兄弟包的产物不兼容，只有真正按“已发布”形态安装一次才能暴露问题。

isolate-monorepo-package 的设计目标，就是用本地脚本模拟“已发布到 npm”的形态：

1. 自动发现目标包的全部工作区依赖（直接依赖与传递依赖）；
2. 把这些工作区依赖打包为 tarball（本地模拟 npm 包）；
3. 创建一个隔离的临时目录，并改写其中的 package.json，使依赖指向本地 tarball；
4. 输出该临时目录的路径，供你进入其中执行 install / test 做验证。

这正是 README.md 中所描述的“locally replicating the release flow to ensure dependencies will work together post build”。

安装：无需单独安装

该工具随 Inquirer 工作区自动可用，不需要额外安装。根目录 package.json 的 devDependencies 中已声明 "isolate-monorepo-package": "workspace:*"，工具自身的清单文件为 tools/isolate-monorepo-package/package.json，其中 "bin": "./src/bin.ts" 声明了可执行入口，工作区安装后即可直接在命令行使用 isolate-monorepo-package（或通过 yarn isolate-monorepo-package 调用）。

当前版本为 1.0.0，标记为 "private": true，说明它尚未作为独立 npm 包对外发布，仅服务于本仓库（以及可复制到其他 monorepo 场景）。

使用方法

基础用法

# 基本用法——输出隔离目录的路径
isolate-monorepo-package @inquirer/demo

以 @inquirer/demo 为目标包时，工具会输出一个隔离目录路径（位于系统临时目录），该目录内已复制好 @inquirer/demo 的源码，且 package.json 的依赖已指向打包好的本地 tarball。

一行式：直接进入隔离目录跑测试

# 一行式方案——直接 cd 进隔离目录
cd $(yarn isolate-monorepo-package @inquirer/demo)
yarn set version stable # 仅对 yarn 生效；本仓库未预置该设置，因此需要显式指定要运行的版本
yarn install
yarn test
cd -

注意这里的 yarn set version stable 是 yarn 特有的步骤：因为隔离目录只复制了目标包和 .yarnrc.yml，没有携带本仓库完整的 yarn 版本管理配置，所以需要显式指定 yarn 运行版本。

或使用 npm

cd $(yarn isolate-monorepo-package @inquirer/demo)
npm install
npm test
cd -

尽管工具底层使用 yarn（如 yarn workspaces list、yarn workspace ... pack），但它对包管理器是中立的：只要你的包管理器支持 workspaces 即可，隔离目录内生成的 resolutions（yarn 协议）与 overrides（npm 协议）会被对应包管理器分别识别。

包名校验与错误提示

工具入口 src/bin.ts 的 parseArguments 会解析命令行参数：若未提供包名，会输出如下错误与用法提示后退出：

Error: No package name provided

Usage: isolate-monorepo-package <package-name> [-v|--verbose]

Options:
  -v, --verbose  Show verbose output

Examples:
  isolate-monorepo-package @inquirer/demo
  isolate-monorepo-package @inquirer/core -v
  cd $(isolate-monorepo-package @inquirer/demo)

命令行参数

参数	含义	说明
<package-name>	要隔离的工作区包名	必填，须与工作区中声明的包名完全一致（如 @inquirer/demo、@inquirer/core）
-v, --verbose	显示详细进度信息	可选；所有详细日志都输出到 stderr，不影响 stdout 的路径输出

若指定的包名在工作区中不存在，validatePackageExists（见 src/index.ts）会抛出 IsolatedBuildError，并列出当前工作区中所有可用包名供你核对。

输出约定：stdout 只输出目录路径

为了让脚本便于捕获路径，工具严格遵守一条输出约定：

工具仅向 stdout 输出隔离目录的路径；其余所有消息（进度、错误、详细日志）一律走 stderr。

这一点在 src/bin.ts 的 main 中实现：console.log(isolatedDir) 是唯一写入 stdout 的语句，而源码中所有进度信息都通过 console.error(...) 输出。因此在 shell 脚本中可以放心地捕获路径：

# 捕获路径到变量
TEST_DIR=$(isolate-monorepo-package @inquirer/demo)

# 或直接 cd
cd $(isolate-monorepo-package @inquirer/demo)

源码级工作流：七步构建隔离环境

入口 createIsolatedEnvironment（见 src/index.ts）串联了七个步骤，下面结合源码逐层拆解。

第 1 步：定位工作区根目录

findWorkspaceRoot（src/index.ts）从当前工作目录开始逐级向上查找 .yarnrc.yml，找到即视为工作区根；若一直找到文件系统根仍未发现，则抛出 IsolatedBuildError：Could not find yarn workspace root (.yarnrc.yml not found)。

这也解释了 README 故障排查中的第一条：你必须在 Yarn 工作区（存在 .yarnrc.yml）内使用该工具。本仓库根目录确实存在 .yarnrc.yml。

第 2 步：发现全部工作区包

discoverWorkspaces（src/index.ts）执行 yarn workspaces list --json 获取所有工作区位置，随后对每个工作区读取其 package.json，从 dependencies、devDependencies、peerDependencies 三张表中提取“工作区依赖”：

• 版本字符串以 workspace: 开头的依赖；
• 或依赖名存在于工作区包名集合中的依赖。

两者都满足其一即认为该依赖属于本仓库内部包。

第 3 步：校验目标包存在

validatePackageExists 检查目标包名是否在工作区映射中，不存在则报错并列出全部可用包名。

第 4 步：收集直接与传递依赖

collectDependencies（src/index.ts）对目标包做递归收集，使用 visited 集合规避循环依赖；collectWorkspaceDependencies（src/index.ts）在收集完成后删除目标包自身，并过滤出仅属于工作区的依赖集合。

第 5 步：将全部依赖打包为 tarball

先通过 mkdtemp 在系统临时目录创建 isolate-monorepo-artifacts-* 工件目录并 chmod 0o700，随后 packAllDependencies（src/index.ts）并行地对每个工作区依赖执行：

yarn workspace <dep-name> pack --out <artifacts-dir>/<safe-name>.tgz

packWorkspace（src/index.ts）会生成安全文件名——把包名中的 @ 去掉、/ 替换为 -（如 @inquirer/core → inquirer-core.tgz）——任一打包失败都会以 IsolatedBuildError 报错。

第 6 步：创建隔离环境并改写 package.json

setupIsolatedEnvironment（src/index.ts）完成三件事：

1. 在 os.tmpdir() 下创建 isolate-monorepo-package-* 临时目录（chmod 0o700），把目标包目录整体复制进去；
2. 把工作区根的 .yarnrc.yml 复制到隔离目录，保证 yarn 行为一致；
3. 改写隔离目录中的 package.json：
   • 将直接依赖中命中 tarball 映射的条目改为 file:<tarball-path> 协议；
   • 同时写入 resolutions（yarn）与 overrides（npm）字段，覆盖全部工作区依赖（含间接依赖），确保整棵依赖树使用一致的本地版本。

其中 pkg.resolutions ??= {}、pkg.overrides ??= {} 的写法（src/index.ts）保证在目标包原本没有这些字段时也能安全写入。

第 7 步：返回隔离目录路径

createIsolatedEnvironment 返回隔离目录路径，最终由 bin 入口输出到 stdout。

隔离环境的目录形态

完成隔离后，你会得到类似下面的结构（实际路径是系统临时目录下的随机目录名）：

/tmp/isolate-monorepo-package-XXXX/
└── demo/                       # 目标包源码副本
    ├── .yarnrc.yml             # 复制自工作区根
    ├── package.json            # 依赖已改写
    └── ...（目标包源码）

配套的 tarball 存放在另一个 isolate-monorepo-artifacts-* 临时目录中，供隔离目录的 file: 协议引用。进入隔离目录执行 install && test，即可验证“发布后形态”下包与依赖能否协同工作。

故障排查

若工具执行失败，按 README 给出的顺序排查：

1. 确认位于 Yarn 工作区内：.yarnrc.yml 必须存在（这正是根目录探测的依据，对应 findWorkspaceRoot 的报错）；
2. 确认包名存在于工作区：工具会列出可用包名，仔细比对拼写与 scope（如 @inquirer/core 而非 core）；
3. 使用 -v 查看详细输出：isolate-monorepo-package <package-name> -v 会打印每一步的进度（发现的工作区、依赖清单、打包结果、package.json 改写细节等），可快速定位失败环节；
4. 确保临时目录可写：README 中原话为“Ensure /tmp/artifacts/ is writable”。从源码看，工具实际使用 os.tmpdir()（Linux 下通常为 /tmp）创建工件与隔离目录，因此请确保系统临时目录对当前用户可写。

适用前提与限制

• Node 版本：工具自身在 package.json 声明 "node": ">=24"，使用前请确认运行环境满足要求；
• 必须存在 .yarnrc.yml：这是工作区根目录识别的唯一依据，也是 README 与源码共同强调的前置条件；
• 包管理器兼容性：底层调用的是 yarn 的 workspaces list 与 workspace pack 命令，但隔离环境产物同时写入 yarn 的 resolutions 与 npm 的 overrides，因此任何支持 workspaces 的包管理器都可消费最终产物；
• 模拟范围：它模拟的是“依赖以本地 tarball 形式被安装”的形态，用于发布前的构建与测试验证，并不包含真实的 npm 发布流程。

许可证

Copyright (c) 2025 Simon Boudrias，以 MIT 许可证发布，详见仓库根目录 LICENSE。