---
name: pnpm-aliases
description: 以自定义名称安装包，用于版本管理、分支维护或替代方案
---

# pnpm 别名

pnpm 通过 `npm:` 协议支持包别名。这使你可以用不同名称安装包、使用同一包的多个版本，或替换包。

## 基本语法

```bash
pnpm add <别名>@npm:<包名>@<版本>
```

在 `package.json` 中：
```json
{
  "dependencies": {
    "<别名>": "npm:<包名>@<版本>"
  }
}
```

## 使用场景

### 同一包的多个版本

并排安装不同版本：

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

使用方式：
```js
import lodash3 from 'lodash3'
import lodash4 from 'lodash4'
```

### 用分支替换包

用分支或替代包替换原包：

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

所有 `original-pkg` 的 import 都会解析到 `my-fork`。

### 替换已废弃的包

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

### 作用域包与无作用域包互转

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

## CLI 用法

### 添加别名

```bash
# 以别名添加 lodash
pnpm add lodash4@npm:lodash@4

# 以原包名添加分支
pnpm add request@npm:@cypress/request
```

### 添加多个版本

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

## 搭配 TypeScript

若需为别名解析类型，你可能需要配置 TypeScript：

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

或者将 `@types` 包与别名搭配使用：

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

## 结合 overrides 使用

强制所有传递依赖使用某个别名：

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

这会将所有 `underscore` 的引用（包括依赖包中的）替换为 lodash。

## Git 与本地别名

别名支持任何有效的 pnpm 标识符：

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

## 最佳实践

1. **命名清晰**：使用描述性别名，表明用途
   ```json
   "lodash-legacy": "npm:lodash@3"
   "lodash-modern": "npm:lodash@4"
   ```

2. **记录别名**：添加注释或文档说明别名存在的原因

3. **全局替换优先使用 overrides**：如果想在所有地方替换某个包，应使用 overrides 而非别名

4. **全面测试**：别名化包可能存在细微的行为差异

<!--
来源参考：
- https://pnpm.io/aliases
-->