在 macOS 上查看和修改 npm、yarn 和 pnpm 的全局配置项

下面我将详细说明如何在 macOS 上查看和修改 npm、yarn 和 pnpm 的全局安装地址与缓存地址，并列举常用配置项及其应用场景：

一、全局安装地址与缓存地址管理

1. npm

查看全局安装路径 ：

bash 复制代码

npm root -g
# 默认：/usr/local/lib/node_modules

查看缓存路径 ：
bash 复制代码
```
npm config get cache
# 默认：~/.npm
```

修改全局安装路径 ：

bash 复制代码

npm config set prefix ~/.npm-global
# 修改后需添加到 PATH：
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

修改缓存路径 ：
bash 复制代码
```
npm config set cache ~/custom-npm-cache
```

2. yarn (classic)

查看全局安装路径 ：

bash 复制代码

yarn global dir
# 默认：~/.config/yarn/global

查看缓存路径 ：

bash 复制代码

yarn cache dir
# 默认：~/Library/Caches/Yarn

修改全局安装路径 ：

bash 复制代码

yarn config set global-folder ~/custom-yarn-global

修改缓存路径 ：

bash 复制代码

yarn config set cache-folder ~/custom-yarn-cache

3. pnpm

查看全局存储路径 ：

bash 复制代码

pnpm store path
# 默认：~/Library/pnpm/store/v3

查看缓存路径 ：

bash 复制代码

pnpm config get store-dir
# 与全局存储相同

修改全局存储路径 ：

bash 复制代码

pnpm config set store-dir /Volumes/SSD/pnpm-store

注意：pnpm 的全局包安装位置独立配置：
bash 复制代码
# 查看全局 bin 目录
pnpm bin -g
# 修改全局包位置
pnpm config set global-bin-dir ~/.pnpm-global

二、常用配置项详解（以 pnpm 为主）

1. 依赖解析类配置

配置项	作用	应用场景	查看/修改
`resolution-strategy`	依赖版本冲突解决策略	解决 peerDependencies 冲突	`pnpm config set resolution-strategy deepest`
`strict-peer-dependencies`	严格 peerDeps 检查（默认 true）	兼容老旧项目时关闭	`pnpm config set strict-peer-dependencies false`
`public-hoist-pattern[]`	提升指定依赖到根 node_modules	解决工具链插件依赖问题	在 .npmrc 添加 `public-hoist-pattern[]=babel`
`shamefully-hoist`	全量提升依赖（模拟扁平化）	兼容严重依赖幽灵依赖的项目	`pnpm config set shamefully-hoist true`

2. 网络与存储类配置

配置项	作用	应用场景	查看/修改
`registry`	包镜像源	切换淘宝源加速下载	`pnpm config set registry https://registry.npmmirror.com`
`store-dir`	全局存储位置	SSD 优化/CI 缓存复用	`pnpm config set store-dir /shared/store`
`network-concurrency`	网络请求并发数	解决网络受限环境下载失败	`pnpm config set network-concurrency 1`
`fetch-timeout`	单包下载超时时间（毫秒）	弱网环境增加超时容忍度	`pnpm config set fetch-timeout 600000`

3. 安装行为类配置

配置项	作用	应用场景	查看/修改
`auto-install-peers`	自动安装 peerDeps	简化 peer 依赖管理	`pnpm config set auto-install-peers true`
`save-prefix`	版本号前缀（^/~）	控制版本更新策略	`pnpm config set save-prefix="~"`
`package-import-method`	安装方式（硬链/复制）	Docker 环境需改为复制	`pnpm config set package-import-method copy`
`prefer-frozen-lockfile`	优先使用 lock 文件	CI 环境确保一致性	`pnpm config set prefer-frozen-lockfile true`

三、配置查看与管理技巧

1. 查看所有配置

bash 复制代码

# npm
npm config list

# yarn
yarn config list

# pnpm
pnpm config list

2. 多级配置优先级

项目级 ：项目根目录的 .npmrc
用户级 ：~/.npmrc
全局级 ：/usr/local/etc/npmrc
内置默认：npm/pnpm 内置配置

3. 临时覆盖配置

bash 复制代码

# 单次安装使用特定 registry
pnpm install --registry=https://registry.example.com

