Electron Builder打包后菜单栏窗口仅显示透明界面而非指定路由

生产环境中，菜单栏窗口仅呈现透明界面，无法加载指定路由内容；但开发环境运行完全正常，引导页等其他窗口可正常加载对应路由。应用就绪后会先检查引导页完成状态，再打开菜单栏窗口，路由配置与上一版本无任何修改。

创建菜单栏的代码 #

const createMenubar = () => {
  //our window you can chanege the size  and other

  const devServerURL = createURLRoute("http://localhost:3000", "onboarding");

  const fileRoute = createFileRoute(
    path.join(__dirname, "../", "index.html"),
    "onboarding"
  );

  window = new BrowserWindow({
    width: 550,
    height: 675,
    show: false,
    resizable: false,
    frame: false,
    fullscreenable: false,
    transparent: true,
    minimizable: false,
    maximizable: false,
    webPreferences: {
      nodeIntegration: false, // Default is false
      contextIsolation: true, // Default is true
      preload: path.join(__dirname, "preload.js"), // Use of preload.jsc
      backgroundThrottling: false,
      devTools: true,
    },
  });

  !app.isPackaged
    ? window.loadURL(devServerURL)
    : window.loadFile(...fileRoute);

  createTray();

  window.on("blur", () => {
    window.hide();
  });

  window.on("show", () => {
    // app.on("did-become-active", (event, data) => {
    if (window) window.webContents.send("app-opened", true);
    // });
  });

  window.on("ready-to-show", () => {
    // console.log(process.env);

    toggleWindow();
    setTimeout(() => {
      window.webContents.send("set-user-status", true);
    }, 1000);

    window.webContents.on("before-input-event", (event, input) => {
      console.log(input);

      if (input.meta && input.key.toLowerCase() === "q") {
        event.preventDefault();

        window.webContents.send("set-user-status", false);

        setTimeout(() => {
          app.exit();
        }, 1000);
      }
    });

    if (!app.isPackaged) window.webContents.openDevTools({ mode: "detach" });

    // window.webContents.on('before-input-event', (event, input) => {
    //   if (input.control && input.key.toLowerCase() === 'i') {
    //     console.log('Pressed Control+I')
    //     event.preventDefault()
    //   }
    // })

    //

    // window.webContents.send("alert", "checking for updates");

    
    if (app.isPackaged) {
    }
    // .then((response) => {
    //   window.webContents.send("alert", `updates response: ${response}`);
    // })
    // .catch((err) => {
    //   window.webContents.send("alert", `updates error: ${err}`);
    // });
  });

  // process.on("exit", () => {
  //   window.webContents.send("set-user-status", false);
  // });
};

创建引导页窗口的代码 #

const createOnboardingWindow = (data) => {
  if (onboardingWindow) onboardingWindow.close();

  //our window you can chanege the size  and other

  onboardingWindow = new BrowserWindow({
    width: parseInt(width * 0.7),
    height: parseInt(height * 0.8),
    maxWidth: windowSize.width,
    maxHeight: windowSize.height,
    transparent: true,
    resizable: true,
    frame: false,
    show: false,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: true, // Default is true
      preload: path.join(__dirname, "preload.js"), // Use of preload.jsc
      backgroundThrottling: false,
    },
  });

  const xSpacing = parseInt((width - windowSize.width) / 2);
  const ySpacing = parseInt((height - windowSize.height) / 2) + 20;

  onboardingWindow.setPosition(xSpacing, ySpacing, false);

  const devServerURL = createURLRoute("http://localhost:3000", "onboarding");

  const fileRoute = createFileRoute(
    path.join(__dirname, "../", "index.html"),
    "onboarding"
  );

  !app.isPackaged
    ? onboardingWindow.loadURL(devServerURL)
    : onboardingWindow.loadFile(...fileRoute);

  // Automatically open Chrome's DevTools in development mode.
  if (!app.isPackaged) {
    onboardingWindow.webContents.openDevTools();
  }

  if (process.defaultApp) {
    if (process.argv.length >= 2) {
      app.setAsDefaultProtocolClient("meetingReminder", process.execPath, [
        path.resolve(process.argv[1]),
      ]);
    }
  } else {
    app.setAsDefaultProtocolClient("meetingReminder");
  }

  return onboardingWindow;
};

路由配置 #

menubar={
          <>
            <Route path="/" element={<App />} />
            <Route path="/signin" element={<Signin />} />
            <Route path="/settings" element={<Settings />} />
          </>
        }
        onboarding={
          <>
            <Route path="/" element={<Onboarding />} />
            <Route path="/signup" element={<Onboarding />} />
            <Route path="/verifyphone" element={<Onboarding />} />
            <Route path="/welcome" element={<Onboarding />} />
          </>
        }
        notification={
          <>
            <Route path="/" element={<Notify />} />
          </>
        }
        alert={
          <>
            <Route path="/" element={<Alert />} />
          </>
        }

排查与解决方案 #

1. 修正路由参数匹配
   菜单栏窗口的createURLRoute和createFileRoute都传入了"onboarding"参数，但实际对应路由是menubar配置下的路径。生产环境中加载文件时未切换到正确的路由上下文，导致页面找不到内容显示透明。

   • 解决：将菜单栏窗口的路由参数从"onboarding"改为"menubar"，确保路由生成函数能指向正确的菜单栏目录或路由分支；或在页面加载后通过IPC通知前端切换到菜单栏路由。

2. 调整窗口显示时机
   菜单栏窗口设置了transparent: true，生产环境页面渲染可能延迟，导致窗口先显示透明背景，后续内容未及时渲染。

   • 解决：将toggleWindow()的调用从ready-to-show事件移到did-finish-load事件中，确保页面内容完全加载后再显示窗口：

     window.webContents.on('did-finish-load', () => {
       toggleWindow();
     });
     

3. 临时开启生产环境DevTools排查
   生产环境默认关闭DevTools，无法查看页面报错信息。

   • 解决：临时修改代码强制开启菜单栏窗口的DevTools，查看是否有资源加载失败、路由匹配错误等报错：

     // 去掉环境判断，强制打开
     window.webContents.openDevTools({ mode: "detach" });
     

4. 修正生产环境文件路径
   打包后path.join(__dirname, "../", "index.html")的相对路径可能失效，导致加载的HTML文件错误。

   • 解决：使用Electron提供的app.getAppPath()构建绝对路径：

     const fileRoute = createFileRoute(
       path.join(app.getAppPath(), "index.html"),
       "menubar"
     );
     

5. 检查预加载脚本兼容性
   菜单栏窗口nodeIntegration: false，而引导页是true，如果预加载脚本中有依赖Node API的未暴露逻辑，会导致菜单栏页面渲染失败。

   • 解决：检查preload.js代码，确保仅使用contextBridge暴露的API，避免直接调用Node模块。

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