skillhub-047-pnpm/references/core-config.md

name, description

name	description
pnpm-configuration	通过 pnpm-workspace.yaml 和 .npmrc 设置进行配置的选项

pnpm 配置

pnpm 使用两个主要的配置文件：pnpm-workspace.yaml 用于工作区（workspace）和 pnpm 特有设置，以及 .npmrc 用于 npm 兼容和 pnpm 特有设置。

pnpm-workspace.yaml

推荐用于放置 pnpm 特有配置的位置。置于项目根目录。

# 定义工作区包
packages:
  - 'packages/*'
  - 'apps/*'
  - '!**/test/**'  # 排除模式

# 共享依赖版本的目录（Catalog）
catalog:
  react: ^18.2.0
  typescript: ~5.3.0

# 用于不同依赖组的命名目录（Named Catalogs）
catalogs:
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

# 覆盖解析（推荐位置）
overrides:
  lodash: ^4.17.21
  'foo@^1.0.0>bar': ^2.0.0

# pnpm 设置（.npmrc 的替代方案）
settings:
  auto-install-peers: true
  strict-peer-dependencies: false
  link-workspace-packages: true
  prefer-workspace-packages: true
  shared-workspace-lockfile: true

.npmrc 设置

pnpm 从 .npmrc 文件中读取设置。可在项目根目录或用户主目录创建。

常用 pnpm 设置

# 自动安装对等依赖（peer dependencies）
auto-install-peers=true

# 在对等依赖问题上失败
strict-peer-dependencies=false

# 依赖提升模式
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
shamefully-hoist=false

# 存储位置
store-dir=~/.pnpm-store

# 虚拟存储位置
virtual-store-dir=node_modules/.pnpm

# 锁定文件设置
lockfile=true
prefer-frozen-lockfile=true

# 副作用缓存（加速重新构建）
side-effects-cache=true

# 注册表设置
registry=https://registry.npmjs.org/
@myorg:registry=https://npm.myorg.com/

工作区设置

# 链接工作区包
link-workspace-packages=true

# 优先使用工作区包而非注册表
prefer-workspace-packages=true

# 所有包共享单个锁定文件
shared-workspace-lockfile=true

# 工作区依赖的保存前缀
save-workspace-protocol=rolling

Node.js 设置

# 使用特定的 Node.js 版本
use-node-version=20.10.0

# Node.js 版本文件
node-version-file=.nvmrc

# 管理包管理器版本
manage-package-manager-versions=true

安全设置

# 忽略特定脚本
ignore-scripts=false

# 允许特定的构建脚本
onlyBuiltDependencies[]=esbuild
onlyBuiltDependencies[]=sharp

# 缺失对等依赖的包扩展
package-extensions[foo@1].peerDependencies.bar=*

配置优先级

设置按以下顺序读取（后者覆盖前者）：

1. /etc/npmrc - 全局配置
2. ~/.npmrc - 用户配置
3. <project>/.npmrc - 项目配置
4. 环境变量：npm_config_<key>=<value>
5. pnpm-workspace.yaml 的 settings 字段

环境变量

# 通过环境变量设置配置
npm_config_registry=https://registry.npmjs.org/

# pnpm 特有的环境变量
PNPM_HOME=~/.local/share/pnpm

Package.json 字段

pnpm 从 package.json 中读取特定字段：

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*"],
      "allowedVersions": {
        "react": "17 || 18"
      }
    },
    "neverBuiltDependencies": ["fsevents"],
    "onlyBuiltDependencies": ["esbuild"],
    "allowedDeprecatedVersions": {
      "request": "*"
    },
    "patchedDependencies": {
      "express@4.18.2": "patches/express@4.18.2.patch"
    }
  }
}

与 npm/yarn 的主要区别

1. 默认严格：不存在幽灵依赖（phantom dependencies）
2. 工作区协议：本地包使用 workspace:*
3. 目录（Catalogs）：集中化版本管理
4. 内容寻址存储：跨项目共享