根本原因是node_modules目录或其子目录被root用户写入（如曾用sudo npm install），导致当前用户无权读取，使模块解析器静默跳过而非报权限错；正确解决需清除缓存、删除node_modules和package-lock.json、重设npm prefix至用户目录并禁用unsafe-perm。
本地模块目录权限不足导致构建失败，根本原因不是构建工具本身出问题，而是 node_modules 或其子目录被系统（尤其是 macOS/Linux）以非当前用户身份写入过，或通过 sudo npm install 留下残留所有权。直接改 chmod -R 755 node_modules 是危险且无效的——它可能修复部分读取问题，但掩盖了真正矛盾：npm 本不该需要 root 权限来管理本地依赖。
为什么 npm install 会突然报 EACCES 错误
典型错误信息像 npm ERR! code EACCES、EPERM: operation not permitted 或构建时提示 Cannot find module 'xxx' 却确认文件存在，往往源于：node_modules 中某些目录/文件的所有者是 root（比如曾用 sudo npm install），而当前用户无权读取或遍历这些路径。Node.js 的模块解析器（require()）和构建工具（如 Webpack、Vite）在递归查找 node_modules 时卡在权限拒绝节点，不会报“权限错”，而是静默跳过或抛出模块未找到。
- macOS 上常见于全局安装后又在项目中混用
sudo，触发 SIP 对某些路径的额外限制 - Linux 容器或 WSL 环境中，挂载卷的 UID/GID 映射错位，导致文件属主不匹配
-
package-lock.json锁定的包版本与本地node_modules实际内容不一致，npm 试图重写时因权限阻塞
彻底清理并重建 node_modules 的安全流程
不要用 rm -rf node_modules 后直接 npm install ——如果 package-lock.json 里记录了被污染的包哈希，重装仍可能复现问题。正确顺序是：
- 运行
npm cache clean --force清除本地缓存，避免 npm 从损坏缓存中提取已签名但属主异常的 tarball - 删除
node_modules和package-lock.json（二者必须一起删，否则 npm install 会按 lock 文件还原旧状态） - 检查
npm config get prefix，确保不是/usr/local这类系统路径；如果是，执行npm config set prefix ~/.npm-global并将~/.npm-global/bin加入$PATH - 最后执行
npm install——此时所有文件均由当前用户创建，所有权干净
预防下次再踩坑的关键配置
npm 默认行为在某些系统上会悄悄降权失败，但不报错，直到构建阶段才暴露。最有效的防御是让 npm 拒绝任何需要提升权限的操作：
- 执行
npm config set unsafe-perm false：强制 npm 在检测到 root 环境时不自动绕过权限检查 - 设置
npm config set user 1001（替换为你当前用户的 UID，用id -u查）——这能防止 Docker 或 CI 环境中因 UID 不匹配导致的属主错乱 - 永远不用
sudo npm install；若需全局命令，用npm install -g xxx --no-bin-links+ 手动软链，或改用corepack管理 pnpm/yarn
真正的“彻底解决”不在于修权限，而在于让整个依赖链路始终运行在单一用户上下文里。一旦 node_modules 出现 root 属主，就说明某个环节已经越权——这个信号比报错本身更值得警惕。
