npm install -g 报 npm ERR! code EACCES permission denied（全局安装权限）

你会遇到什么

npm install -g <包> 报 npm ERR! code EACCES，你以为权限不够加个 sudo 就完事——结果下次连缓存都写不进（Your cache folder contains root-owned files），越修越糟。其实报错有两种形态，路径不同、修法完全不同，先看 path 指向哪再动手。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

npm 全局安装要写两个位置：全局包目录（npm prefix -g，如 /usr/local/lib/node_modules）和缓存（~/.npm）：

形态 1 是非 root 用户装全局包的常态（系统 node 装在 /usr/local 或 /usr）；形态 2 是曾经 sudo 装过的后遗症。报错都带 EACCES + errno -13，但解法不同。

实测环境：WSL Ubuntu，node v22.22.1 / npm 9.2.0，2026-08-29。

npm 全局安装写两个位置：全局包目录（npm prefix -g 指向的 node_modules）和缓存目录（~/.npm）。

EACCES 是「当前用户对目标目录无写权限」：形态 1 的全局目录属 root（系统 node 装进 /usr/local 或 /usr），非 root 用户写入被拒；形态 2 是历史 sudo npm install 把 ~/.npm 缓存目录的属主变成了 root，之后普通用户写缓存被拒。

两种形态都是 EACCES/errno -13，但根因和解法完全不同——形态 1 是「目录属主」问题，形态 2 是「缓存属主被污染」。

确定性推论：报错路径带 node_modules = 形态 1，带 _cacache/.npm = 形态 2；形态 1 的正解是 npm config set prefix ~/.npm-global 把全局目录挪到用户目录并加 PATH（不要 sudo 硬装），形态 2 的正解是 sudo chown -R $(whoami) ~/.npm 把缓存属主改回来；

判断路径固定：ls -ld 看目标目录属主，再对照报错路径。

一步步来

1. 先看报错的 path 判断形态 — 排查

npm install -g yaml 2>&1 | grep -E "path|EACCES"

path /usr/local/lib/... → 形态 1；path /home/<user>/.npm/_cacache → 形态 2。

2. 形态 1：改全局 prefix 到用户目录（推荐） — 必做

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

把 export PATH=... 写进 ~/.bashrc，以后全局包都装到自己目录，不再碰系统目录。

3. 形态 2：把 ~/.npm 所有权还给自己 — 必做

sudo chown -R $(whoami) ~/.npm

npm 报错里会直接提示对应的 chown 命令。不想保留旧缓存也可以 rm -rf ~/.npm 让它重建。

4. 备选方案 — 进阶

• 用 nvm 管理 node：node 装在 ~/.nvm 下，全局包天然可写；
• sudo npm install -g 能用但不推荐——会继续制造形态 2。

怎么确认修好了

npm install -g yaml && yaml --help

不再报 EACCES、yaml 命令能跑（输出 usage）即成功。实测：形态 1 修复后 added 1 package 成功；形态 2 chown 后 changed 1 package 成功。

其它环境的表现

症状

npm install -g <包> 报权限错误，两种典型形态：

# 形态 1：全局包目录没写权限（最常见）
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/yaml
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/yaml'

# 形态 2：缓存目录被 root 占用（用 sudo 装过之后）
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /home/<user>/.npm/_cacache
npm ERR! Your cache folder contains root-owned files, due to a bug in
npm ERR! previous versions of npm which has since been addressed.

特征：错误都带 npm ERR! code EACCES + errno -13；退出码常为 243；形态 1 发生在非 root 用户装全局包（系统 node 装在 /usr/local 或 /usr，目录属 root）；形态 2 常见于曾经 sudo npm install 之后（~/.npm 里混入 root 文件，普通用户再也写不进去）。

原因

npm 全局安装要写两个位置：全局包目录（npm prefix -g，如 /usr/local/lib/node_modules）和缓存（~/.npm）。前者属 root 而当前用户非 root → 形态 1；后者被 root 建过文件/目录（sudo 残留）→ 形态 2。报错虽都是 EACCES，但路径不同、修法不同——先看 path 指向哪里。

解法

1. 形态 1：把全局 prefix 改到用户目录（推荐，一劳永逸）：

   npm config set prefix ~/.npm-global
   export PATH="$HOME/.npm-global/bin:$PATH"   # 写入 ~/.bashrc

之后 npm install -g 装到自己的目录，不再碰系统目录。

1. 形态 1 备选：用 nvm 管理 node（node 装在自己的 ~/.nvm 下，全局包天然可写）；或 sudo npm install -g（能用但不推荐，会继续制造形态 2）。
2. 形态 2：把 ~/.npm 所有权还给自己：

   sudo chown -R $(whoami) ~/.npm

（npm 报错里会直接提示对应的 chown 命令）。不想保留旧缓存也可以 rm -rf ~/.npm 让它重建。

1. 验证：npm install -g <包> 成功 + 命令能跑（如 yaml 输出 usage）。