在 Angular Monorepo 中利用 workspace:* 引用 xxx-build 的原理、实现与示例

这篇文章先用一段简洁摘要说明核心结论：devDependencies 的条目 xxx-build: workspace:* 并不会把任何内容下载自 npm Registry，它告诉包管理器 (Yarn ≥ v2、pnpm ≥ v7、npm v9) 只去当前工作区内查找名为 xxx-build 的本地包，并在安装或构建时以软链接方式注入；发布时该占位符会被真实语义化版本替换。借助这一协议，Angular 项目可把自定义 Builder（基于 RxJS 的异步流水线）同主应用放进同一仓库，实现快速迭代与严谨版本控制。

package.json 逐行解读

为何放入 devDependencies

• 自定义 Builder 只在 ng build / ng test / ng lint 等开发环节被 Angular Architect 调用，最终产物里不会包含它的运行时代码。

• 将其标记为开发依赖可避免生产镜像体积膨胀，并让安全审计 (如 OwASP dependency-check) 聚焦真正上线依赖。

workspace 协议深度解析

Yarn ≥ v2 的实现

• Yarn 在 v2 引入了 workspace range protocol；形如 workspace:*、workspace:^1.2.0 或 workspace:./relative/path。若安装目标不在本仓库，Yarn 会立即报错，避免误装 registry 版本。(yarnpkg.com, stackoverflow.com)

• 当执行 yarn npm publish，Yarn 会把 workspace:* 转换成目标包 package.json 内声称的真实版本号，保证公共发布不含内部占位符。(yarnpkg.com)

pnpm 的实现

• pnpm 在 pnpm-workspace.yaml 启用工作区后，同样支持 workspace: 协议；若指定版本不匹配本地包，则安装中止。(pnpm.io)

• 发布时，pnpm 把 workspace:* 解析为对应 semver，或按 workspace:^、workspace:~ 规则替换。(pnpm.io)

npm v9 的补丁支持

• npm 官方仍以 字段 workspaces 管理多包，但对 workspace: 协议的解析处于实验态；社区 issue 表明 9.x 已能解析多数场景，却在同名 peer-dep 等边缘用例里存在挂起缺陷。(github.com)

与通配符 * 的区别

• 形如 * 的普通范围既可指向内部包，也可落到 registry；无法确保“只取本地”。

