pnpm 包别名（npm: 协议）详解：AIRI 项目中的多版本并存与 Fork 替换实践

本文以 pnpm 的包别名（package alias，npm: 协议）机制为主线，结合 airi 仓库的 pnpm 技能参考文档 逐层展开：先讲清单别名、Fork 替换、弃用包顶替、scoped 与 unscoped 互换等语法与适用场景，再用 AIRI monorepo 中 pnpm-workspace.yaml、stage-ui-spine 包 及其 Spine 运行时加载器 等真实代码，印证别名在实际工程中的落点。读完本文，你能掌握 npm: 别名的完整语法，并理解它在 Catalog、overrides、lockfile 解析链路中的实际行为，具备在大型 monorepo 中用别名管理多版本依赖与替换第三方包的能力。

一、为什么需要包别名

pnpm 支持通过 npm: 协议为包起别名（alias）。一个依赖在 package.json 里叫什么名字，与它实际从 registry 拉取的是哪个包、哪个版本，可以完全解耦。这带来三类核心能力：

1. 同名包多版本并存：例如同时安装 lodash 3.x 和 4.x，以 lodash3、lodash4 两个名字共存；
2. 用 Fork 或替代品替换原包：上游停更或出问题时，把 original-pkg 指向自己的 fork，调用方代码零改动；
3. 顶替弃用包：如将已废弃的 request 指向社区维护的 @cypress/request。

在 AIRI 的技能索引文档 中，别名被归入 pnpm Features 的一类，与 Catalogs、Overrides、Patches 并列：

Aliases — Install under custom names (npm:) and registry aliases (namedRegistries)

当前仓库锁定的包管理器版本为 pnpm@11.24.0（见根目录 package.json 的 packageManager 字段），本文描述的行为均基于该版本。

二、基本语法

CLI 形式的别名安装语法：

pnpm add <alias>@npm:<package>@<version>

对应写入 package.json 后，依赖项形如：

{
  "dependencies": {
    "<alias>": "npm:<package>@<version>"
  }
}

左侧的 <alias> 是项目内 import 时使用的名字，右侧 npm:<package>@<version> 才是真正的包来源与版本约束。

三、多版本并存：AIRI 的 Spine 运行时案例

3.1 文档给出的标准示例

同一包的不同版本可以并行安装：

{
  "dependencies": {
    "lodash3": "npm:lodash@3",
    "lodash4": "npm:lodash@4"
  }
}

使用方式：

import lodash3 from 'lodash3'
import lodash4 from 'lodash4'

3.2 AIRI 仓库中的真实落地：spine-webgl 4.0 / 4.1 / 4.2

AIRI 的 stage-ui-spine 包 需要同时支持 Spine 4.0、4.1、4.2 三个大版本的骨骼动画模型，而 @esotericsoftware/spine-webgl 不同大版本的 runtime API 不兼容，无法只用一份。解决方案正是别名：在 pnpm-workspace.yaml 的 catalog 中定义三个条目：

catalog:
  '@esotericsoftware/spine-webgl': ~4.2.0
  '@esotericsoftware/spine-webgl-4-0': npm:@esotericsoftware/spine-webgl@~4.0.31
  '@esotericsoftware/spine-webgl-4-1': npm:@esotericsoftware/spine-webgl@~4.1.56

这里能看到两个要点：

• 别名名本身就是描述性命名（spine-webgl-4-0、spine-webgl-4-1），一眼看出对应哪个版本，符合文档中 "Clear naming" 的最佳实践；
• 别名定义在 catalog 中而非散落在各包，子包 stage-ui-spine 的 package.json 只需写 "catalog:" 即可引用，保持了 monorepo 版本集中管理：

"dependencies": {
  "@esotericsoftware/spine-webgl": "catalog:",
  "@esotericsoftware/spine-webgl-4-0": "catalog:",
  "@esotericsoftware/spine-webgl-4-1": "catalog:",
  ...
}

3.3 运行时按版本动态加载

别名只是"装得下"，还需要"用得对"。spine-runtime.ts 根据检测到的骨骼版本，动态 import 对应的别名包：

export async function loadSpineRuntime(version: SpineVersion): Promise<typeof import('@esotericsoftware/spine-webgl')> {
  switch (version) {
    case '4.0':
      return await import('@esotericsoftware/spine-webgl-4-0') as unknown as typeof import('@esotericsoftware/spine-webgl')
    case '4.1':
      return await import('@esotericsoftware/spine-webgl-4-1') as unknown as typeof import('@esotericsoftware/spine-webgl')
    case '4.2':
      return await import('@esotericsoftware/spine-webgl')
  }
}

从源码结构看，这里用 as unknown as typeof import('@esotericsoftware/spine-webgl') 做类型断言，把三个版本的模块统一收敛到 4.2 类型的对外签名——因为各版本对外 API 形状相近但并非类型完全一致。

