wangjunxiao/tianshu-engine

Fork 0

Files

cocos02 686b1b45ea docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README

2026-06-10 17:01:55 +08:00

5.5 KiB

Raw Blame History

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. 安装依赖

# 主项目依赖
npm install

# Electron 依赖
cd electron
npm install express

2. 开发

# 启动开发服务器
npm run dev

3. 构建

# 构建 Vue 项目
npm run build

4. 打包

# 打包 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:

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

修改窗口配置

编辑 electron/main.js:

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. 减小包体积

# 使用 electron-builder 替代 electron-packager
npm install --save-dev electron-builder

2. 启用代码压缩

在 vite.config.ts 中配置：

build: {
  minify: 'terser',
  terserOptions: {
    compress: {
      drop_console: true
    }
  }
}

3. 优化资源加载

使用 CDN 加载第三方库
启用 gzip 压缩
懒加载非关键资源

安全建议

禁用 Node 集成

webPreferences: {
  nodeIntegration: false,
  contextIsolation: true
}

只监听本地地址
```
server.listen(PORT, '127.0.0.1')
```
验证用户输入
- 检查 URL 参数
- 验证文件路径
- 防止 XSS 攻击

调试技巧

查看服务器日志

console.log('Server started on port:', PORT)

查看网络请求

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

查看控制台错误

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

部署建议

1. 代码签名

# Windows
electron-builder --win --x64 --publish never

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

2. 自动更新

使用 electron-updater 实现自动更新功能。

3. 安装包配置

在 electron-builder.yml 中配置安装选项。

总结

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

5.5 KiB Raw Blame History Unescape Escape