解决electron-builder在Windows构建时文件路径过长的问题

问题背景

在使用electron-builder构建Electron应用时，许多开发者遇到了一个常见问题：在Windows环境下，特别是使用pnpm作为包管理器时，构建过程中会出现"!include: could not open file"的错误。这个问题主要出现在GitHub Actions等CI环境中，但有时也会在本地开发环境中出现。

问题表现

错误信息通常如下所示：

!include: could not open file: "...\node_modules\.pnpm\app-builder-lib@25.0.0-alpha.6...\node_modules\app-builder-lib\templates\nsis\include\StdUtils.nsh"
Error in script "<stdin>" on line 1 -- aborting creation process

根本原因

这个问题主要由以下几个因素共同导致：

1. Windows文件路径长度限制：尽管现代Windows系统已经支持长路径，但某些工具和场景下仍然存在限制。

2. pnpm的虚拟存储结构：pnpm使用硬链接和符号链接来管理依赖，这会导致node_modules目录结构比npm/yarn更深。

3. CI环境的工作目录：GitHub Actions等CI平台通常会在较深的目录路径下运行构建，进一步加剧了路径长度问题。

4. electron-builder的NSIS脚本引用：构建过程中需要引用位于node_modules深处的NSIS脚本文件。

解决方案

1. 降级electron-builder版本

临时解决方案是降级到已知可用的版本：

• electron-builder 24.9.1
• electron-builder 24.13.0

2. 配置pnpm的虚拟存储路径

在项目根目录的.npmrc文件中添加以下配置：

virtual-store-dir-max-length=80

这个配置会限制pnpm创建的虚拟存储目录的路径长度。需要注意的是：

• 修改配置后需要重新运行pnpm install
• 对于monorepo项目，需要在根目录的.npmrc中配置

3. 启用Windows长路径支持

虽然GitHub Actions的Windows环境默认已启用长路径支持，但在本地开发环境中可以执行以下PowerShell命令确保启用：

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

4. 调整项目目录结构

将项目放在更接近根目录的位置，例如：

• 不推荐：C:\Users\username\long\path\to\project
• 推荐：C:\projects\my-project

最佳实践建议

1. 版本兼容性：目前推荐使用electron 30.x + electron-builder 24.9.1的组合

2. CI环境优化：

   • 在GitHub Actions中，优先使用pnpm的路径长度限制配置
   • 确保构建步骤在修改.npmrc后执行pnpm install

3. 长期解决方案：

   • 关注electron-builder的未来版本更新
   • 考虑向electron-builder项目提交改进建议

总结

Windows环境下的文件路径长度限制与pnpm的目录结构设计相结合，导致了electron-builder构建过程中的文件访问问题。通过合理配置pnpm或调整electron-builder版本，开发者可以有效解决这一问题。随着工具的不断演进，这个问题有望在未来的版本中得到根本性解决。