npm 全局安装报 EACCES 权限不足怎么解决

一句话回答：EACCES 表示操作系统拒绝访问。全局安装时常见原因是 npm prefix 指向普通用户不可写的目录（例如部分 Unix 安装中的 /usr/local/lib/node_modules），也可能是项目/缓存权限或 Windows ACL；先按报错路径定位。最佳解法是用 nvm 安装 Node（全局目录通常位于用户目录，可避免常见系统目录写权限问题）；或执行 npm config set prefix "$HOME/.npm-global" 把全局目录改到家目录并配好 PATH。sudo npm install -g 虽能应急但后患无穷，不推荐。

方案一：用版本管理器装 Node

nvm 把 Node 整个装在 ~/.nvm 下，全局包目录随之落在用户目录，可规避系统级全局目录权限冲突，但仍须正确的目录属主与写权限：

# 按 nvm 官方仓库说明下载、审阅并运行安装器，然后重开终端
# Bash / zsh 应加载各自的配置文件，不要一律 source ~/.bashrc
nvm install --lts
npm install -g 包名      # 不再需要 sudo

额外收益：可以随时 nvm use --lts 等命令 切换版本。

方案二：改 npm 全局目录

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"

# 加入 PATH（写进 ~/.bashrc 或 ~/.zshrc）
export PATH=~/.npm-global/bin:$PATH

source ~/.bashrc
npm install -g 包名

两种方案不要盲目叠加：nvm-sh 不兼容用户 .npmrc 中自定义的 prefix，迁移到 nvm 前应按官方说明清理该配置。

为什么不推荐 sudo npm

sudo npm install -g 包名    # 能跑，但别这么干

危害：

1. 权限污染：npm 缓存（~/.npm）里混入 root 属主的文件，之后普通 npm 命令会随机报 EACCES，越搞越乱
2. 安全风险：npm 包安装时会执行 postinstall 脚本，用 root 跑等于给任意第三方代码开了最高权限
3. 卸载、升级时权限问题连环出现

如果已经用 sudo 搞乱了缓存，修复：

# 仅在确认 ~/.npm 属于本用户缓存且误被改为 root 后执行
sudo chown -R "$(id -u):$(id -g)" "$HOME/.npm"

已经乱了的系统级 Node 怎么办

用 apt/brew 装的 Node 把全局目录放在系统路径，迁移步骤：

1. 用方案二改 prefix（不必重装 Node）
2. 或干脆卸载系统 Node，改装 nvm 管理的版本

常见问题（FAQ）

Q：Windows 上会遇到 EACCES 吗？

A：会，ACL、文件被占用、防护软件或受限目录均可能导致权限类错误（也可能显示 EPERM）。先看具体路径和操作，不要一概使用管理员权限或关闭防护；本文 nvm-sh/prefix 的 POSIX 路径命令不能直接照搬到 Windows。

Q：公司服务器上没有 sudo 权限怎么全局安装？

A：方案二就是为零 sudo 场景设计的——prefix 改到家目录后所有操作都在用户权限内。也可以用 npx 包名 直接运行而不全局安装。

Q：Docker 镜像里报 EACCES？

A：官方 node 镜像通常提供非 root 的 node 用户，但不保证它可写系统级全局目录。可把 NPM_CONFIG_PREFIX 指向该用户可写目录并配置 PATH，或在构建阶段安装所需工具后以非 root 运行；不要靠提升运行期权限掩盖目录问题。

核查依据

本文依据官方文档核对，示例未在实际业务环境运行；上线前请按部署版本、权限与数据范围验证。

• docs.npmjs.com：resolving eacces permissions errors when installing packages globally
• 官方项目：BestPractices
• 官方项目：nvm

---

延伸阅读

• Node.js 报错 "Can't set headers after they are sent" 怎么解决
• Elasticsearch 报 index_not_found_exception 怎么解决