Vite 桌面应用实战：Electron 与 Tauri 的工程化落地

需要全平台像素级一致、依赖大量 Node 原生模块 → Electron
追求极小体积与低内存、愿意引入 Rust → Tauri
需要调用冷门系统 API → 先确认 Tauri 是否有官方或社区插件

主进程    → 创建窗口、访问文件系统、菜单与托盘（Node/Rust 侧）
预加载脚本 → 在渲染前运行，用 contextBridge 暴露受控 API（桥接层）
渲染进程  → 就是你的 Vite 前端应用（浏览器环境）

my-app/
├─ src/                 # 渲染进程（Vite 工程）
├─ electron/            # 壳层：main.ts 主进程、preload.ts 预加载
├─ index.html           # Vite 入口 HTML
└─ vite.config.ts

// vite.config.ts
export default defineConfig({
  plugins: [
    electron([
      { entry: 'electron/main.ts' },
      { entry: 'electron/preload.ts', onstart: (a) => a.reload() },
    ]),
  ],
})

// electron/main.ts
const DEV_URL = process.env.VITE_DEV_SERVER_URL

function createWindow() {
  const win = new BrowserWindow({
    webPreferences: { preload: `${__dirname}/preload.js` },
  })
  if (DEV_URL) win.loadURL(DEV_URL)
  else win.loadFile(`${__dirname}/../dist/index.html`)
}

渲染进程代码改动 → Vite HMR 直接热替换，无需重启
预加载脚本改动   → 需要 reload 窗口（onstart 里调 reload）
主进程代码改动   → 必须重启整个 Electron 进程

export default defineConfig({
  base: './',
})

Hash 模式（createWebHashHistory）  → file:// 下开箱可用，推荐
History 模式（createWebHistory）   → file:// 下刷新会 404，需自定义协议

win.loadFile(path.join(__dirname, '../dist/index.html'))

# 期望看到 ./assets/index-xxxx.js 而非 /assets/index-xxxx.js
grep -o 'src="[^"]*"' dist/index.html | head

new BrowserWindow({
  webPreferences: {
    contextIsolation: true,
    nodeIntegration: false,
    preload: path.join(__dirname, 'preload.js'),
  },
})

// electron/preload.ts
contextBridge.exposeInMainWorld('api', {
  readConfig: () => ipcRenderer.invoke('config:read'),
})
// 主进程侧
ipcMain.handle('config:read', async () => readConfigFromDisk())

// shared/ipc.ts
export interface AppApi {
  readConfig(): Promise<AppConfig>
}
declare global { interface Window { api: AppApi } }

// Electron 侧
autoUpdater.autoDownload = false
autoUpdater.checkForUpdates()
autoUpdater.on('update-available', () => {
  // 提示用户，确认后调用 autoUpdater.downloadUpdate()
})

macOS → Apple Developer 证书 + 公证（notarization），否则 Gatekeeper 拦截
Windows → 代码签名证书，否则 SmartScreen 警告
Linux → 无强制签名，用 AppImage/deb/rpm 分发

Electron → electron-builder / electron-forge
Tauri    → tauri build（内置打包与签名流程）

- 首屏不做重初始化，把非关键逻辑延迟到窗口显示后
- 主进程与渲染进程并行启动，别串行等待
- 前端首包做代码分割，先渲染骨架再加载功能

// 窗口内容就绪后再显示，避免白屏闪烁
win.once('ready-to-show', () => win.show())

永远用 path.join / app.getPath，别手写斜杠拼接
用户数据写 app.getPath('userData')，别写死在安装目录
文件名大小写：Windows 不敏感、Linux 敏感，引用资源时保持一致

每个平台必须在对应系统上构建（或使用 CI 的对应 runner）
macOS 的公证、Windows 的签名都依赖各自平台的工具链
交叉编译 Electron 不现实，Tauri 跨编译也需额外配置

Electron → 用 --inspect 启动，Chrome 的 chrome://inspect 附加调试
Tauri    → Rust 侧用 println!/log crate，前端侧仍是 DevTools

- 统一日志出口：主进程写文件，渲染进程经 IPC 汇总
- 捕获 uncaughtException 与 render-process-gone，写入崩溃日志
- 生产环境保留日志滚动，避免无限增长

app.on('render-process-gone', (_e, _wc, details) => logCrash(details.reason))

□ 渲染层 base 为相对路径，路由优先 Hash 模式
□ contextIsolation 开启、nodeIntegration 关闭
□ 系统能力全部经 contextBridge 暴露并带类型
□ 预加载脚本构建格式为 CJS
□ 自动更新链路已接通并做了版本比对
□ macOS 公证、Windows 签名证书已进 CI 密钥
□ 窗口 ready-to-show 后再显示，首包做了代码分割

选型看体积与一致性（Electron vs Tauri）
联调看地址注入（dev server URL）
构建看路径协议（base 相对 + Hash 路由）
安全看桥接边界（preload + contextBridge）
发布看签名更新（公证 + updater）