npm 装包报 EACCES 权限错误不是 Node.js 的问题

FreeGuideOnline 最新 2026-07-04

Error: EACCES: permission denied, access '/usr/local/lib/node_modules'


`EACCES` 是 “Error: access” 的缩写，是操作系统抛出的权限拒绝错误。**这跟 Node.js 版本无关，也跟 npm 的 bug 无关，纯粹是文件系统权限问题。**

### 为什么会发生？

- **默认全局目录需要管理员权限**  
  官方 Node.js 安装包（从 [nodejs.org](https://nodejs.org) 下载）通常会把全局模块路径设在 `/usr/local/lib/node_modules`，该目录仅允许 `root` 用户写入。如果直接用普通用户执行 `npm install -g`，就会触发 EACCES。

- **之前使用过 `sudo npm`**  
  如果你曾经用 `sudo npm install -g ...` 安装过包，之后生成的某些文件或目录可能被 `root` 拥有，普通用户再想读写时就会遇到权限错误。

- **npm 缓存目录权限异常**  
  偶尔缓存目录（`~/.npm`）的权限被破坏也会导致类似错误，不过 EACCES 更常见于全局安装。

### 快速诊断：确定哪个目录有问题

运行以下命令可以查看 npm 的全局前缀和缓存路径：

```bash
npm config get prefix
npm config get cache

典型输出：

/usr/local
/Users/你的用户名/.npm

如果 prefix 显示 /usr/local，那么全局模块会被安装到 /usr/local/lib/node_modules，而修改该目录需要 sudo。这正是错误的原因。

正确的解决方法（选择一种即可）

以下方案按推荐程度从高到低排列，请不要随意使用 sudo npm，它会带来更多权限和安全风险。

方案一：避免全局安装，使用 npx

很多工具的全局安装其实可以用 npx 替代。npx 会临时下载并执行包，不会污染全局目录。例如：

# 原来需要全局安装 create-react-app 再执行
# npm install -g create-react-app && create-react-app my-app

# 现在只需一行
npx create-react-app my-app

本地项目依赖直接安装在项目 node_modules 内，无需全局权限。

方案二：修改 npm 全局目录到用户主目录（推荐）

告诉 npm 把全局模块安装到你自己有完全控制权的目录，例如 ~/.npm-global。

  1. 创建目录：

    mkdir ~/.npm-global

  2. 配置 npm 使用新目录：

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

  3. 将新目录的 bin 文件夹添加到系统的 PATH 环境变量。
    在 ~/.bashrc、~/.zshrc 或 ~/.profile 中添加以下行：

    export PATH=~/.npm-global/bin:$PATH

    然后刷新配置文件：

    source ~/.bashrc   # 或 ~/.zshrc

  4. 测试：现在你可以不带 sudo 安装全局包了：

    npm install -g package-name

方案三：使用 Node 版本管理器（最佳实践）

nvm（Node Version Manager）或 n 等工具会在你的用户目录下安装 Node.js，并自动管理 npm 全局目录，全无权限烦恼。

  • 安装 nvm（以 macOS / Linux 为例）：

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

    重启终端后生效。

  • 安装 Node.js：

    nvm install --lts
nvm use --lts

安装后，npm 的全局 prefix 会自动指向 ~/.nvm/versions/node/<版本号>/lib，完全归当前用户所有，再也不会出现 EACCES 错误。

方案四：修复现有目录权限（不推荐，仅限紧急修复）

如果你已经用过 sudo npm，想恢复目录归属给自己，可以手动更改。此操作有风险，请在理解命令含义后执行。

# 将全局 node_modules 目录所有权授予当前用户
sudo chown -R $(whoami) /usr/local/lib/node_modules

# 同时修复 /usr/local/bin 等目录中的链接
sudo chown -R $(whoami) /usr/local/bin /usr/local/share