270 lines
5.5 KiB
Markdown
270 lines
5.5 KiB
Markdown
# 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/)
|