# Electron + Vue3 + TypeScript 项目

基于 [electron-vite](https://electron-vite.org/) 构建的现代化 Electron 应用模板。

## 技术栈

| 领域 | 技术 |
|------|------|
| 构建工具 | [electron-vite](https://electron-vite.org/) |
| 前端框架 | Vue 3 (Composition API) |
| 语言 | TypeScript |
| UI | 原生 HTML/CSS + Vue 组件 |

## 项目结构

```
├── electron.vite.config.ts    # Vite 配置（electron-vite 专用）
├── tsconfig*.json             # TypeScript 配置
├── src/
│   ├── main/                  # 主进程（Node.js 环境）
│   │   └── index.ts
│   ├── preload/               # 预加载脚本（桥接层）
│   │   ├── index.ts
│   │   └── index.d.ts        # 类型声明
│   └── renderer/              # 渲染进程（浏览器环境）
│       ├── index.html
│       └── src/
│           ├── main.ts        # Vue 入口
│           ├── App.vue
│           └── components/
│               └── Counter.vue
├── out/                       # 构建输出目录
└── package.json
```

## 核心概念

### 1. 三进程架构

Electron 有三个独立的进程：

```
┌─────────────────────────────────────────────────┐
│                   Main Process                   │
│  (Node.js) - 创建窗口、管理应用生命周期           │
│                    │                             │
│                    ▼                             │
│  ┌───────────────────────────────────────────┐  │
│  │              Preload Script                │  │
│  │  (上下文桥接，安全暴露 API 到渲染进程)       │  │
│  └───────────────────────────────────────────┘  │
│                    │                             │
│                    ▼                             │
│  ┌───────────────────────────────────────────┐  │
│  │            Renderer Process                │  │
│  │  (Chromium) - Vue 应用运行，DOM 操作        │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
```

**主进程 (main)**：运行 Node.js，负责窗口管理、应用生命周期、系统 API 调用

**预加载脚本 (preload)**：运行在渲染进程中，但能访问 Node.js API，通过 `contextBridge` 安全暴露有限 API

**渲染进程 (renderer)**：运行 Web 内容，Vue/React 应用在此执行，只能通过 IPC 与主进程通信

### 2. 上下文隔离 (Context Isolation)

```javascript
// main.js - 窗口配置
webPreferences: {
    contextIsolation: true,   // 启用上下文隔离
    nodeIntegration: false,    // 禁用 Node.js 访问
    preload: 'preload.js'     // 加载预加载脚本
}
```

- `contextIsolation: true` 防止渲染进程直接访问 Node.js，防止 XSS 攻击
- 渲染进程只能通过 `window.electron` 或 `window.api` 访问预暴露的 API

### 3. IPC 通信模式

```
Renderer                         Main
   │                               │
   │  ipcRenderer.invoke('xxx')    │
   │ ─────────────────────────────►│
   │                               │  ipcMain.handle('xxx', ...)
   │         Promise<Result>       │
   │ ◄─────────────────────────────│
   ▼                               ▼
```

```typescript
// preload - 暴露 IPC 通道
contextBridge.exposeInMainWorld('api', {
    getData: () => ipcRenderer.invoke('get-data')
})

// renderer - 调用
const data = await window.api.getData()

// main - 处理
ipcMain.handle('get-data', () => {
    return { message: 'Hello from main!' }
})
```

### 4. electron-vite 构建流程

```
┌─────────────────────────────────────────────────────────┐
│                    electron-vite dev                    │
├─────────────────────────────────────────────────────────┤
│  main    │  Vite (SSR)  →  out/main/index.js           │
│  preload │  Vite (ESM)  →  out/preload/index.mjs        │
│  renderer│  Vite + Vue  →  http://localhost:5173        │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                   electron-vite build                    │
├─────────────────────────────────────────────────────────┤
│  main    │  Vite (SSR)  →  out/main/index.js           │
│  preload │  Vite (ESM)  →  out/preload/index.mjs       │
│  renderer│  Vite + Vue  →  out/renderer/                │
└─────────────────────────────────────────────────────────┘
```

electron-vite 自动处理：
- 主进程和预加载脚本的 CommonJS/ESM 兼容
- 渲染进程的热模块替换 (HMR)
- 路径别名、依赖打包等

### 5. Vue 组件生命周期

```typescript
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'

const count = ref(0)
let timer: ReturnType<typeof setTimeout> | null = null

function updateCounter(): void {
    count.value++
    timer = setTimeout(updateCounter, 1000)
}

onMounted(() => {
    updateCounter()
})

onUnmounted(() => {
    if (timer) clearTimeout(timer)
})
</script>
```

- `onMounted` - 组件挂载时启动定时器
- `onUnmounted` - 组件卸载时清理定时器，防止内存泄漏

## 命令

```bash
# 开发模式（热重载）
npm run dev

# 生产构建
npm run build

# 运行已构建的应用
npm start

# 打包为可执行文件
npm run package
```

## 开发建议

1. **IPC 优先**：渲染进程不直接操作系统 API，通过 IPC 委托给主进程
2. **类型安全**：preload 的 API 声明在 `.d.ts` 文件中，renderer 可获得智能提示
3. **组件化**：UI 逻辑封装在 Vue 组件中，主进程只负责业务无关的系统操作
4. **清理资源**：组件卸载时务必清理定时器、事件监听器等

## TypeScript 配置

项目有 3 个 TypeScript 配置文件：

### tsconfig.json（根配置/入口）
```json
{
  "references": [
    { "path": "./tsconfig.node.json" },
    { "path": "./tsconfig.web.json" }
  ]
}
```
**作用**：项目总入口，本身不编译代码，通过 `references` 引用其他两个配置。

### tsconfig.node.json（Node.js 环境）
**对应**：`src/main/` + `src/preload/` + `electron.vite.config.ts`

```json
{
  "lib": ["ES2022"],
  "include": ["src/main/**/*", "src/preload/**/*", "electron.vite/**/*"]
}
```
**作用**：为主进程和预加载脚本提供类型检查，这两个运行在 Node.js 环境，需要 Node.js 内置类型（如 `process`、`path`、`fs`）。

### tsconfig.web.json（浏览器环境）
**对应**：`src/renderer/`

```json
{
  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  "jsx": "preserve",
  "jsxImportSource": "vue",
  "include": ["src/renderer/**/*"]
}
```
**作用**：为渲染进程（Vue 应用）提供类型检查，需要 DOM 类型（如 `window`、`document`、`HTMLElement`）和 Vue JSX 支持。

### 为什么分开？
```
┌─────────────────┐
│  tsconfig.json  │  ← 根配置，定义整体规则
└────────┬────────┘
         │
    references
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ node  │ │  web  │   ← 分别针对不同运行环境
│ .json │ │ .json │
└───┬───┘ └───┬───┘
    │         │
 Node.js    浏览器
 API 类型   DOM 类型
```

不同运行环境有不同的全局 API，分开配置可以：
- 避免类型冲突（Node.js 的 `global` vs 浏览器的 `window`）
- 按需引入类型库，减小检查范围
- IDE 根据当前文件路径自动选择对应配置

## 全部文件清单

| 文件 | 作用 |
|------|------|
| `package.json` | 项目配置：依赖、脚本、electron-builder 设置 |
| **`electron.vite.config.ts`** | **构建入口**：定义三个进程的入口路径、插件、别名 |
| `tsconfig.json` | TS 总入口，引用其他两个配置 |
| `tsconfig.node.json` | Node.js 环境配置（主进程、预加载） |
| `tsconfig.web.json` | 浏览器环境配置（渲染进程、Vue） |
| `src/main/index.ts` | Electron 主进程：创建窗口、管理应用生命周期、处理 IPC |
| `src/preload/index.ts` | 预加载脚本：通过 contextBridge 暴露安全 API |
| `src/preload/index.d.ts` | 预加载 API 的 TypeScript 类型声明 |
| `src/renderer/index.html` | 渲染进程 HTML 入口 |
| `src/renderer/src/main.ts` | Vue 应用入口 |
| `src/renderer/src/App.vue` | Vue 根组件 |
| `src/renderer/src/components/Counter.vue` | 计数器业务组件 |
| `out/` | 构建输出目录（`.gitignore` 忽略） |

## electron.vite.config.ts 详解

这是 electron-vite 的核心配置文件，作用类似普通 Vite 项目的 `vite.config.ts`，但需要为三个进程分别配置：

```typescript
import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  // ── 主进程配置 ──
  main: {
    plugins: [externalizeDepsPlugin()],  // 依赖外置，不打包进输出
    build: {
      rollupOptions: {
        input: { index: 'src/main/index.ts' }
      }
    }
  },

  // ── 预加载脚本配置 ──
  preload: {
    plugins: [externalizeDepsPlugin()],
    build: {
      rollupOptions: {
        input: { index: 'src/preload/index.ts' }
      }
    }
  },

  // ── 渲染进程配置 ──
  renderer: {
    root: 'src/renderer',                  // HTML 所在目录
    plugins: [vue()],                      // Vue 插件
    resolve: {
      alias: { '@': 'src/renderer/src' }   // 路径别名
    },
    build: {
      rollupOptions: {
        input: 'src/renderer/index.html'   // HTML 入口
      }
    }
  }
})
```

### 关键点

| 配置项 | 作用 |
|--------|------|
| `externalizeDepsPlugin()` | 将 `node_modules` 中的依赖转为 `require()` 引用，减小包体积 |
| `root: 'src/renderer'` | 告诉 Vite 渲染进程的 HTML 在哪个目录 |
| `plugins: [vue()]` | 在渲染进程启用 Vue 插件，处理 `.vue` 文件 |
| `resolve.alias` | 设置 `@` 指向 `src/renderer/src`，简化导入路径 |
| `build.rollupOptions.input` | 指定每个进程的入口文件 |

### 构建后输出

```
electron-vite build
       │
       ▼
┌──────────────────────────────────────────┐
│  out/main/index.js      (主进程)          │
│  out/preload/index.mjs  (预加载)         │
│  out/renderer/index.html (渲染进程)       │
│  out/renderer/assets/*   (JS/CSS)        │
└──────────────────────────────────────────┘
```