5月28日 01:01

pnpm 的 .npmrc 配置有哪些常用选项？

pnpm 通过 .npmrc 文件管理配置，支持项目级、用户级、全局级三个层级，项目级优先级最高。掌握常用配置不仅影响日常开发效率，也是 Monorepo 和 CI/CD 环境的必备知识。

注册表与镜像源

最基础的配置是切换包下载源。国内开发者在项目根目录 .npmrc 中配置淘宝镜像几乎是标配：

ini
registry=https://registry.npmmirror.com/

企业私有包则通过作用域隔离：

ini
@mycompany:registry=https://npm.mycompany.com/

这样 @mycompany/xxx 包走私有源，其余走公共源，互不干扰。

依赖安装策略

几个配置项直接影响安装行为和依赖结构，也是面试高频考点：

strict-peer-dependencies — 设为 true 时，peer 依赖不满足会直接报错中断安装。默认 false 只警告。在大型 Monorepo 中建议开启，避免隐式依赖缺失导致的运行时问题。

ini
strict-peer-dependencies=true

auto-install-peers — 自动安装缺失的 peer 依赖。和 strict-peer-dependencies 互斥，二选一：要么严格校验，要么自动补全。

ini
auto-install-peers=true

shamefully-hoist — 提升所有依赖到根目录 node_modules，模拟 npm 的扁平结构。会破坏 pnpm 严格的依赖隔离，仅在遇到不兼容的第三方库（如依赖隐式引用）时才启用：

ini
shamefully-hoist=true

存储与缓存

pnpm 的核心优势是内容寻址存储（content-addressable store），全局只存一份，各项目通过硬链接引用：

ini
# 自定义 store 位置（默认 ~/.local/share/pnpm/store）
store-dir=/path/to/custom/store

# 包元数据缓存目录
cache-dir=/path/to/custom/cache

# 状态文件目录（pnpm-state.json）
state-dir=/path/to/custom/state

在 CI 环境中可以把 store 挂载到缓存卷，避免每次重新下载：

ini
store-dir=/tmp/pnpm-store

网络与代理

网络配置在团队协作和企业环境中常用：

ini
# 并发请求数（默认 16，网络好可调大）
network-concurrency=32

# 单次请求超时（毫秒，默认 60000）
fetch-timeout=60000

# 重试次数（默认 2）
fetch-retries=3

企业内网需要代理时：

ini
proxy=http://proxy.company.com:8080
https-proxy=http://proxy.company.com:8080
no-proxy=localhost,127.0.0.1,internal.company.com

Workspace（Monorepo）配置

pnpm Workspace 是 Monorepo 的核心能力，相关配置决定了包之间的链接行为：

ini
# 允许 workspace 包互相链接
link-workspace-packages=true

# 优先使用 workspace 本地版本而非 registry 版本
prefer-workspace-packages=true

# pnpm add 时自动添加 workspace: 协议前缀
save-workspace-protocol=true

link-workspace-packages=true 配合 prefer-workspace-packages=true 后，workspace 内的包改动能即时反映到依赖方，无需手动 link。

CI/CD 推荐配置

CI 环境对确定性和速度有严格要求，推荐以下组合：

ini
# 不修改 lockfile，确保构建可复现
frozen-lockfile=true

# 优先使用本地缓存
prefer-offline=true

# 静默输出减少日志
reporter=silent

# 严格 peer 依赖检查
strict-peer-dependencies=true

frozen-lockfile=true 是 CI 的关键配置——如果 pnpm-lock.yaml 与 package.json 不一致，直接报错而非自动更新，防止不可复现的构建。

Node.js 版本管理

pnpm 内置了 Node.js 版本管理能力，无需 nvm：

ini
# 指定项目使用的 Node.js 版本
use-node-version=20.11.0

# 强制 engines 字段校验
engine-strict=true

国内下载 Node.js 较慢时，配置镜像：

ini
node-mirror:release=https://npmmirror.com/mirrors/node/

安全相关

ini
# 禁止执行 install 脚本（防范供应链攻击）
ignore-scripts=true

# SSL 证书校验（默认 true，不要轻易关闭）
strict-ssl=true

ignore-scripts=true 能阻断恶意包的 postinstall 脚本执行，但会导致部分依赖（如 esbuild、sharp）安装后需要手动 rebuild。

配置优先级

多个 .npmrc 同时存在时，优先级从高到低：

命令行参数（--registry=xxx）
环境变量（npm_config_registry）
项目级 .npmrc（项目根目录）
用户级 ~/.npmrc
全局 /etc/npmrc
pnpm 内置默认值

项目级配置优先级最高，意味着团队可以通过提交项目 .npmrc 到 Git 来统一配置，个人偏好放在 ~/.npmrc 中。

查看与管理配置

bash
# 查看所有生效配置
pnpm config list

# 查看某项配置
pnpm config get registry

# 设置（写入用户级 .npmrc）
pnpm config set registry https://registry.npmmirror.com/

# 删除
pnpm config delete registry

.npmrc 文件支持环境变量替换，语法为 ${NAME} 或带默认值 ${NAME:-fallback}，适合在 CI 中动态注入认证令牌：

ini
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

标签：PNPM