Electron结合React、TypeScript应用经electron-builder打包后启动空白问题

落地排查步骤 #

1. 修正React前端的静态资源路径配置 #

这是该场景下最高发的问题诱因

• 打开React项目根目录的package.json，新增配置项"homepage": "./"，修改完成后重新执行react-scripts build生成前端构建产物
• 触发原理：react-scripts默认会以站点根绝对路径引用所有静态资源，Electron生产环境通过file://协议加载本地文件时，绝对路径会被解析为磁盘根路径，所有JS、CSS资源都会触发404，最终渲染为空白界面

2. 校准主进程的窗口加载逻辑 #

检查Electron主进程的窗口创建代码，避免生产环境硬编码开发服务地址、使用无层级的裸相对路径：

• 适配开发/生产环境的正确加载逻辑参考：

  import { app, BrowserWindow } from 'electron'
  import path from 'path'
  
  function createWindow() {
    const mainWindow = new BrowserWindow({
      width: 1200,
      height: 800,
      webPreferences: {
        preload: path.join(__dirname, '../preload/index.js')
      }
    })
  
    // 开发环境加载本地dev服务，生产环境加载本地构建好的index.html
    if (!app.isPackaged) {
      mainWindow.loadURL('http://localhost:3000')
    } else {
      mainWindow.loadFile(path.join(__dirname, '../build/index.html'))
    }
  
    // 临时调试：自动打开DevTools查看控制台报错
    mainWindow.webContents.openDevTools()
  }
  

• 常见踩坑：路径拼接时要对应Electron主进程的编译输出目录，确认当前代码的层级关系能正确定位到前端build目录下的index.html，避免生产环境加载空路径

3. 核对electron-builder的打包配置 #

• 检查electron-builder配置（通常存于package.json的build字段，或独立的electron-builder.yml文件）的files规则，确保两类核心资源被纳入打包范围：
  • React构建生成的build目录（存储前端入口文件、静态资源）
  • TypeScript编译Electron主进程、preload脚本生成的输出目录（如dist-electron）
• 确认package.json根级别的main字段，指向的是Electron编译后的主进程入口文件，不要保留最初触发报错的错误路径build/electron.js，避免出现主进程逻辑错位、窗口加载路径失效的问题

4. 通过控制台报错定位具体问题 #

临时在主进程代码中开启DevTools自动打开配置，运行打包后的exe后，直接根据控制台报错定向排查：

• 若看到大量静态资源404报错，回到第1步检查homepage配置和路径拼接逻辑
• 若看到CORS跨域拦截报错，检查webPreferences中的webSecurity配置，按需放开本地文件的访问权限
• 若看到路由解析报错，将React Router的BrowserRouter替换为HashRouter，适配file协议下的路由解析规则

内容的提问来源于stack exchange，提问作者Lucas