解决 Vite EACCES 权限错误：从报错到修复的完整指南

问题现象

在 macOS 上运行 npm run dev 启动 Vite 开发服务器时，控制台频繁抛出以下错误：

bash 复制代码

Error: EACCES: permission denied, mkdir '/Users/xxx/project/node_modules/.vite/deps_temp_xxxxx'
    at Object.mkdirSync (node:fs:1370:26)
    at runOptimizeDeps (vite/dist/node/chunks/node.js:31235:5)

关键特征：

服务能启动（http://localhost:5173/ 可访问）
但依赖优化持续失败，热更新失效
错误重复出现，影响开发体验

根因分析

Vite 在启动时会执行 依赖预构建（Dependency Pre-bundling），需要：

扫描项目依赖
在 node_modules/.vite 目录创建临时文件夹
写入缓存的优化后的依赖

当该目录被 root 用户 或其他用户创建时，当前用户无写入权限，导致 EACCES 错误。

常见触发场景：

场景	说明
使用 `sudo npm install`	以 root 身份安装依赖
从其他机器复制项目	保留原用户的文件权限
CI/CD 构建后本地开发	构建容器与本地用户 ID 不一致
多用户共享项目目录	权限交叉污染

解决方案

四步快速修复（推荐）

在项目根目录依次执行：

bash 复制代码

# 步骤 1：停止当前服务
Ctrl + C

# 步骤 2：递归修复 node_modules 所有权
sudo chown -R $(whoami) node_modules

# 步骤 3：清除 Vite 缓存
rm -rf node_modules/.vite

# 步骤 4：重新启动开发服务器
npm run dev

命令解析：

$(whoami)：自动获取当前用户名
-R：递归处理所有子目录
chown：Change Owner，修改文件所有者

彻底重装（备用方案）

如果上述方法无效，可能是更深层的权限问题：

bash 复制代码

# 完全删除依赖和锁文件
rm -rf node_modules package-lock.json

# 重新安装（无需 sudo）
npm install

# 启动服务
npm run dev

预防措施

1. 避免使用 sudo 安装依赖

bash 复制代码

# ❌ 错误做法
sudo npm install

# ✅ 正确做法
npm install

如果提示权限不足，修改 npm 全局目录到用户空间：

bash 复制代码

# 创建用户级全局目录
mkdir ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'

# 添加到 PATH（zsh 用户）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

2. 检查目录权限

bash 复制代码

# 查看 node_modules 权限
ls -ld node_modules

# 正确输出示例：
# drwxr-xr-x  120 yourname  staff  3840 Apr  3 17:29 node_modules
#     ↑ 所有者应为当前用户，而非 root

3. 使用 npx 避免全局安装

bash 复制代码

# 不推荐全局安装 Vite
npm install -g vite

# 推荐本地安装，使用 npx
npm install -D vite
npx vite

扩展：其他常见 Vite 权限错误

端口占用

bash 复制代码

# 错误：Port 5173 is already in use
# 解决：强制终止占用进程
npx kill-port 5173

只读文件系统

bash 复制代码

# 错误：EROFS: read-only file system
# 常见于 Docker 或受限环境
# 解决：挂载可写卷或更换缓存目录
vite --cacheDir /tmp/.vite

总结

问题	解决命令	耗时
Vite 权限错误	`sudo chown -R $(whoami) node_modules`	10 秒
深层权限污染	删除重装 `rm -rf node_modules && npm i`	2-5 分钟
预防复发	配置 npm 前缀 + 避免 sudo	一次性

核心原则： Node.js 项目永远不要使用 sudo 安装依赖。权限问题优先用 chown 修复，而非重装。

参考链接：