Error: Could not resolve “bufferutil” imported by “ws”. Is it installe

这是 Electron 主进程打包后找不到可选原生依赖 的经典警告： ws（WebSocket 库）在运行时尝试加载性能优化包 bufferutil / utf-8-validate，它们被声明在 ws 的 optionalDependencies，如果本地未编译成功就会被静默跳过；但在 Electron 的 Vite 打包产物里，静态分析依旧把 require(“bufferutil”) 语句留了下来，运行时就抛 “Could not resolve”。

解决思路：让打包器把这两个可选包标记为“外部依赖，不要 bundle”，主进程运行时如果真的找不到，ws 会自动退化到 JS 实现，功能不受影响。

一、最快修复（electron-vite 官方方案）

修改 electron.vite.config.ts（主进程配置）：

export default defineConfig({
  main: {
    resolve: {
      // 告知 vite 遇到这些模块就假装它们存在，不要打包
      external: ['bufferutil', 'utf-8-validate']
    },
    build: {
      rollupOptions: {
        external: ['bufferutil', 'utf-8-validate'] // 同上，保险写两遍
      }
    }
  },
  preload: { /* 保持原样 */ },
  renderer: { /* 保持原样 */ }
})

二、如果还报错 → 显式安装并 rebuild（可选）

1. 安装

npm i -D bufferutil utf-8-validate

1. 用 electron-rebuild 重新编一次（针对你当前 Electron 版本）

npx electron-rebuild -f -w bufferutil utf-8-validate

国内网络差可换镜像

npm_config_electron_mirror=https://npmmirror.com/mirrors/electron/ npx electron-rebuild -f -w bufferutil utf-8-validate

三、验证

npm run dev        # 不再抛 Error
npm run build:mac  # 打包后双击 App 正常启动

四、原理一句话

• ws 只是“可选”依赖这两个原生模块；
• Vite/Rollup 默认会把 require() 全部静态扫描并打包，找不到就崩；
• 把模块标记为 external 后，运行时会走 Node 正常查找路径，找不到就退化，功能无损。

30 秒复盘

1. 在 electron.vite.config.ts → main.external 里加 ['bufferutil', 'utf-8-validate']；
2. （可选）npm i -D bufferutil utf-8-validate && electron-rebuild；
3. 重新 npm run dev 世界安静。