以下是创建 Electron + Vite + React 项目的详细步骤，结合了现代前端工具链和桌面应用开发的最佳实践：

步骤 1: 创建 Vite + React 基础项目

首先使用 Vite 初始化一个 React 项目：

# 创建 Vite 项目
npm create vite@latest electron-vite-react -- --template react

# 进入项目目录
cd electron-vite-react

# 安装依赖
npm install

步骤 2: 安装 Electron 相关依赖

需要安装 Electron 核心及开发辅助工具：

# 安装 Electron 核心（生产依赖）
npm install electron --save-dev

# 安装 Electron 与 Vite 集成工具（解决热更新和打包问题）
npm install electron-vite --save-dev

# 安装路径处理工具（Electron 常用）
npm install path --save

步骤 3: 配置项目结构

调整项目目录为 Electron 规范结构：

electron-vite-react/
├── src/
│   ├── main/             # Electron 主进程代码
│   │   └── index.js      # 主进程入口
│   ├── renderer/         # React 渲染进程代码（原 src 目录内容）
│   │   ├── App.jsx
│   │   ├── index.css
│   │   └── main.jsx
│   └── preload/          # 预加载脚本（进程通信桥梁）
│       └── index.js
├── index.html            # 渲染进程入口 HTML
├── package.json          # 项目配置
└── vite.config.js        # Vite 配置

移动文件：

• 将原 src/ 目录下的所有文件（App.jsx, index.css, main.jsx）移动到 src/renderer/
• 创建 src/main/ 和 src/preload/ 目录

步骤 4: 配置 Vite 与 Electron

1. 配置 vite.config.js

让 Vite 分别处理主进程、渲染进程和预加载脚本：

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { join } from 'path'

// 路径解析函数
const resolve = (dir) => join(__dirname, dir)

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': resolve('src/renderer') // 渲染进程代码别名
    }
  },
  build: {
    outDir: 'dist/renderer', // 渲染进程打包目录
    emptyOutDir: true
  },
  server: {
    port: 3000 // 开发服务器端口，与 Electron 配置一致
  }
})

2. 创建 Electron 配置文件 electron.vite.config.js

用于 electron-vite 工具的配置：

// electron.vite.config.js
import { defineConfig } from 'electron-vite'
import { join } from 'path'

const resolve = (dir) => join(__dirname, dir)

export default defineConfig({
  main: {
    build: {
      outDir: 'dist/main', // 主进程打包目录
      rollupOptions: {
        input: resolve('src/main/index.js') // 主进程入口
      }
    }
  },
  preload: {
    build: {
      outDir: 'dist/preload', // 预加载脚本打包目录
      rollupOptions: {
        input: resolve('src/preload/index.js') // 预加载入口
      }
    }
  },
  renderer: {
    // 复用 Vite 配置
    extends: 'vite.config.js'
  }
})

步骤 5: 编写核心代码

1. 主进程代码（src/main/index.js）

负责创建窗口和 Electron 核心逻辑：

// src/main/index.js
import { app, BrowserWindow } from 'electron'
import { join } from 'path'

// 开发环境判断
const isDev = process.env.NODE_ENV === 'development'

// 创建窗口函数
function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: join(__dirname, '../preload/index.js'), // 预加载脚本路径
      contextIsolation: true, // 开启上下文隔离（安全最佳实践）
      nodeIntegration: false // 关闭 Node 集成
    }
  })

  // 加载页面（开发环境加载 Vite 服务器，生产环境加载本地文件）
  if (isDev) {
    mainWindow.loadURL('http://localhost:3000')
    mainWindow.webContents.openDevTools() // 开发环境自动打开调试工具
  } else {
    mainWindow.loadFile(join(__dirname, '../../index.html'))
  }
}

// 应用就绪后创建窗口
app.whenReady().then(createWindow)

// 关闭所有窗口时退出应用（macOS 除外）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

// macOS 激活应用时重新创建窗口
app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) createWindow()
})

2. 预加载脚本（src/preload/index.js）

