使用 Electron 与 Next.js 13.4 构建桌面应用指南

霞舞

发布时间：2025-08-14 21:06:02

317人浏览过

来源于php中文网

原创

使用 Electron 与 Next.js 13.4 构建桌面应用指南

本文详细介绍了如何将 Electron 与 Next.js 13.4 集成以构建桌面应用程序。由于缺乏现成的样板，文章重点阐述了手动配置方法，包括将后端服务（如 CRUD 和事件处理）部署在 Electron 主进程中，并通过进程间通信机制实现主进程与渲染进程的数据交换。文中提供了开发环境搭建、构建脚本配置以及 Next.js 导出设置的具体指导，并特别强调了 Next.js Pages 路由相对于 App 路由在当前集成方案中的优势。

1. 概述与核心思路

在当前阶段，将 electron 与 next.js 13.4 结合构建桌面应用，通常需要进行手动配置，而非依赖现有的集成样板。其核心思想是将应用程序的后端服务（如数据操作 crud、事件处理等）逻辑放置在 electron 的主进程中执行，而不是利用 next.js 的 api 路由。渲染进程（即 next.js 界面）与主进程之间的数据通信和事件交互，则通过 electron 提供的进程间通信（ipc）机制实现，通常结合预加载脚本（preload script）和 react 的 context api 在渲染层进行数据管理。

为了提供类似单页应用（SPA）的客户端路由体验，可以借助 electron-serve 等 NPM 包来管理 Next.js 导出的静态文件。

2. 项目结构与开发环境配置

建议采用清晰的项目目录结构，将 Next.js 应用和 Electron 主进程代码分开管理，例如：

rootdir/
├── app/  # Next.js 应用目录
└── main/ # Electron 主进程代码目录

2.1 安装依赖

首先，在项目根目录（rootdir）下初始化 package.json，并安装必要的依赖：

npm init -y
npm install electron next react react-dom concurrently electron-builder electron-serve

electron: Electron 框架本身。
next, react, react-dom: Next.js 及其 React 依赖。
concurrently: 用于并发运行 Next.js 和 Electron 开发服务器。
electron-builder: 用于打包和分发 Electron 应用。
electron-serve: 用于在 Electron 中服务 Next.js 的静态导出文件。

2.2 package.json 脚本配置

为了方便开发和构建，需要在 package.json 中配置相应的脚本。concurrently 工具可以帮助我们同时启动 Next.js 开发服务器和 Electron 进程，从而简化开发流程和调试。

// rootdir/package.json
{
  "name": "electron-next-app",
  "version": "1.0.0",
  "main": "main/index.js", // 指定 Electron 主进程入口文件
  "scripts": {
    "dev": "concurrently -n \"NEXT,ELECTRON\" -c \"yellow,blue\" --kill-others \"next dev\" \"electron .\"",
    "build": "next build && next export && electron-builder",
    "start": "electron ."
  },
  "devDependencies": {
    "concurrently": "^8.2.2",
    "electron-builder": "^24.9.1"
  },
  "dependencies": {
    "electron": "^28.0.0",
    "electron-serve": "^1.2.0",
    "next": "^13.4.19",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

dev: 使用 concurrently 并发启动 Next.js 开发服务器 (next dev) 和 Electron 应用程序 (electron .)。-n 用于指定进程名称，-c 用于指定控制台颜色，--kill-others 确保一个进程退出时其他进程也随之关闭。
build: 首先执行 next build 编译 Next.js 应用，然后 next export 将其导出为静态文件，最后 electron-builder 将 Electron 应用打包。
start: 直接运行 Electron 应用，通常用于开发或测试已构建的版本。

3. Next.js 配置

Next.js 应用需要配置为导出静态文件，以便 Electron 能够加载。

3.1 next.config.js 配置

在 app 目录下的 next.config.js 文件中，进行以下配置：

// rootdir/app/next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // ... 其他 Next.js 配置
  output: "export", // 将 Next.js 应用导出为静态 HTML、CSS 和 JS 文件
  images: {
    unoptimized: true // 在静态导出模式下，禁用 Next.js Image 组件的图像优化功能
  }
  // ... 其他 Next.js 配置
};

module.exports = nextConfig;

output: "export": 这是关键配置，它告诉 Next.js 在构建时将应用程序导出为一组静态文件，而不是启动一个 Node.js 服务器。这些静态文件随后将被 Electron 加载。
images: { unoptimized: true }: 在静态导出模式下，Next.js 的 Image 组件的优化功能可能无法正常工作。设置 unoptimized: true 可以避免相关问题。

3.2 路由选择：Pages 路由 vs. App 路由

重要提示： 截至目前（Next.js 13.4 及更高版本），Next.js 的 App Router（引入了 Server Components 等特性）与 Electron 的单页应用（SPA）加载模式可能存在兼容性问题。这主要是因为 App Router 的某些功能依赖于 Node.js 服务器环境，而 Electron 在加载静态导出的 Next.js 应用时，更期望一个纯粹的客户端渲染环境。

因此，强烈建议在当前集成方案中优先使用 Next.js 的 Pages 路由。 如果您尝试使用 App Router 并成功使其工作，请务必分享您的经验。

4. Electron 主进程配置

Electron 主进程负责创建窗口、加载 Next.js 导出的内容、处理操作系统交互以及执行后端逻辑。

Ink For All

AI写作和营销助手，精心设计的 UI

下载

4.1 主进程入口文件 (main/index.js)

在 main 目录下创建 index.js 作为 Electron 的主进程入口文件。这里我们将使用 electron-serve 来加载 Next.js 的静态构建产物。

// rootdir/main/index.js
const { app, BrowserWindow, ipcMain } = require('electron');
const serve = require('electron-serve');
const path = require('path');

// 根据环境选择加载方式
const loadURL = serve({ directory: path.join(__dirname, '../out') }); // 'out' 是 Next.js 默认的导出目录

let mainWindow;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      nodeIntegration: false, // 禁用 Node.js 集成，提高安全性
      contextIsolation: true, // 启用上下文隔离
      preload: path.join(__dirname, 'preload.js') // 预加载脚本
    }
  });

  // 在开发模式下，加载 Next.js 开发服务器
  if (process.env.NODE_ENV === 'development') {
    mainWindow.loadURL('http://localhost:3000'); // Next.js 开发服务器默认端口
    mainWindow.webContents.openDevTools(); // 打开开发者工具
  } else {
    // 在生产模式下，加载 Next.js 导出的静态文件
    loadURL(mainWindow);
  }

  mainWindow.on('closed', () => {
    mainWindow = null;
  });
}

