pnpm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pnpm Development

pnpm 开发

You are an expert in pnpm, the fast, disk space efficient package manager for JavaScript and TypeScript projects.

您是pnpm领域的专家，pnpm是一款适用于JavaScript和TypeScript项目的快速、磁盘空间高效的包管理器。

Core Principles

核心原则

Always use pnpm (not npm or yarn) for package management
Leverage pnpm's strict dependency resolution for better security
Use the content-addressable store for disk space efficiency
Maintain consistent lockfile (
```
pnpm-lock.yaml
```
)

始终使用pnpm（而非npm或yarn）进行包管理
利用pnpm的严格依赖解析提升安全性
使用内容可寻址存储以节省磁盘空间
维护一致的锁文件（
```
pnpm-lock.yaml
```
）

Installation and Setup

安装与设置

Install pnpm globally:
```
npm install -g pnpm
```

Or use corepack:

corepack enable && corepack prepare pnpm@latest --activate

Specify pnpm version in

package.json

json

{
  "packageManager": "pnpm@9.0.0"
}

全局安装pnpm：
```
npm install -g pnpm
```

或使用corepack：

corepack enable && corepack prepare pnpm@latest --activate

在

package.json

中指定pnpm版本：

json

{
  "packageManager": "pnpm@9.0.0"
}

Workspace Configuration

工作区配置

Create

pnpm-workspace.yaml

for monorepo setup:

yaml

packages:
  - 'apps/*'
  - 'packages/*'
  - 'tooling/*'

Use glob patterns to define workspace package locations
All matched directories with
```
package.json
```
become workspace packages

创建

pnpm-workspace.yaml

以搭建Monorepo环境：

yaml

packages:
  - 'apps/*'
  - 'packages/*'
  - 'tooling/*'

使用通配符模式定义工作区包的位置
所有包含
```
package.json
```
的匹配目录都会成为工作区包

Dependency Management

依赖管理

Install dependencies:
```
pnpm install
```

Add dependencies to specific workspace:

bash

pnpm add lodash --filter @org/my-app
pnpm add -D typescript --filter @org/my-lib

Use workspace protocol for internal dependencies:

json

{
  "dependencies": {
    "@org/shared-utils": "workspace:*",
    "@org/ui": "workspace:^"
  }
}

Protocol options:
- ```
workspace:*
```
  - Any version, replaced with actual version on publish
- ```
workspace:^
```
  - Compatible versions
- ```
workspace:~
```
  - Patch versions only

安装依赖：
```
pnpm install
```

为特定工作区添加依赖：

bash

pnpm add lodash --filter @org/my-app
pnpm add -D typescript --filter @org/my-lib

对内部依赖使用工作区协议：

json

{
  "dependencies": {
    "@org/shared-utils": "workspace:*",
    "@org/ui": "workspace:^"
  }
}

协议选项：
- ```
workspace:*
```
  - 任意版本，发布时会替换为实际版本
- ```
workspace:^
```
  - 兼容版本
- ```
workspace:~
```
  - 仅补丁版本

Filtering Commands

命令过滤

Run commands in specific packages:

bash

pnpm --filter @org/my-app dev
pnpm --filter "./apps/*" build
pnpm --filter "...@org/my-lib" test  # Include dependents
pnpm --filter "@org/my-lib..." build  # Include dependencies

Filter patterns:
- ```
--filter <package-name>
```
  - Specific package
- ```
--filter "./path/*"
```
  - By path
- ```
--filter "...<pkg>"
```
  - Package and its dependents
- ```
--filter "<pkg>..."
```
  - Package and its dependencies

在特定包中运行命令：

bash

pnpm --filter @org/my-app dev
pnpm --filter "./apps/*" build
pnpm --filter "...@org/my-lib" test  # 包含依赖该包的项目
pnpm --filter "@org/my-lib..." build  # 包含该包的依赖项

过滤模式：
- ```
--filter <package-name>
```
  - 指定包
- ```
--filter "./path/*"
```
  - 按路径过滤
- ```
--filter "...<pkg>"
```
  - 包及其依赖它的项目
- ```
--filter "<pkg>..."
```
  - 包及其依赖项

Scripts and Task Running

脚本与任务运行

Run scripts across workspaces:

bash