安全暴露 Electron API 给 React 渲染进程：

// src/preload/index.js
import { contextBridge, ipcRenderer } from 'electron'

// 向渲染进程暴露有限的 API
contextBridge.exposeInMainWorld('electronAPI', {
  // 示例：获取 Electron 版本
  getElectronVersion: () => process.versions.electron,
  // 示例：主进程通信（后续可扩展硬件交互等功能）
  sendMessage: (message) => ipcRenderer.invoke('handle-message', message)
})

3. 渲染进程 React 组件（src/renderer/App.jsx）

使用预加载脚本暴露的 API：

// src/renderer/App.jsx
import { useState } from 'react'
import './index.css'

function App() {
  const [electronVersion, setElectronVersion] = useState('')
  const [message, setMessage] = useState('')
  const [response, setResponse] = useState('')

  // 获取 Electron 版本
  const getVersion = () => {
    // 调用预加载脚本暴露的 API
    const version = window.electronAPI.getElectronVersion()
    setElectronVersion(`Electron 版本: ${version}`)
  }

  // 与主进程通信
  const sendToMain = async () => {
    if (!message) return
    const res = await window.electronAPI.sendMessage(message)
    setResponse(`主进程回复: ${res}`)
  }

  return (
    <div className="App">
      <h1>Electron + Vite + React</h1>
      <button onClick={getVersion}>获取 Electron 版本</button>
      <p>{electronVersion}</p>

      <div style={{ marginTop: 20 }}>
        <input
          type="text"
          value={message}
          onChange={(e) => setMessage(e.target.value)}
          placeholder="输入消息发送给主进程"
        />
        <button onClick={sendToMain}>发送</button>
        <p>{response}</p>
      </div>
    </div>
  )
}

export default App

4. 调整渲染进程入口（src/renderer/main.jsx）

确保 React 正确挂载：

// src/renderer/main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

步骤 6: 配置 package.json 脚本

添加启动和打包脚本：

{
  "name": "electron-vite-react",
  "private": true,
  "version": "0.0.0",
  "main": "dist/main/index.js", // 主进程入口（打包后路径）
  "scripts": {
    "dev": "electron-vite dev", // 开发模式（同时启动 Vite 和 Electron）
    "build": "electron-vite build", // 打包所有进程代码
    "preview": "electron-vite preview" // 预览打包结果
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "path": "^0.12.7"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.0.1",
    "electron": "^25.3.1",
    "electron-vite": "^1.0.25",
    "vite": "^4.4.5"
  }
}

步骤 7: 测试项目

1. 启动开发环境：

   npm run dev

   会自动打开 Electron 窗口，显示 React 应用，且支持热更新。

2. 测试功能：

   • 点击「获取 Electron 版本」按钮，应显示当前 Electron 版本
   • 在输入框输入文本并点击「发送」，会通过 IPC 与主进程通信（需在主进程添加对应监听逻辑，见下方扩展）

扩展：完善主进程通信逻辑

在 src/main/index.js 中添加 IPC 监听，处理渲染进程的消息：

// 在 createWindow 函数上方添加
import { ipcMain } from 'electron'

// 监听渲染进程的消息
ipcMain.handle('handle-message', (event, message) => {
  console.log('收到渲染进程消息:', message)
  return `已收到: ${message}（来自主进程）` // 回复渲染进程
})

打包应用（可选）

如果需要打包为可执行文件，推荐使用 electron-builder：

# 安装打包工具
npm install electron-builder --save-dev

在 package.json 中添加打包脚本和配置：

{
  "scripts": {
    "dist": "electron-vite build && electron-builder"
  },
  "build": {
    "appId": "com.example.electron-vite-react",
    "productName": "ElectronViteReact",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*"
    ]
  }
}

执行打包：

npm run dist

通过以上步骤，你已经搭建了一个功能完整的 Electron + Vite + React 项目，支持开发热更新、进程间安全通信，并且可以打包为桌面应用。项目架构遵循 Electron 安全最佳实践，适合后续扩展硬件交互等功能。