app.on('ready', createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (mainWindow === null) {
    createWindow();
  }
});

// 示例：主进程处理渲染进程的请求
ipcMain.handle('get-data-from-main', async (event, arg) => {
  console.log('Received request from renderer:', arg);
  // 这里可以执行文件读写、数据库操作、网络请求等
  return `Data from main process: ${arg} - ${new Date().toLocaleString()}`;
});

serve({ directory: path.join(__dirname, '../out') }): electron-serve 会将 Next.js 导出的静态文件（默认在 out 目录下）作为应用程序的根目录。
webPreferences:
- nodeIntegration: false: 禁用 Node.js 集成，这是 Electron 安全最佳实践。
- contextIsolation: true: 启用上下文隔离，防止预加载脚本和页面脚本之间直接访问彼此的全局对象。
- preload: path.join(__dirname, 'preload.js'): 指定一个预加载脚本，它会在页面加载之前运行，并可以安全地将 Electron API 暴露给渲染进程。
开发与生产模式区分：在 development 环境下，直接加载 Next.js 开发服务器的 URL；在生产环境下，使用 electron-serve 加载构建后的静态文件。
ipcMain.handle(): 示例展示了主进程如何监听来自渲染进程的请求并返回数据。

4.2 预加载脚本 (main/preload.js)

预加载脚本是连接主进程和渲染进程的关键。它在渲染进程的沙盒环境中运行，可以安全地将主进程的功能暴露给渲染进程，而不会暴露整个 Node.js 环境。

// rootdir/main/preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  getData: (arg) => ipcRenderer.invoke('get-data-from-main', arg),
  // 可以在这里暴露更多主进程功能
});

contextBridge.exposeInMainWorld('electronAPI', {...}): 这会将一个名为 electronAPI 的对象暴露给渲染进程的 window 对象。渲染进程可以通过 window.electronAPI.getData() 来调用主进程的功能。
ipcRenderer.invoke(): 用于向主进程发送请求并等待响应。

5. 渲染进程（Next.js）与主进程通信

在 Next.js 应用中，可以通过 window.electronAPI 来调用主进程暴露的功能。为了更好地管理这些功能，可以在 React Context 中封装它们。

// rootdir/app/pages/_app.js (或 app/layout.js for App Router)
import React, { createContext, useContext } from 'react';

// 创建一个 Context 来提供 Electron API
const ElectronApiContext = createContext(null);

export function useElectronApi() {
  return useContext(ElectronApiContext);
}

export default function MyApp({ Component, pageProps }) {
  // 确保在客户端渲染时才访问 window.electronAPI
  const electronApi = typeof window !== 'undefined' ? window.electronAPI : null;

  return (
    
      
    
  );
}

// rootdir/app/pages/index.js (示例页面)
import React, { useState, useEffect } from 'react';
import { useElectronApi } from '../pages/_app'; // 假设 _app.js 在 pages 目录下

export default function HomePage() {
  const electronApi = useElectronApi();
  const [data, setData] = useState('Loading...');

  useEffect(() => {
    if (electronApi) {
      electronApi.getData('Hello from Next.js').then((result) => {
        setData(result);
      }).catch(error => {
        console.error('Error fetching data from main process:', error);
        setData('Error fetching data.');
      });
    } else {
      setData('Electron API not available (running outside Electron)');
    }
  }, [electronApi]);

  return (
    
      Electron + Next.js 示例
      {data}
      
    
  );
}

6. 构建与打包

完成开发后，可以使用 electron-builder 将应用程序打包成可分发的安装包。

npm run build

这个命令会：

执行 next build 编译 Next.js 应用。
执行 next export 将 Next.js 应用导出为静态文件到 out 目录。
执行 electron-builder 根据 package.json 中的配置（或独立的 electron-builder.json）打包 Electron 应用。打包后的文件通常位于 dist 目录。

7. 注意事项与总结

手动配置是核心： 现有生态系统缺乏成熟的 Next.js 13.4 + Electron 样板，因此需要手动配置是当前的主要方法。
主进程承担后端： 将所有需要访问操作系统资源、进行数据持久化或复杂业务逻辑的功能，都放在 Electron 主进程中实现。
IPC 通信： 使用 Electron 的 ipcMain 和 ipcRenderer 结合预加载脚本和 contextBridge 进行安全高效的进程间通信。
Next.js 静态导出： 确保 Next.js 配置为 output: "export"，并处理好图像优化等相关问题。
Pages 路由优先： 鉴于当前 App Router 与静态导出和 Electron 集成的潜在兼容性问题，优先选择 Pages 路由。
安全性： 始终遵循 Electron 的安全最佳实践，如禁用 nodeIntegration，启用 contextIsolation，并谨慎暴露 API。