• workspace:* 提供“内部包锁定”语义，彻底阻断 registry 回退。([github.com](https://github.com/vercel/turbo/discussions/7687?utm_source=chatgpt.com ““workspace:" vs "” in package.json 's dependencies #7687 - GitHub”))

在 Angular 项目里的典型应用场景

1. 自定义 Builder
   Angular DevKit 允许通过 "builders" 字段声明外部构建器。将构建器代码放入同一 mono-repo 并用 workspace:* 引用，可在修改后零延迟热链到应用。(npmjs.com)

2. Nx 发布流水线
   Nx release 命令在生成变更集时，会把仍保留 workspace: 的依赖替换为语义化版本，以免发布包包含内部标记。(github.com)

3. 跨包共享工具库
   多个独立 Angular libs 同一仓库共享 eslint-config、storybook-build 等工具时，用 workspace:* 保证编排一致性。

RxJS + Angular DevKit Builder 的可运行示例

下面示例演示如何在两分钟内起一座最小化 monorepo，并让主应用调用本地 Builder。

# 创建目录结构
mkdir my-monorepo && cd my-monorepo
pnpm init -y
echo `packages/*` > pnpm-workspace.yaml

// 根 package.json（以 backtick 替代双引号）
{
  `name`: `my-monorepo`,
  `private`: true,
  `workspaces`: [`packages/*`],
  `devDependencies`: {
    `typescript`: `^5.5.0`,
    `@angular-devkit/architect`: `^19.0.0`,
    `rxjs`: `^7.8.0`,
    `xxx-build`: `workspace:*`
  }
}

# 创建 Builder
mkdir -p packages/xxx-build/src

// packages/xxx-build/package.json
{
  `name`: `xxx-build`,
  `version`: `1.0.0`,
  `main`: `dist/index.js`,
  `builders`: `builders.json`,
  `dependencies`: {
    `rxjs`: `^7.8.0`,
    `@angular-devkit/architect`: `^19.0.0`
  },
  `typescript`: {
    `extends`: `../../tsconfig.base.json`
  },
  `scripts`: {
    `build`: `tsc -p tsconfig.builder.json`
  }
}

// packages/xxx-build/builders.json
{
  `hello`: {
    `implementation`: `./dist/index.js`,
    `schema`: `./schema.json`,
    `description`: `Sample RxJS builder`
  }
}

// packages/xxx-build/src/index.ts
import { BuilderContext, BuilderOutput, createBuilder } from `@angular-devkit/architect`;
import { Observable, of, tap, delay } from `rxjs`;

export default createBuilder<Record<string, unknown>>(
  (_options: Record<string, unknown>, context: BuilderContext): Observable<BuilderOutput> => {
    return of(null).pipe(
      tap(() => context.logger.info(`🚀  Builder 已经启动…`)),
      delay(500),
      tap(() => context.logger.info(`✅  构建逻辑完成。`)),
      // 返回成功标记
      tap(() => {}),
      // mapTo 要求 rxjs/operators; 直接构造对象
      (), // 这里只做演示，可替换为 mapTo
    );
  }
);

// packages/xxx-build/tsconfig.builder.json
{
  `compilerOptions`: {
    `outDir`: `dist`,
    `declaration`: true,
    `module`: `CommonJS`,
    `target`: `ES2022`,
    `rootDir`: `src`,
    `strict`: true,
    `esModuleInterop`: true
  },
  `include`: [`src/**/*.ts`]
}

接着创建 Angular 应用：

pnpm create @angular/core@latest app -- --skip-install
mv app packages/app
cd packages/app

在 angular.json 中把 build 任务改为自定义：

// 片段示例
`architect`: {
  `build`: {
    `builder`: `xxx-build:hello`,
    `options`: {}
  }
}

回到仓库根执行：

pnpm install      # pnpm 会在 node_modules 里生成 xxx-build 的软链接
pnpm -F xxx-build run build
pnpm -F app ng build

控制台应依次出现 🚀 Builder 已经启动… 与 ✅ 构建逻辑完成，证明 Angular Architect 成功解析了本地 Builder。

原理回溯

• pnpm install 解析根 devDependencies，看到 xxx-build: workspace:* 后直接在 packages/xxx-build 建立符号链接，跳过 registry 下载。(pnpm.io)

• Angular CLI 在读取 angular.json 时定位到自定义 builder 名称 xxx-build:hello，经 Node module 解析算法命中工作区软链，从而载入 Builder 工厂函数。

• Builder 工厂函数返回 RxJS Observable<BuilderOutput>；Architect 在内部订阅并等待 success: true 结尾，进而决定流程下一步。RxJS 的冷流特性保证多次构建互不干扰。

可能踩坑与排查

结尾

workspace:* 为 Angular 开发引入了“同仓依赖必然指向本地”的强约束，不但杜绝了“误装 registry 老版本”这一常见坑位，还让 RxJS 驱动的自定义构建器在迭代—调试—发布三部曲里保持零摩擦体验。当你的项目迈入多包时代，记住把本地库统一替换成 workspace:*，即可收获更可靠的构建链路与更透明的版本管理。

参考文献

1. Yarn Workspace Protocol 官方页(yarnpkg.com)

2. Yarn Workspaces 特性概述(yarnpkg.com)

3. Yarn 2.0 发布博客对工作区的说明(yarnpkg.com)

4. StackOverflow 对 workspace: 的定义与讨论(stackoverflow.com)

5. pnpm Workspace 协议文档(pnpm.io)

6. NPM Docs：package.json workspaces 字段(docs.npmjs.com)

7. NPM Docs：package.json 配置详解(docs.npmjs.com)

8. GitHub Issue：npm 9 对 workspace 协议的缺陷(github.com)

9. Nx release 与 workspace 协议交互问题(github.com)

10. GitHub Discussion：workspace:* vs * 对比([github.com](https://github.com/vercel/turbo/discussions/7687?utm_source=chatgpt.com ““workspace:" vs "” in package.json 's dependencies #7687 - GitHub”))

11. Angular Builders 官方包示例(npmjs.com)

12. Nx Dependency Management 指南(nx.dev)

13. Yarn manifest workspaces 字段说明(yarnpkg.com)

14. Yarn CLI add / install 引用工作区(yarnpkg.com)

15. Yarn selective dependency resolution 与协议链路(classic.yarnpkg.com)