1. 构建失败，先别看 build，看 install

在 Electron + Vite 项目中，构建失败时常见到诸如 vite is not recognized 的提示，但这通常只是表象。

真正的问题往往出现在依赖安装阶段，尤其是 electron 在执行 install.js 下载二进制时因为网络超时而中断，导致 node_modules 不完整，进而引发后续构建失败。

npm install
# 或
yarn install

只要日志中出现 ETIMEDOUT、ECONNRESET，基本可以直接判定为网络问题。

2. npm 与 yarn 不要混用，先统一再排障

项目中同时存在 package-lock.json 和 yarn.lock，或交替使用 npm install 与 yarn install，很容易导致依赖解析不一致，从而放大问题。实践中应当明确只使用一种包管理器，并在切换前彻底清理环境。

例如统一使用 npm：

rm -rf node_modules
rm -f yarn.lock
npm cache clean --force
npm install

例如统一使用 npm：

rm -rf node_modules
rm -f package-lock.json
yarn install

3. Electron 安装失败的关键：网络

Electron 安装失败往往与 npm registry 无关，而是二进制下载源不可达。因此除了切换 registry，还需要为 Electron 单独配置镜像。常见配置方式如下：

npm config set registry https://registry.npmmirror.com
npm config set electron_mirror https://npmmirror.com/mirrors/electron/
npm config set electron_builder_binaries_mirror https://npmmirror.com/mirrors/electron-builder-binaries/

或临时用环境变量：

export ELECTRON_MIRROR=https://repo.huaweicloud.com/electron/

不行就换网络、换时间段，多试几次往往比折腾配置有效。

4. Windows 的 EPERM 报错

EPERM: operation not permitted 多出现在 Windows 环境，原因通常是 node_modules 被占用或权限不足。此时反复 install 意义不大，正确做法是关闭编辑器和相关进程后彻底删除依赖目录，再重新安装。

rm -rf node_modules
npm cache clean --force
npm install