# Electron 打包完整指南

## 概述

本指南介绍如何将 Vue/HTML 项目打包成 Electron 应用，采用**本地服务器方案**，无需修改源码。

## 核心优势

✅ **零源码修改** - 项目代码完全不需要改动
✅ **自动端口查找** - 自动处理端口冲突（9527-9999）
✅ **跨平台兼容** - 浏览器和 Electron 都能正常工作
✅ **易于维护** - 打包逻辑集中在 Electron 目录
✅ **性能优秀** - 本地服务器响应快速

## 项目结构

```
branch-engine/
├── dist/                    # 构建输出目录
├── electron/                # Electron 相关文件
│   ├── main.js             # 主进程入口
│   ├── server.js           # 本地服务器
│   └── package.json        # Electron 依赖
├── scripts/
│   ├── prepare-electron.cjs # 打包前准备
│   └── pack-html.cjs       # HTML 打包
├── src/                    # Vue 源码
├── editor/                 # 编辑器
└── package.json            # 主项目配置
```

## 工作原理

### 开发环境
```
npm run dev
↓
Vite 开发服务器 (localhost:5173)
↓
浏览器访问 → 正常工作 ✅
```

### 打包环境
```
npm run pack:win
↓
1. npm run build (生成 dist)
2. 复制 dist 到 electron
3. 启动 Express 服务器 (localhost:9527-9999)
4. Electron 加载 http://127.0.0.1:PORT ✅
```

## 详细步骤

### 1. 安装依赖

```bash
# 主项目依赖
npm install

# Electron 依赖
cd electron
npm install express
```

### 2. 开发

```bash
# 启动开发服务器
npm run dev
```

### 3. 构建

```bash
# 构建 Vue 项目
npm run build
```

### 4. 打包

```bash
# 打包 Windows 版本
npm run pack:win

# 打包 Mac 版本
npm run pack:mac
```

### 5. 运行

打包完成后，在 `release/` 目录下找到生成的应用：
- Windows: `release/MyGame-win32-x64/MyGame.exe`
- Mac: `release/MyGame-mas-x64/MyGame.app`

## 核心文件说明

### electron/main.js

主进程入口，负责：
- 启动本地服务器
- 创建浏览器窗口
- 加载应用
- 处理应用生命周期

### electron/server.js

本地服务器，负责：
- 自动查找可用端口（9527-9999）
- 提供静态文件服务
- 处理资源请求

### scripts/prepare-electron.cjs

打包前准备脚本，负责：
- 将 dist 目录复制到 electron
- 验证构建文件

## 端口自动查找

### 功能特性
- 起始端口：9527
- 最大端口：9999
- 自动检测：逐个检测端口可用性
- 冲突处理：自动跳过被占用的端口

### 使用示例

#### 正常情况
```
✅ Local server running at http://127.0.0.1:9527
🚀 Loading app from: http://127.0.0.1:9527/index.html
```

#### 端口冲突
```
🔒 Port 9527 is blocked
✅ Local server running at http://127.0.0.1:9528
🚀 Loading app from: http://127.0.0.1:9528/index.html
```

## 配置选项

### 修改端口范围

编辑 `electron/server.js`:

```javascript
const START_PORT = 9527  // 起始端口
const MAX_PORT = 9999    // 最大端口
```

### 修改窗口配置

编辑 `electron/main.js`:

```javascript
const win = new BrowserWindow({
  fullscreen: true,           // 全屏模式
  autoHideMenuBar: true,      // 隐藏菜单栏
  webPreferences: {
    nodeIntegration: false,   // 禁用 node 集成
    contextIsolation: true    // 启用上下文隔离
  }
})
```

## 常见问题

### Q1: 打包后白屏
**A:** 检查 dist 目录是否正确复制到 electron 目录。

### Q2: 端口被占用
**A:** 系统会自动查找下一个可用端口，无需手动处理。

### Q3: 资源加载失败
**A:** 确保使用绝对路径（如 `/scenes/config.json`），本地服务器会正确处理。

### Q4: 开发者工具如何关闭
**A:** 删除 `electron/main.js` 中的 `win.webContents.openDevTools()` 行。

### Q5: 如何添加应用图标
**A:** 在打包配置中添加图标文件路径。

## 性能优化

### 1. 减小包体积
```bash
# 使用 electron-builder 替代 electron-packager
npm install --save-dev electron-builder
```

### 2. 启用代码压缩
在 `vite.config.ts` 中配置：
```typescript
build: {
  minify: 'terser',
  terserOptions: {
    compress: {
      drop_console: true
    }
  }
}
```

### 3. 优化资源加载
- 使用 CDN 加载第三方库
- 启用 gzip 压缩
- 懒加载非关键资源

## 安全建议

1. **禁用 Node 集成**
   ```javascript
   webPreferences: {
     nodeIntegration: false,
     contextIsolation: true
   }
   ```

2. **只监听本地地址**
   ```javascript
   server.listen(PORT, '127.0.0.1')
   ```

3. **验证用户输入**
   - 检查 URL 参数
   - 验证文件路径
   - 防止 XSS 攻击

## 调试技巧

### 查看服务器日志
```javascript
console.log('Server started on port:', PORT)
```

### 查看网络请求
打开开发者工具 → Network 标签，查看所有请求。

### 查看控制台错误
打开开发者工具 → Console 标签，查看错误信息。

## 部署建议

### 1. 代码签名
```bash
# Windows
electron-builder --win --x64 --publish never

# Mac
electron-builder --mac --x64 --publish never
```

### 2. 自动更新
使用 `electron-updater` 实现自动更新功能。

### 3. 安装包配置
在 `electron-builder.yml` 中配置安装选项。

## 总结

本方案采用**本地服务器 + 自动端口查找**的方式，完美解决了 Electron 打包中的路径问题，同时保持了源码的纯净性。这是一个简单、优雅、可维护的解决方案。

## 相关文档

- [Electron 官方文档](https://www.electronjs.org/docs)
- [Express 文档](https://expressjs.com/)
- [Vite 文档](https://vitejs.dev/)