日常全局安装/升级 npm 包时，经常遇到 ENOTEMPTY: directory not empty 报错，终端提示目录重命名失败。很多人会误以为是 Node、NVM 版本问题，其实这是非常典型的 npm 残留文件系统异常，本文带你彻底搞懂报错根因，并提供由浅入深、可直接复制执行的全套解决方案。
一、完整报错信息复盘
本次安装 @anthropic-ai/claude-code 全局包报错日志如下，是该问题的标准报错模板：
npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/peterzhang/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/peterzhang/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai/.claude-code-5ydbVGEI
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename 旧目录 -> 临时备份目录核心问题：npm 尝试将旧包目录重命名为临时备份目录，但目标临时目录已存在且非空，导致重命名流程中断，安装失败。
二、报错根本原因（通俗易懂）
npm 升级、重装、卸载全局包的标准执行逻辑：
- 将旧版本包目录重命名为
.xxx-随机字符格式的临时备份目录； - 解压安装新版本包；
- 安装完成后自动删除临时备份目录。
⚠️ 该问题和 Node20、NVM 版本、系统环境无关，纯文件系统残留问题。
三、分级解决方案（从优先推荐到兜底方案）
按顺序执行，优先用简单方案，绝大多数情况第一步即可解决。
方案一：清理残留临时目录（首选、最安全）
精准删除报错提示的残留临时文件夹，不影响其他依赖，零风险。
# 进入报错的全局包目录
cd /home/peterzhang/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai
# 删除残留的临时目录（对应报错中的 .claude-code-5ydbVGEI）
rm -rf .claude-code-5ydbVGEI
# 重新执行安装命令
npm install -g @anthropic-ai/claude-code方案二：强制删除旧包目录重装（方案一失效用）
若临时目录清理后仍报错，说明旧包文件已损坏，直接删除旧包本体重装：
cd /home/peterzhang/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai
rm -rf claude-code
npm install -g @anthropic-ai/claude-code方案三：强制安装绕过重命名校验（快速兜底）
不想手动删文件，直接通过强制参数绕过目录校验，覆盖安装：
npm install -g @anthropic-ai/claude-code --force方案四：清理 npm 缓存（终极兜底）
若以上方案全部失效，大概率是 npm 缓存损坏，清空缓存后重试：
npm cache clean --force
# 缓存清理完成后重新安装
npm install -g @anthropic-ai/claude-code四、通用避坑总结
- 核心结论：ENOTEMPTY 报错 99% 是 npm 操作中断导致的临时目录残留，非版本兼容问题；
- 最佳修复习惯：优先删临时目录，其次删旧包，最后用强制安装和清缓存；
- 日常避坑：安装、升级依赖时不要强制终止终端进程，避免文件残留；
- 通用适配：该方案适用于所有 npm 包（eslint、vue-cli、ts 等）的同名目录重命名报错。
五、一键修复单行命令
懒人直达，直接复制整条命令一键修复重装：
rm -rf /home/peterzhang/.nvm/versions/node/v20.20.2/lib/node_modules/@anthropic-ai/.claude-code-5ydbVGEI && npm install -g @anthropic-ai/claude-code正文完
可以使用微信扫码关注公众号（ID：xzluomor）
