1. 背景与环境

在开发 Electron 鸿蒙化应用时，我们需要通过 @electron-forge/cli 初始化项目脚手架：

npm install --save-dev @electron-forge/cli

但在 Windows 上执行时，可能遇到如下报错：

npm ERR! code EBUSY
npm ERR! syscall rename
npm ERR! path C:\Users\xxx\AppData\Local\npm-cache\_cacache\tmp\xxx
npm ERR! dest C:\Users\xxx\AppData\Local\npm-cache\_cacache\content-v2\sha512\xx\xx\xxx
npm ERR! errno EBUSY
npm ERR! Invalid response body while trying to fetch https://registry.npmjs.org/xxx: EBUSY: resource busy or locked, rename 'xxx' -> 'xxx'

本文示例的开发环境如下：

组件	版本
Windows	11 专业版 22H2
Node.js	20.x LTS
npm	10.x
@electron-forge/cli	latest

---

问题原因

在 Windows 系统上，npm 缓存文件可能被以下情况占用：

1. 其他 npm 进程正在运行
2. 防病毒软件正在扫描该文件
3. 文件被其他程序锁定
4. 之前的 npm 进程没有完全关闭

2. EBUSY 错误根因分析

2.1 什么是 EBUSY？

EBUSY 是 Windows 系统级错误码（对应 Win32 ERROR_BUSY），含义是 “资源正忙或被锁定”。在 npm 的场景中，通常是 npm 缓存目录（%APPDATA%/npm-cache）中的某个文件被其他进程占用，导致 npm 无法对其进行读写或重命名操作。

2.2 npm 缓存机制简述

npm 会将下载的包缓存在 %APPDATA%/npm-cache/_cacache/ 目录下，这是一个 content-addressable cache。安装流程大致为：

npm install
  └─ 下载包 → 写入 _cacache/tmp/（临时文件）
       └─ rename → _cacache/content-v2/（正式缓存）
            └─ 解压到 node_modules/

如果在 rename 这一步，临时文件被其他进程（杀毒软件、残留的 node 进程、文件索引服务等）占用，就会抛出 EBUSY。

2.3 常见元凶

1. 残留的 Node.js 进程：上一次 npm install 未完全退出
2. 杀毒软件/Windows Defender：实时扫描锁定了缓存文件
3. Windows Search Indexer：正在索引缓存目录
4. 文件资源管理器：打开了缓存目录
5. 磁盘权限不足：非管理员用户对 %APPDATA% 的写入权限被限制

3. 解决方案（按推荐顺序）

方案 1：清理 npm 缓存（首选，解决率 ≈ 90%）

适用场景：首次遇到此错误，且之前安装过程被中断。

# 清理 npm 缓存
npm cache clean --force

# 重新安装
npm install --save-dev @electron-forge/cli

补充说明：

• --force 会强制清空整个缓存目录，下次安装时需要重新下载所有包，耗时稍长但最彻底。
• 如果想先检查缓存健康度，可先运行 npm cache verify，它会报告损坏的缓存项数量，视情况再决定是否 --force 清理。

实际截图：

---

方案 2：强制关闭残留 Node 进程后重试

适用场景：方案 1 无效，或怀疑之前有进程未正常退出。

# 1. 查看当前运行的 Node 进程
Get-Process node -ErrorAction SilentlyContinue

# 2. 强制结束所有 Node 进程
Get-Process node -ErrorAction SilentlyContinue | Stop-Process -Force

# 3. 清理缓存
npm cache clean --force

# 4. 重新安装
npm install --save-dev @electron-forge/cli

CMD 版本（不使用 PowerShell 的用户）：

:: 查看 Node 进程
tasklist | findstr node.exe

:: 强制结束所有 Node 进程
taskkill /F /IM node.exe

:: 清理缓存并重新安装
npm cache clean --force && npm install --save-dev @electron-forge/cli

---

方案 3：以管理员身份运行终端

适用场景：权限不足导致无法操作缓存目录。

操作步骤：

1. 按 Win + X，选择 “终端（管理员）” 或 “Windows PowerShell（管理员）”
2. 在管理员终端中，进入项目目录后重新执行安装命令

npm install --save-dev @electron-forge/cli

注意：以管理员身份运行可以解决权限问题，但安装后的 node_modules 所有权可能归属于 Administrator，后续普通权限操作可能受限。建议只在必要时使用此方案。

方案 4：切换包管理器（yarn / pnpm）

适用场景：npm 反复出现 EBUSY 且上述方案均无效。
yarn 和 pnpm 的缓存机制与 npm 不同，占用竞争的概率更低。