# 临时禁用 peerDeps 检查
pnpm install --strict-peer-dependencies=false

四、典型场景配置示例

场景 1：企业内网开发

bash 复制代码

# ~/.npmrc
registry=http://internal-npm-registry.example.com
strict-peer-dependencies=false
fetch-retries=5

`strict-peer-dependencies=false`

作用：关闭 peerDependencies 的严格检查
使用场景：
- 当项目依赖的包声明了不兼容的 peerDependencies 时
- 老项目升级遇到无法解决的 peerDeps 冲突
- 临时解决 UNMET PEER DEPENDENCY 错误

典型问题案例：

kotlin 复制代码

# 安装时出现错误：
ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies
[email protected] requires a peer of typescript@>=4.6 but none was installed

解决方案：

bash 复制代码

echo "strict-peer-dependencies=false" >> .npmrc
pnpm install

`fetch-retries=5`

作用：设置网络请求失败时的重试次数
使用场景：
- 不稳定的网络环境（如移动热点）
- 企业VPN限制导致间歇性下载失败
- 大型依赖包（>100MB）下载超时

典型问题案例：

arduino 复制代码

FetchError: request to https://registry.npmjs.org/lodash failed, reason: socket hang up

推荐配置：

arduino 复制代码

pnpm config set fetch-retries 5
pnpm config set fetch-timeout 300000  # 5分钟超时

场景 2：CI/CD 优化

bash 复制代码

# .npmrc
store-dir=/ci/shared-store
prefer-frozen-lockfile=true
package-import-method=copy  # Docker 兼容

`prefer-frozen-lockfile=true`

作用：优先使用现有 lock 文件，不自动更新
使用场景：
- CI/CD 流水线确保构建一致性
- 生产环境部署
- 审计依赖变更时
典型问题案例 ：

CI 构建时因 lock 文件自动更新导致依赖版本变化，引发生产事故

工作流示例：

bash 复制代码

# CI 脚本
pnpm install --frozen-lockfile  # 等同于 prefer-frozen-lockfile=true

`package-import-method=copy`

作用：使用复制替代硬链接安装依赖
使用场景：
- Docker 多阶段构建
- Windows 系统防病毒软件锁定文件
- NFS 共享文件系统

典型问题案例：

bash 复制代码

# Docker 构建时报错
Error: EBUSY: resource busy or locked, unlink...

解决方案：

dockerfile

go 复制代码

# Dockerfile
RUN pnpm install --package-import-method=copy

场景 3：解决 Monorepo 依赖问题

bash 复制代码

# 项目根目录 .npmrc
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*babel*
auto-install-peers=true

`public-hoist-pattern[]=babel`

作用：将匹配模式的依赖提升到根 node_modules
使用场景：
- Babel/Webpack 插件找不到依赖
- Jest 测试框架的全局扩展
- ESLint 插件依赖问题

典型问题案例：

arduino 复制代码

Error: Cannot find module '@babel/plugin-transform-runtime'

配置方式：

csharp 复制代码

# .npmrc
public-hoist-pattern[]=*babel*
public-hoist-pattern[]=*jest*

`auto-install-peers=true`

作用：自动安装未声明的 peerDependencies
使用场景：
- 遗留项目缺少 peerDeps 声明
- 快速原型开发
- 减少手动解决 peer 依赖时间

典型问题案例：

sql 复制代码

Warning: [email protected] requires a peer of [email protected] but none was installed

注意：可能隐藏依赖问题，生产项目慎用

五、重要注意事项

路径修改后的权限问题：

bash 复制代码

sudo chown -R $(whoami) ~/.pnpm-store  # 确保用户有权访问

全局包路径冲突解决：
bash 复制代码
```
# 检查全局包冲突
which eslint
# 重置链接
pnpm setup
```
pnpm setup
- 作用：配置 pnpm 环境（存储路径、PATH设置等）
- 使用场景：
  - 首次安装 pnpm 后
  - 更换全局存储位置后
  - 系统升级后环境重置
- 执行效果：
  bash 复制代码
```
# 典型输出
Setting up pnpm...
Added ~/.pnpm-store/bin to PATH in ~/.zshrc
Created global store at /Volumes/SSD/pnpm-store
```
- 推荐使用：
  arduino 复制代码