3.4 lockfile 中的解析证据

pnpm-lock.yaml 记录了别名的最终解析结果，catalog 区块中：

'@esotericsoftware/spine-webgl-4-0':
  specifier: npm:@esotericsoftware/spine-webgl@~4.0.31
  version: 4.0.31
'@esotericsoftware/spine-webgl-4-1':
  specifier: npm:@esotericsoftware/spine-webgl@~4.1.56
  version: 4.1.56

子包依赖区块（pnpm-lock.yaml）进一步确认了别名条目确实解析到目标包的对应版本：

packages/stage-ui-spine:
  dependencies:
    '@esotericsoftware/spine-webgl':
      specifier: 'catalog:'
      version: 4.2.119
    '@esotericsoftware/spine-webgl-4-0':
      specifier: 'catalog:'
      version: '@esotericsoftware/spine-webgl@4.0.31'
    '@esotericsoftware/spine-webgl-4-1':
      specifier: 'catalog:'
      version: '@esotericsoftware/spine-webgl@4.1.56'

version 字段中显示的 @esotericsoftware/spine-webgl@4.0.31 明确说明：node_modules 里名为 spine-webgl-4-0 的目录，实际内容是 spine-webgl@4.0.31 这个包。这就是别名机制在 lockfile 层面的完整链路。

四、用 Fork 替换原包

当上游包出现问题时，可以把依赖名指向一个 API 兼容的 fork 或替代品：

{
  "dependencies": {
    "original-pkg": "npm:my-fork@^1.0.0"
  }
}

此后所有 import 'original-pkg' 的代码都会解析到 my-fork，调用方不需要任何改动——这是别名做"无感替换"的关键价值。

AIRI 中有一个直接印证：node-pty 在 catalog 中被替换为维护更积极的 fork（pnpm-workspace.yaml）：

catalog:
  node-pty: npm:@lydell/node-pty@^1.2.0-beta.15

仓库中所有写 import ... from 'node-pty' 的模块，实际运行的都是 @lydell/node-pty 的代码。

五、顶替弃用包与 scoped/unscoped 互换

5.1 顶替弃用包

官方文档给出的经典案例是把已停维护的 request 指向社区续作：

{
  "dependencies": {
    "request": "npm:@cypress/request@^3.0.0"
  }
}

5.2 scoped 与 unscoped 互换

别名还能跨越"作用域"边界，既可以把无 scope 的名字映射到 scoped 包，也可以反过来：

{
  "dependencies": {
    "vue": "npm:@anthropic/vue@^3.0.0",
    "@myorg/utils": "npm:lodash@^4.17.21"
  }
}

5.3 AIRI 的批量弃用包替换：axios 与 @nolyfill

AIRI 的 pnpm-workspace.yaml 在 overrides 区块中使用 npm: 别名做了多组全局替换：

overrides:
  '@types/hast': 'catalog:'
  array-flatten: npm:@nolyfill/array-flatten@^1.0.44
  axios: npm:feaxios@^0.0.23
  'eslint-plugin-sonarjs>typescript': 'catalog:'
  hono: 4.13.3
  is-core-module: npm:@nolyfill/is-core-module@^1.0.39
  isarray: npm:@nolyfill/isarray@^1.0.44
  onnxruntime-web: npm:onnxruntime-web@^1.27.0
  safe-buffer: npm:@nolyfill/safe-buffer@^1.0.44
  safer-buffer: npm:@nolyfill/safer-buffer@^1.0.44
  side-channel: npm:@nolyfill/side-channel@^1.0.44
  string.prototype.matchall: npm:@nolyfill/string.prototype.matchall@^1.0.44

其中 axios: npm:feaxios@^0.0.23 就是"用替代品替换原包"的实例：workspace 内所有直接依赖 axios 的代码，运行时实际加载 feaxios。仓库代码里也留有对应的踩坑记录——apps/stage-web/vite.config.ts 与 apps/stage-pocket/vite.config.ts 中均有注释说明某插件内置 downloader 存在 feaxios 相关 bug，于是改为优先使用系统 mkcert 命令，侧面印证了 fork 替换后仍需关注兼容边界。