# 先安装 yarn（如果尚未安装）
npm install -g yarn

# 使用 yarn 安装
yarn add -D @electron-forge/cli

# --- 或者使用 pnpm ---

# 先安装 pnpm
npm install -g pnpm

# 使用 pnpm 安装
pnpm add -D @electron-forge/cli

包管理器	缓存位置	特点
npm	%APPDATA%/npm-cache/	默认，生态最大
yarn	%APPDATA%/Local/Yarn/	离线安装更快
pnpm	%APPDATA%/Local/pnpm-store/	硬链接机制，磁盘占用更少

方案 5：排查杀毒软件/Windows Defender

适用场景：上述方案均失败，且错误反复出现在不同的安装场景。

5.1 将 npm 缓存目录加入 Windows Defender 排除项

1. 打开 “Windows 安全中心” → “病毒和威胁防护”
2. 点击 “管理设置” → 滚动到 “排除项” → “添加或删除排除项”
3. 添加文件夹：C:\Users\<你的用户名>\AppData\Local\npm-cache
4. 添加文件夹：C:\Users\<你的用户名>\AppData\Roaming\npm-cache
5. 重试安装

5.2 临时禁用实时保护（最后手段）

在 “病毒和威胁防护设置” 中，临时关闭 “实时保护”，安装完成后务必重新开启。

⚠️ 安全提醒：安装完成后请立即恢复实时保护，期间不要浏览未知网站或打开可疑文件。

方案 6：手动删除缓存目录（兜底方案）

如果 npm cache clean --force 本身也报 EBUSY，说明缓存目录中有文件连 npm 自己都无法操作：

# 查看缓存目录位置
npm config get cache
# 输出类似: C:\Users\xxx\AppData\Local\npm-cache

# 手动删除整个缓存目录
Remove-Item -Recurse -Force "C:\Users\xxx\AppData\Local\npm-cache"

然后重新执行安装，npm 会自动重建缓存目录。

4. 排查流程图

npm install 报 EBUSY
  │
  ├── ① npm cache clean --force 后重试
  │    └─ 成功 → ✅ 完成
  │    └─ 失败 ↓
  │
  ├── ② 检查并关闭残留 Node 进程，清缓存重试
  │    └─ 成功 → ✅ 完成
  │    └─ 失败 ↓
  │
  ├── ③ 以管理员身份运行终端重试
  │    └─ 成功 → ✅ 完成
  │    └─ 失败 ↓
  │
  ├── ④ 换 yarn / pnpm 安装
  │    └─ 成功 → ✅ 完成
  │    └─ 失败 ↓
  │
  ├── ⑤ 将 npm 缓存目录加入杀软排除项
  │    └─ 成功 → ✅ 完成
  │    └─ 失败 ↓
  │
  └── ⑥ 手动删除缓存目录 → 重试
       └─ 成功 → ✅ 完成
       └─ 失败 → 检查磁盘权限 / 更换 Node 版本

5. 安装成功后验证

# 检查 @electron-forge/cli 是否安装成功
npx electron-forge --version

# 检查 node_modules 中是否存在该包
ls node_modules/@electron-forge/cli

---

6. 预防措施

1. 定期清理缓存：npm cache clean --force（建议每月一次）
2. 安装前确保无残留进程：任务管理器确认 node.exe 全部退出
3. 将 npm 缓存目录加入杀软排除列表（操作见方案 5.1）
4. 配置 .npmrc 优化缓存行为：

在项目根目录或用户目录创建/编辑 .npmrc：

# 设置缓存路径（可选，避免系统盘空间不足）
cache=D:\npm-cache

# 设置更长的网络超时，减少中断
fetch-timeout=120000

5. 保持工具链更新：npm install -g npm@latest

7. 总结

方案	解决率	操作复杂度	副作用
① 清缓存	~90%	低	重新下载包
② 杀进程	~70%	低	无
③ 管理员	~60%	低	node_modules 权限可能变化
④ 换包管理器	~85%	中	团队需统一包管理器
⑤ 杀软排除	~50%	中	降低缓存目录安全性
⑥ 手动删缓存	~95%	中	需重新下载所有包

大多数情况下，方案 1（清理缓存） 即可解决问题。本文方案 1 实操后安装成功，顺利完成 Electron 鸿蒙化项目的初始化。

---

参考资源

• npm 官方文档 - npm cache
• Electron Forge 官方文档
• 项目源码：harmony-count-app
• 开源鸿蒙 PC 社区：HarmonyPC