故障排除 ​

请参阅 Vite 的故障排除指南 和 Rollup 的故障排除指南 了解更多信息。

如果这里的建议并未帮助到你，你可以去 GitHub issue tracker 查看是否有人已经遇到相同的问题。如果你发现了 bug，或者 electron-vite 不能满足你的需求，欢迎提交 issue 或在 GitHub 讨论区 发帖提问。

技巧 ​

通过以下几个步骤，你可以很快找到问题所在：

1. 在开发模式（dev）下，可以使用 debugger 方式断点调试问题。
2. 打包前，先执行 preview 命令，预览打包后的情况，更早发现问题。
3. 打包后，可以附加参数 --trace-warnings 到应用程序运行，查看错误信息。例如： .\app.exe --trace-warnings （在 Windows 中）， open app.app --args --trace-warnings （在 MacOS 中）。
4. 通常 preview 命令运行正常，而打包后不正常，大概率是依赖模块未被打包进应用程序，请检查依赖模块是否安装在 dependencies 中，也可能是 pnpm 问题（如果使用了的话）。

迁移 ​

The CJS build of Vite's Node API is deprecated ​

从 Vite 5 开始，调用 Vite 的 CJS Node API 时，会收到弃用警告日志。 electron-vite 2 现已发布为 ESM，你可以更新到最新版本。

此外，你还需要确保：

1. electro.vite.config.js 配置文件的内容使用 ESM 语法。
2. 最近的 package.json 文件中有 "type": "module" ，或者使用 .mjs 扩展名，例如 electron.vite.config.mjs 。

请注意，在项目 package.json 中添加 "type": "module" 时，如果 Electron 支持 ESM (Electron 28+)，则会构建为 ESM，需要先阅读 Electron 的 ESM 支持 指南。但如果不支持 ESM，它将被构建为 CommonJS，并且所有文件都将具有 .cjs 扩展名。

如果你不想进行任何更改并保持打包成 CJS，最好的方式是将 electro.vite.config.js 重命名为 electro.vite.config.mjs 。

开发 ​

Unable to load preload scripts -> Error: module not found: 'XXX' ​

从 Electron 20 开始，预加载脚本默认沙盒化，不再拥有完整 Node.js 环境的访问权。

你可以选择以下两种修改方式：

1. 为 BrowserWindow 指定 sandbox: false 。
2. 重构预加载脚本以从渲染器中删除 Node 使用并将其打包成一个文件（不支持 require 多个文件）。

Uncaught Error: Module "XXX" has been externalized for browser compatibility. or Uncaught ReferenceError: __dirname is not defined ​

目前，electron-vite 不支持 nodeIntegration。其中一个重要的原因是 Vite 的 HMR 是基于原生 ESM 实现的。

推荐使用 预加载脚本 进行开发，避免将 Node.js 模块用于渲染器代码。如果你想这样做，你可以手动添加 polyfills，更多详情见 nodeIntegration 。

• 相关: nodeIntegration
• 相关: Module externalized for browser compatibility

构建 ​

Error [ERR_REQUIRE_ESM]: require() of ES Module ​

Electron 不支持 ESM ，所以主进程和预加载脚本的构建标准仍然是 CJS 。发生此错误是因为模块被外部化了。对于支持 CJS 的模块，我们最好将其外部化。对于只支持 ESM 的模块（例如 lowdb、execa、node-fetch 等），我们不应该将其外部化。我们应该让 electron-vite 把它打包成一个 CJS 标准模块来支持 Electron。

要解决这个问题：

import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
export default defineConfig({
  main: {
    plugins: [externalizeDepsPlugin({ exclude: ['foo'] })] // <- Add related modules to 'exclude' option
  // ...
})

import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
export default defineConfig({
  main: {
    plugins: [externalizeDepsPlugin({ exclude: ['foo'] })] // <- Add related modules to 'exclude' option