@nolyfill/* 系列则是把 isarray、safe-buffer、side-channel 等老依赖统一顶替为 nolyfill 组织的维护版；根目录 package.json 甚至提供了配套的 nolyfill 脚本（pnpm dlx nolyfill）用于批量修复。

六、CLI 使用方式

6.1 以别名添加

# 以别名安装 lodash
pnpm add lodash4@npm:lodash@4

# 以原名安装 fork
pnpm add request@npm:@cypress/request

6.2 一次添加多个版本

pnpm add react17@npm:react@17 react18@npm:react@18

七、与 TypeScript 的配合

别名包同样需要类型解析。文档给出两种做法。

方式一：tsconfig paths 映射

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "lodash3": ["node_modules/lodash3"],
      "lodash4": ["node_modules/lodash4"]
    }
  }
}

方式二：给 @types 包也起别名

{
  "devDependencies": {
    "@types/lodash3": "npm:@types/lodash@3",
    "@types/lodash4": "npm:@types/lodash@4"
  }
}

AIRI 的 spine 案例是另一条路径：三个版本共享同一份 typeof import('@esotericsoftware/spine-webgl') 类型签名，通过 as unknown as 断言复用（见 spine-runtime.ts），在"API 形状相近、类型不完全等价"的场景下更省事，但也意味着类型检查无法发现被断言掩盖的 API 差异，需要靠运行时测试兜底。

八、与 overrides 组合：全局强制替换

别名作用于"当前包声明的依赖"，而 overrides 能把一个包在全依赖树（含传递依赖）中强制替换为别名目标。在 pnpm-workspace.yaml 中（pnpm 10+ 的推荐位置）：

# pnpm-workspace.yaml
overrides:
  "underscore": "npm:lodash@^4.17.21"

这会把所有 underscore 引入（包括来自第三方依赖的内部引用）全部替换为 lodash。AIRI 上文展示的 axios → feaxios、isarray → @nolyfill/isarray 等正是该机制的实战形态。

文档的最佳实践也强调：全局替换优先用 overrides，而不是别名——别名适合"本地换一个名字用"，overrides 适合"整棵树都换掉"。二者定位不同，AIRI 仓库恰好两种都用到了：catalog 别名（spine 多版本）+ workspace overrides（axios/nolyfill 批量替换）。

九、Git 与本地路径别名

别名可以搭配任意合法的 pnpm 来源说明符，不限于 registry 包：

{
  "dependencies": {
    "my-fork": "npm:user/repo#commit",
    "local-pkg": "file:../local-package"
  }
}

即可以从 Git 仓库的指定 commit 或本地目录安装，并以自定义名字引用，便于在正式发版前验证 fork 或本地实验包。

十、区分：namedRegistries 是"注册表别名"，不是包别名

文档特别强调：namedRegistries 前缀选择的是包从哪个 registry 获取，与 npm: 包别名是两码事：

# pnpm-workspace.yaml
namedRegistries:
  work: https://npm.work.example.com/

pnpm add work:@corp/lib@^2.0.0   # 针对 work 注册表解析 @corp/lib

内置的 gh: 前缀指向 GitHub Packages，其认证复用 .npmrc 中按 URL 配置的凭据条目。AIRI 仓库当前未配置 namedRegistries，其 pnpm-workspace.yaml 顶部配置的是 catalogMode、minimumReleaseAge（供应链安全，与 features-supply-chain-security 文档 呼应）、packages、overrides、patchedDependencies、catalog、allowBuilds、packageExtensions 等区块——可见别名只是 pnpm 工作区配置能力矩阵中的一环，常与 catalog、overrides、patches 协同使用。

十一、最佳实践（继承自技能文档）

1. 清晰的命名：用能表达用途的别名

   "lodash-legacy": "npm:lodash@3",
   "lodash-modern": "npm:lodash@4"
   

   AIRI 的 spine-webgl-4-0 / spine-webgl-4-1 命名即属此类，见名知版本。
2. 记录别名动机：在文档或注释中解释为什么存在这个别名（例如 fork 解决了什么问题），避免后来者误删。
3. 全局替换优先用 overrides：需要替换整棵依赖树中的某个包时，用 pnpm-workspace.yaml 的 overrides 而非别名。
4. 充分测试：别名指向的包（尤其 fork、弃用包替代品）可能存在细微行为差异，AIRI 中 feaxios 替换 axios 后仍需为插件 downloader 单独打 workaround，即为例证。

十二、小结：一条完整的别名链路

以 AIRI 仓库为例，npm: 别名从声明到运行时的完整链路是：

1. 声明：在 pnpm-workspace.yaml 的 catalog 中定义 '@esotericsoftware/spine-webgl-4-0': npm:@esotericsoftware/spine-webgl@~4.0.31；
2. 引用：子包 stage-ui-spine/package.json 以 "catalog:" 引用别名；
3. 解析：pnpm-lock.yaml 记录别名 → @esotericsoftware/spine-webgl@4.0.31 的固定解析结果；
4. 消费：spine-runtime.ts 按骨骼版本动态 import 别名包并做类型收敛。

掌握这条链路后，你就能在 monorepo 中放心使用 npm: 别名：它既能像 spine 案例那样"多版本并存"，也能像 axios/nolyfill 案例那样配合 overrides 完成"整树替换"，而 lockfile 与源码中的实证都保证了替换行为可追溯、可验证。