npm 全局包迁移指南：从系统目录到用户目录

背景

npm 默认的全局安装路径通常与 npm 的安装目录共享，如：

脚本安装的 npm 在 /usr/local ，其安装的应用在 /usr/local/lib/node_modules
brew 安装的 npm 在 /opt/homebrew，其安装的应用在 /opt/homebrew/lib/node_modules
这会导致以下问题：
npm 安装的版本会与安装 npm 相同方式的版本不能共存，如 brew 安装的 npm 安装 Claude 不能与 brew 直接安装的 Claude 共存安装
系统升级时可能丢失或损坏

将 npm 全局包迁移到用户目录（~/.npm-global）可以彻底解决这些问题。

迁移前检查

1. 确认当前配置

shell 复制代码

npm config get prefix
# 输出示例：/usr/local 或 /opt/homebrew

2. 查看已安装的全局包

ini 复制代码

npm list -g --depth=0

3. 查看旧目录内容

bash 复制代码

ls /usr/local/lib/node_modules
# 或
ls /opt/homebrew/lib/node_modules

注意：npm、corepack 等是 npm 自带的，不需要迁移。

迁移步骤

第一步：创建新的用户目录

bash 复制代码

mkdir -p ~/.npm-global/bin

第二步：配置 npm 使用新目录

arduino 复制代码

npm config set prefix '~/.npm-global'

此配置会写入 ~/.npmrc，永久生效。

第三步：更新 PATH

在 ~/.zshrc（或 ~/.bashrc）中添加：

bash 复制代码

# 将 npm 全局 bin 目录放在 PATH 最前面，优先于系统目录
export PATH="$HOME/.npm-global/bin:$PATH"

然后重载配置：

bash 复制代码

source ~/.zshrc

第四步：验证新配置

bash 复制代码

npm config get prefix
# 应输出：/Users/你的用户名/.npm-global

which npm
# 确认路径正确

迁移已有包

方案 A：逐个重新安装（推荐）

bash 复制代码

# 查看旧目录中的包（排除 npm 自带）
ls /usr/local/lib/node_modules

# 重新安装需要的包
npm install -g <package-name>

# 示例
npm install -g ganache hardhat truffle create-dmg

对于 scoped 包（带 @ 前缀）：

perl 复制代码

# 先查看完整包名
ls /usr/local/lib/node_modules/@scope-name/

# 然后安装
npm install -g @scope-name/package-name

方案 B：批量迁移脚本

bash 复制代码

#!/bin/bash
# 定义需要迁移的包列表
PACKAGES="ganache hardhat truffle create-dmg"

for pkg in $PACKAGES; do
  echo "Installing $pkg..."
  npm install -g "$pkg"
done

# 处理 scoped 包
for scope in iflow-ai music163 qingchencloud; do
  if [ -d "/usr/local/lib/node_modules/@$scope" ]; then
    for pkg in $(ls /usr/local/lib/node_modules/@$scope/); do
      echo "Installing @$scope/$pkg..."
      npm install -g "@$scope/$pkg"
    done
  fi
done

脚本由 AI 生成，不保证全平台可用性，最好根据实际情况重写

验证迁移结果

bash 复制代码

# 确认新目录中有包
ls ~/.npm-global/lib/node_modules/

# 确认命令可用
which <command-name>
<command-name> --version

后续影响

方面	说明
新安装	所有 `npm install -g` 自动安装到 `~/.npm-global`
权限	不再需要 `sudo`，完全用户态管理
冲突	与 Homebrew 等其他包管理器完全隔离
备份	可直接备份 `~/.npm-global` 目录
卸载	直接删除 `~/.npm-global` 即可清空所有全局包

回退方案

如需恢复默认配置：

shell 复制代码

# 删除自定义 prefix
npm config delete prefix

# 从 PATH 中移除 ~/.npm-global/bin
# 编辑 ~/.zshrc，删除相关 export 行

常见问题

Q: 旧目录里的包还能用吗？

A: 只要旧目录仍在 PATH 中，就可以继续使用。但建议逐步迁移到新目录统一管理。

Q: 需要删除旧目录吗？

A: 不需要。旧目录可以保留作为备份，或等确认新环境稳定后再手动清理。

Q: 会影响 npx 吗？

A: 不会。npx 会优先使用 ~/.npm-global 中的包，行为一致。

总结

迁移到用户目录后，npm 全局包管理变得：

✅ 无权限冲突
✅ 无系统目录污染
✅ 与 Homebrew 等工具和平共处
✅ 便于备份和迁移