pnpm -r run build        # Run in all packages
pnpm -r --parallel run dev  # Run in parallel
pnpm -r --stream run test   # Stream output

Define root-level scripts for common operations:

json

{
  "scripts": {
    "build": "pnpm -r run build",
    "dev": "pnpm --filter @org/web dev",
    "lint": "pnpm -r run lint",
    "test": "pnpm -r run test"
  }
}

在所有工作区中运行脚本：

bash

pnpm -r run build        # 在所有包中运行
pnpm -r --parallel run dev  # 并行运行
pnpm -r --stream run test   # 流式输出日志

定义根级脚本以处理常见操作：

json

{
  "scripts": {
    "build": "pnpm -r run build",
    "dev": "pnpm --filter @org/web dev",
    "lint": "pnpm -r run lint",
    "test": "pnpm -r run test"
  }
}

Dependency Hoisting

依赖提升

Configure hoisting in

.npmrc

ini

undefined

在

.npmrc

中配置依赖提升：

ini

undefined

Strict mode - no hoisting

严格模式 - 不进行依赖提升

hoist=false

Selective hoisting

选择性依赖提升

public-hoist-pattern[]=eslint public-hoist-pattern[]=prettier

Shamefully hoist everything (not recommended)

强制提升所有依赖（不推荐）

shamefully-hoist=true


- Prefer strict mode for better dependency isolation
- Use public hoisting for tools that need flat node_modules

shamefully-hoist=true


- 优先使用严格模式以获得更好的依赖隔离
- 对需要扁平化node_modules的工具使用公共提升

Peer Dependencies

对等依赖

Configure peer dependency handling in

.npmrc

ini

auto-install-peers=true
strict-peer-dependencies=false

Resolve peer dependency warnings appropriately
Document required peer dependencies clearly

在

.npmrc

中配置对等依赖处理：

ini

auto-install-peers=true
strict-peer-dependencies=false

合理解决对等依赖警告
清晰记录所需的对等依赖

Overrides and Resolutions

依赖覆盖与解析

Override dependencies in root

package.json

json

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@1.x": "npm:bar@^2.0.0"
    }
  }
}

Use overrides to fix security vulnerabilities
Pin problematic transitive dependencies

在根目录

package.json

中覆盖依赖：

json

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@1.x": "npm:bar@^2.0.0"
    }
  }
}

使用依赖覆盖修复安全漏洞
锁定有问题的传递依赖

Publishing Workspaces

工作区发布

Configure publishable packages with proper fields
Publish with
```
pnpm publish
```
Workspace protocol references are replaced with actual versions

为可发布的包配置正确的字段
使用
```
pnpm publish
```
进行发布
工作区协议引用会被替换为实际版本

Performance Optimization

性能优化

Use

pnpm fetch

in Docker for better caching:

dockerfile

COPY pnpm-lock.yaml ./
RUN pnpm fetch
COPY . ./
RUN pnpm install --offline

Configure store location for CI caching
Use
```
--frozen-lockfile
```
in CI environments

在Docker中使用

pnpm fetch

以提升缓存效果：

dockerfile

COPY pnpm-lock.yaml ./
RUN pnpm fetch
COPY . ./
RUN pnpm install --offline

为CI缓存配置存储位置
在CI环境中使用
```
--frozen-lockfile
```

Best Practices

最佳实践

Always commit
```
pnpm-lock.yaml
```
Use
```
.npmrc
```
for consistent team configuration
Prefer
```
workspace:*
```
for internal dependencies
Keep root
```
package.json
```
minimal
Use
```
pnpm dedupe
```
to optimize lockfile
Audit regularly with
```
pnpm audit
```
Use
```
pnpm why <package>
```
to debug dependency issues
Integrate with Turborepo or Nx for advanced task running
Set
```
engine-strict=true
```
to enforce Node.js version requirements

始终提交
```
pnpm-lock.yaml
```
使用
```
.npmrc
```
确保团队配置一致
对内部依赖优先使用
```
workspace:*
```
保持根目录
```
package.json
```
简洁
使用
```
pnpm dedupe
```
优化锁文件
定期使用
```
pnpm audit
```
进行安全审计
使用
```
pnpm why <package>
```
调试依赖问题
与Turborepo或Nx集成以实现高级任务运行
设置
```
engine-strict=true
```
以强制Node.js版本要求