```
# 安装后立即执行
curl -fsSL https://get.pnpm.io/install.sh | sh -
pnpm setup
```

配置继承陷阱：

bash 复制代码

# 清除项目级配置覆盖
pnpm config delete registry --location=project

`pnpm config delete registry --location=project`

作用：删除项目级 registry 配置
使用场景：
- 切换企业私库到公共库
- 清除过期的仓库配置
- 解决 registry 冲突问题

典型问题案例：

bash 复制代码

# 项目 .npmrc 配置了失效的私库地址
pnpm install
ERROR  GET https://old-registry.example.com/react 404 Not Found

解决方案：

ini 复制代码

# 删除项目级配置
pnpm config delete registry --location=project

# 验证
pnpm config get registry --location=project  # 应返回 undefined

下面我将详细解释每个配置/命令的作用、适用场景以及典型问题解决案例：

配置项解析与应用场景

1. `strict-peer-dependencies=false`

作用：关闭 peerDependencies 的严格检查
使用场景 ：
- 当项目依赖的包声明了不兼容的 peerDependencies 时
- 老项目升级遇到无法解决的 peerDeps 冲突
- 临时解决 UNMET PEER DEPENDENCY 错误

典型问题案例 ：

bash 复制代码

# 安装时出现错误：
ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies
[email protected] requires a peer of typescript@>=4.6 but none was installed

解决方案 ：

bash 复制代码

echo "strict-peer-dependencies=false" >> .npmrc
pnpm install

2. `fetch-retries=5`

作用：设置网络请求失败时的重试次数
使用场景 ：
- 不稳定的网络环境（如移动热点）
- 企业VPN限制导致间歇性下载失败
- 大型依赖包（>100MB）下载超时

典型问题案例 ：

bash 复制代码

FetchError: request to https://registry.npmjs.org/lodash failed, reason: socket hang up

推荐配置 ：

bash 复制代码

pnpm config set fetch-retries 5
pnpm config set fetch-timeout 300000  # 5分钟超时

3. `prefer-frozen-lockfile=true`

作用：优先使用现有 lock 文件，不自动更新
使用场景 ：
- CI/CD 流水线确保构建一致性
- 生产环境部署
- 审计依赖变更时
典型问题案例： CI 构建时因 lock 文件自动更新导致依赖版本变化，引发生产事故

工作流示例 ：

bash 复制代码

# CI 脚本
pnpm install --frozen-lockfile  # 等同于 prefer-frozen-lockfile=true

4. `package-import-method=copy`

作用：使用复制替代硬链接安装依赖
使用场景 ：
- Docker 多阶段构建
- Windows 系统防病毒软件锁定文件
- NFS 共享文件系统

典型问题案例 ：

bash 复制代码

# Docker 构建时报错
Error: EBUSY: resource busy or locked, unlink...

解决方案 ：

dockerfile 复制代码

# Dockerfile
RUN pnpm install --package-import-method=copy

5. `public-hoist-pattern[]=babel`

作用：将匹配模式的依赖提升到根 node_modules
使用场景 ：
- Babel/Webpack 插件找不到依赖
- Jest 测试框架的全局扩展
- ESLint 插件依赖问题

典型问题案例 ：

bash 复制代码

Error: Cannot find module '@babel/plugin-transform-runtime'

配置方式 ：

ini 复制代码

# .npmrc
public-hoist-pattern[]=*babel*
public-hoist-pattern[]=*jest*

6. `auto-install-peers=true`

作用：自动安装未声明的 peerDependencies
使用场景 ：
- 遗留项目缺少 peerDeps 声明
- 快速原型开发
- 减少手动解决 peer 依赖时间

典型问题案例 ：

bash 复制代码

Warning: [email protected] requires a peer of [email protected] but none was installed

注意：可能隐藏依赖问题，生产项目慎用

命令解析与应用场景

1. `pnpm setup`

作用：配置 pnpm 环境（存储路径、PATH设置等）
使用场景 ：
- 首次安装 pnpm 后
- 更换全局存储位置后
- 系统升级后环境重置

执行效果 ：

bash 复制代码

# 典型输出
Setting up pnpm...
Added ~/.pnpm-store/bin to PATH in ~/.zshrc
Created global store at /Volumes/SSD/pnpm-store

