init vue
This commit is contained in:
@@ -0,0 +1,332 @@
|
|||||||
|
# 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) │
|
||||||
|
└──────────────────────────────────────────┘
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user