tianshu-engine/docs/QUICK_REFERENCE.md

Electron 打包快速参考

🚀 快速开始

# 1. 安装依赖
npm install
cd electron && npm install express

# 2. 开发
npm run dev

# 3. 构建
npm run build

# 4. 打包
npm run pack:win    # Windows
npm run pack:mac    # Mac

📦 核心特性

特性	说明
✅ 零源码修改	项目代码无需改动
✅ 自动端口查找	9527-9999 自动切换
✅ 本地服务器	Express 提供静态文件
✅ 跨平台兼容	浏览器和 Electron 都能用

🔧 配置文件

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,
    contextIsolation: true
  }
})

📁 目录结构

dist/              # 构建输出
electron/
  ├── main.js      # 主进程
  ├── server.js    # 本地服务器
  └── package.json # Electron 依赖
release/           # 打包输出

🎯 工作流程

开发: Vite (localhost:5173) → 浏览器 ✅
打包: Express (localhost:9527) → Electron ✅

🐛 常见问题

问题	解决方案
白屏	检查 dist 是否复制到 electron
端口冲突	系统自动处理，无需干预
资源加载失败	使用绝对路径 /scenes/...
开发者工具	删除 openDevTools() 关闭

📊 端口查找

9527 → 可用 ✅
9528 → 被占用，跳过
9529 → 可用 ✅
...

🔒 安全建议

webPreferences: {
  nodeIntegration: false,   // ✅ 禁用 Node
  contextIsolation: true    // ✅ 隔离上下文
}

📝 注意事项

1. 只监听 127.0.0.1，不暴露到外网
2. 应用退出时自动关闭服务器
3. 端口范围耗尽会抛出错误

📚 相关文档

• 完整指南
• 端口查找