推荐使用 ：

bash 复制代码

# 安装后立即执行
curl -fsSL https://get.pnpm.io/install.sh | sh -
pnpm setup

2. `pnpm config delete registry --location=project`

作用：删除项目级 registry 配置
使用场景 ：
- 切换企业私库到公共库
- 清除过期的仓库配置
- 解决 registry 冲突问题

典型问题案例 ：

bash 复制代码

# 项目 .npmrc 配置了失效的私库地址
pnpm install
ERROR  GET https://old-registry.example.com/react 404 Not Found

解决方案 ：

bash 复制代码

# 删除项目级配置
pnpm config delete registry --location=project

# 验证
pnpm config get registry --location=project  # 应返回 undefined

配置优先级管理技巧

1. 多级配置查看

bash 复制代码

# 查看所有层级配置
pnpm config list -l

# 只查看项目级配置
pnpm config list --location=project

2. 配置作用域管理

作用域	标志	配置文件位置
项目级	`--location=project`	./.npmrc
用户级	`--location=user`	~/.npmrc
全局级	`--location=global`	/etc/npmrc

3. 典型配置工作流

graph LR A[遇到问题] --> B{确定问题类型} B -->|依赖解析| C[修改 .npmrc 配置] B -->|环境问题| D[使用 pnpm setup] B -->|网络问题| E[调整 fetch 配置] C --> F[提交 .npmrc 到 Git] D --> G[更新 shell 配置] E --> H[设置企业代理]

最佳实践建议

项目级配置（.npmrc）：

ini 复制代码

# 推荐通用配置
auto-install-peers=true
strict-peer-dependencies=false
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*babel*

提交到版本控制，确保团队一致

用户级配置（~/.npmrc）：
ini 复制代码
```
# 个人开发环境
store-dir=/Volumes/SSD/pnpm-store
fetch-retries=3
```
不提交到版本控制

CI/CD 专用配置：

bash 复制代码

# CI 脚本中动态设置
pnpm config set store-dir ~/.pnpm-store
pnpm config set prefer-frozen-lockfile true
pnpm config set package-import-method copy

问题诊断工具：

bash 复制代码

# 检查配置来源
pnpm config list -l | grep 'registry'

# 检查实际安装路径
pnpm why react --detail

通过合理使用这些配置，可以解决 90% 的依赖管理问题，同时优化开发体验和构建效率。

在 macOS 上查看和修改 npm、yarn 和 pnpm 的全局配置项

一、全局安装地址与缓存地址管理

1. npm

2. yarn (classic)

3. pnpm

二、常用配置项详解（以 pnpm 为主）

1. 依赖解析类配置

2. 网络与存储类配置

3. 安装行为类配置

三、配置查看与管理技巧

1. 查看所有配置

2. 多级配置优先级

3. 临时覆盖配置

四、典型场景配置示例

场景 1：企业内网开发

strict-peer-dependencies=false

fetch-retries=5

场景 2：CI/CD 优化

prefer-frozen-lockfile=true

package-import-method=copy

场景 3：解决 Monorepo 依赖问题

public-hoist-pattern[]=*babel*

auto-install-peers=true

五、重要注意事项

pnpm setup

pnpm config delete registry --location=project

配置项解析与应用场景

1. strict-peer-dependencies=false

2. fetch-retries=5

3. prefer-frozen-lockfile=true

4. package-import-method=copy

5. public-hoist-pattern[]=*babel*

6. auto-install-peers=true

命令解析与应用场景

1. pnpm setup

2. pnpm config delete registry --location=project

配置优先级管理技巧

1. 多级配置查看

2. 配置作用域管理

3. 典型配置工作流

最佳实践建议

`strict-peer-dependencies=false`

`fetch-retries=5`

`prefer-frozen-lockfile=true`

`package-import-method=copy`

`public-hoist-pattern[]=babel`

`auto-install-peers=true`

`pnpm setup`

`pnpm config delete registry --location=project`

1. `strict-peer-dependencies=false`

2. `fetch-retries=5`

3. `prefer-frozen-lockfile=true`

4. `package-import-method=copy`

5. `public-hoist-pattern[]=babel`

6. `auto-install-peers=true`

1. `pnpm setup`

2. `pnpm config delete registry --location=project`