Electron-Builder 中如何正确处理 node_modules 中的示例文件

在 Electron 应用开发过程中，使用 electron-builder 打包时经常会遇到 node_modules 中某些文件被意外排除的问题。特别是像 Three.js 这样的流行库，其示例文件通常存放在 node_modules/three/examples/ 目录下，这些文件在实际开发中非常有用，但默认情况下会被 electron-builder 排除在最终打包产物之外。

问题背景

electron-builder 出于优化打包体积的考虑，默认会排除 node_modules 中的一些非必要文件，包括测试文件、示例文件等。这种默认行为虽然能减小应用体积，但当开发者确实需要使用这些被排除的文件时，就会遇到问题。

对于 Three.js 这样的库，其 examples 目录下包含了许多实用的模块和示例代码，开发者可能会在自己的项目中直接引用这些模块。如果这些文件被打包工具排除，就会导致运行时错误。

解决方案

方法一：使用 onNodeModuleFile 钩子

electron-builder 提供了 onNodeModuleFile 配置项，允许开发者自定义对 node_modules 中文件的处理逻辑。通过这个钩子，可以强制包含特定路径的文件：

{
  onNodeModuleFile: filePath => {
    return filePath.includes('node_modules/three/examples')
  }
}

注意跨平台兼容性，Windows 系统需要使用反斜杠路径分隔符：

{
  onNodeModuleFile: filePath => {
    return filePath.includes('node_modules/three/examples') || 
           filePath.includes('node_modules\\three\\examples')
  }
}

或者更优雅地使用 path.sep 实现跨平台兼容：

const path = require('path')
{
  onNodeModuleFile: filePath => {
    return filePath.includes(`node_modules${path.sep}three${path.sep}examples`)
  }
}

方法二：使用 files 配置覆盖默认排除规则

electron-builder 的 files 配置理论上应该能够覆盖默认的排除规则。开发者可以尝试以下配置：

{
  files: [
    "**/*",
    "**/node_modules/*/examples/**/*"
  ]
}

但需要注意的是，在 electron-builder 24.13.3 版本中，默认排除规则的优先级较高，这种方法可能不会生效。不过，社区已经意识到这个问题，并在后续版本中进行了改进。

方法三：使用 disableDefaultIgnoredFiles 配置

在 electron-builder 的较新版本中，新增了 disableDefaultIgnoredFiles 配置项，可以完全禁用默认的文件排除规则：

{
  disableDefaultIgnoredFiles: true
}

这个选项给了开发者更大的控制权，特别是当项目确实需要包含那些通常会被排除的文件时。

最佳实践建议

1. 精确包含：尽量避免使用过于宽泛的包含规则，而是精确指定需要包含的文件路径，这有助于控制最终打包体积。

2. 跨平台考虑：处理文件路径时始终考虑跨平台兼容性，使用 path 模块来处理路径分隔符。

3. 版本适配：检查使用的 electron-builder 版本，新版本提供了更灵活的文件包含控制选项。

4. 性能权衡：在包含大量额外文件前，评估其对应用启动时间和体积的影响，特别是对于 Electron 应用来说，体积控制尤为重要。

总结

electron-builder 的文件包含/排除机制虽然默认会优化打包结果，但也提供了多种方式让开发者能够按需调整。理解这些机制并根据项目需求合理配置，可以确保所有必要的资源文件都被正确包含在最终的应用包中。随着 electron-builder 的持续更新，文件包含的控制也变得更加灵活和直观。