使用 Nx 空工作区测试本地包面向 nx 源码开发的 init 生成器与推理插件验证指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx导读在 nx 仓库中开发或修改一个包如nx/vite、nx/oxlint后你往往希望在发布到 registry 之前就验证init生成器、推理插件inference plugins和nx add流程在真实工作区中的表现。仓库提供了 examples/empty 这样一个真正的空工作区它没有项目、没有tsconfig.json、没有任何源码文件因此生成器或插件对工作区做出的任何改动就是完整且唯一的 diff。本文基于该空工作区的设计讲解它的工作原理、本地包接入方式、生成器与推理插件的实测流程、常见陷阱如根目录被误判为项目以及重置方法并给出对应源码依据。为什么需要真正的空工作区普通示例工作区通常已经包含项目、配置和源码测试包时难以区分哪些改动来自我的生成器。而examples/empty的设计原则是工作区内没有任何 Nx 项目凡是生成器写入的内容都能通过git status完整观察做到所见即所得。没有tsconfig.json也没有源码文件因此init生成器、nx add流程对工作区的全部修改就是一个干净的 diff它本身是一个独立的 pnpm workspace拥有自己的pnpm-lock.yaml见 pnpm-lock.yaml在其中执行pnpm install永远不会触碰仓库根目录的依赖树本地包通过link:依赖接入pnpm 的link:协议天然支持跨 workspace 边界链接见 pnpm-workspace.yaml 的注释说明。从 package.json 可以看到它声明的devDependencies全部指向../../packages/*// examples/empty/package.json devDependencies: { nx/angular: link:../../packages/angular, nx/devkit: link:../../packages/devkit, nx/js: link:../../packages/js, nx/oxlint: link:../../packages/oxlint, nx/playwright: link:../../packages/playwright, nx/react: link:../../packages/react, nx/vite: link:../../packages/vite, nx/vitest: link:../../packages/vitest, nx/vue: link:../../packages/vue, nx/web: link:../../packages/web, nx: link:../../packages/nx, typescript: ~5.9.2 }也就是说工作区里跑的nx命令来自packages/nx的工作树代码而非已发布的 npm 包——这正是针对工作树里的包而不是发布版本进行测试这一目标的实现基础。初始化与构建链接包安装pnpm installpackage.json中的postinstall脚本负责在安装完成后构建链接的本地包scripts: { postinstall: cd ../.. pnpm nx run-many -t build -p nx js nx/oxlint angular react vue playwright vite vitest web --skip-sync }该脚本回到仓库根目录cd ../..用根工作区的nx对nx、js、nx/oxlint、angular、react、vue、playwright、vite、vitest、web等包执行run-many -t build。由于这些包是以link:方式接入的postinstall从源码构建它们确保空工作区运行的始终是你工作树中的最新代码而不是某个缓存的旧构建产物。如果你修改了某个包的源码但未构建可在空工作区里手动重新构建cd ../.. pnpm nx run-many -t build -p 包名工作区配置文件nx.json 保持了最小化配置只声明了输入与遥测相关项{ $schema: ../../node_modules/nx/schemas/nx-schema.json, namedInputs: { default: [{projectRoot}/**/*, sharedGlobals], sharedGlobals: [] }, plugins: [], analytics: false, neverConnectToCloud: true }其中plugins: []表示默认不加载任何插件analytics: false与neverConnectToCloud: true则确保测试过程不会产生遥测上报或连接 Nx Cloud。测试某个包的生成器链接目标包无论你要验证的是已有包还是新开发的包第一步都是把它加进devDependencies并同步加入postinstall的构建列表// examples/empty/package.json devDependencies: { nx/vite: link:../../packages/vite }然后在根目录构建该包后重新安装cd ../.. pnpm nx run-many -t build -p vite cd examples/empty pnpm install直接调用生成器绕过 registry生成器通常通过nx add触发而nx add会从registry解析包——对于尚未发布、或仅在工作树中被修改过的本地包这一路径并不可行。此时应直接调用生成器nx g nx/oxlint:init该命令会在空工作区中执行nx/oxlint的init生成器其产生的所有文件变更oxlint.json、package.json依赖、.vscode/extensions.json推荐等就是你测试的净输出。检查生成结果生成完成后用 git 观察完整 diffgit status再查看工作区中被识别的项目nx show projects因为初始工作区没有任何项目nx show projects的输出一开始应为空生成器每写入一个可被推理插件识别的项目这里就会多出一行这正是验证推理插件是否生效的最直接手段。生成项目以验证推理插件大多数推理插件会刻意跳过没有匹配文件的项目——空工作区里没有任何源码文件插件无从推断项目。因此当你要验证某个推理插件时需要先在工作区内生成一个真实项目供插件拾取nx g nx/js:lib packages/demo --linter oxlint例如上述命令会在packages/demo下生成一个使用 oxlint 作为 linter 的 JS 库。随后nx show projects如果推理插件工作正常demo会出现在项目列表中。用源码佐证这一点文件归属推断依赖 find-project-for-path.ts 中的findProjectForPath——它基于{ projectRoot - projectName }映射从文件路径逐级向上dirname查找最近的已知项目根对应的单元测试 验证了给定 src 内任意子路径都能定位到所属项目的行为。由此可见若工作区中不存在任何项目findProjectForPath自然匹配不到项目推理插件也就不会产出项目节点。.vscode/extensions.json模拟真实新建工作区.vscode/extensions.json是刻意存在的它镜像了create-nx-workspace生成的内容因此那些追加编辑器推荐扩展的生成器有东西可追加。// examples/empty/.vscode/extensions.json { recommendations: [nrwl.angular-console] }实现层面可参考 utils.ts 中的addVsCodeRecommendedExtensions它只在该文件已存在时读取并追加去重后的recommendations不存在时则以{ recommendations: extensions }新建。也就是说生成器不会为没有该文件的工作区凭空创建它——空工作区预置这一文件正是为了测试追加路径而非新建路径。关键陷阱不要给根目录添加项目这是空工作区最重要的使用约束。根目录的 package.json刻意不包含nx键。原因如下一旦在根package.json中加入nx: {}根目录就会成为一个项目root: .此时 findProjectForPath 的向上逐级匹配会命中根目录这个.项目——任何路径包括工作区之外的路径都会被判定属于该根项目于是本地link:依赖会被当作工作区源码处理Nx 转而加载插件的TypeScript 源码而非构建后的dist由于 TypeScript 源码中的NodeNext风格的.jsimport 说明符只在构建后才会存在生成器最终会因为这些不存在的导入而失败。因此在空工作区中测试时请保持根package.json不含nx键避免把根目录变成项目。在两次测试之间重置工作区生成器会不断污染工作区测试之间需要彻底重置git clean -fdx . git checkout -- . pnpm installgit clean -fdx .删除所有未跟踪文件包括node_modules、.nx缓存以及生成器写入的新文件git checkout -- .恢复被修改的已跟踪文件最后重新pnpm install触发postinstall重新构建链接包回到一个干净、可复现的初始状态。小结空工作区的完整测试循环把上面各节串起来一次典型的本地包验证流程是在examples/empty/package.json中加入nx/xxx: link:../../packages/xxx并把它加进postinstall的构建列表cd ../.. pnpm nx run-many -t build -p xxx再回到examples/empty执行pnpm install直接调用生成器nx g nx/xxx:init观察输出git status看 diffnx show projects看项目推断结果需要验证推理插件时先nx g nx/js:lib packages/demo --linter oxlint生成一个真实项目测试完毕执行git clean -fdx . git checkout -- . pnpm install重置。这套基于 examples/empty 的流程让 nx 的开发者在不发布任何包的前提下用最小、最可控的工作区验证生成器与推理插件的真实行为是 nx 源码开发与 CI 回归中极具价值的测试阵地。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考