154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
# 桌面应用打包简版指南
|
||
|
||
## 一句话总结
|
||
|
||
技术栈：`React 前端 + Python FastAPI 后端 + Electron 外壳 + electron-builder 安装包`
|
||
|
||
用户双击桌面图标 → Electron 启动 → 自动拉起后端 → 窗口加载后端页面。
|
||
|
||
---
|
||
|
||
## 打包前准备
|
||
|
||
### 1. 安装依赖
|
||
|
||
```powershell
|
||
# 前端依赖
|
||
cd chatlab-web/frontend
|
||
npm install
|
||
|
||
# Electron 依赖
|
||
cd ../../electron-launcher
|
||
npm install
|
||
|
||
# Python 依赖
|
||
cd ../chatlog_fastAPI
|
||
py -3.12 -m pip install -r requirements.txt
|
||
py -3.12 -m pip install pyinstaller
|
||
```
|
||
|
||
### 2. 确认文件齐全
|
||
|
||
- `chatlog.exe` 存在于项目根目录
|
||
- `lib/windows_x64/wx_key.dll` 存在
|
||
- Node.js、Python 3.12 可用
|
||
|
||
---
|
||
|
||
## 一键打包
|
||
|
||
```powershell
|
||
cd 项目根目录
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
|
||
```
|
||
|
||
这个脚本会依次完成：
|
||
1. 生成应用图标
|
||
2. 构建 React 前端（`npm run build`）
|
||
3. 用 PyInstaller 打包 Python 后端
|
||
4. 复制所有资源到 `electron-launcher/build-resources/`
|
||
5. 扫描敏感文件（.env、证书、数据库等自动排除）
|
||
6. 调用 electron-builder 生成 NSIS 安装包
|
||
7. 输出到 `release/` 目录
|
||
|
||
最终产物：`release/ChatLab-Setup-版本号.exe`
|
||
|
||
---
|
||
|
||
## 调试时跳过某些步骤
|
||
|
||
```powershell
|
||
# 只改前端，跳过后端打包
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipBackend
|
||
|
||
# 只改后端，跳过前端构建
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipFrontend
|
||
|
||
# 只准备资源，不生成安装包
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1 -SkipInstaller
|
||
```
|
||
|
||
---
|
||
|
||
## 打包流程原理
|
||
|
||
```
|
||
scripts/build-desktop.ps1（总控脚本）
|
||
│
|
||
├── Vite 构建前端 → chatlab-web/frontend/dist/
|
||
│
|
||
├── PyInstaller 打包后端 → chatlog_fastAPI/dist/ChatLabBackend/
|
||
│
|
||
├── 复制所有资源到 build-resources/
|
||
│ ├── frontend/（前端静态文件）
|
||
│ ├── backend/（Python 后端 exe + _internal/）
|
||
│ ├── chatlog.exe（微信数据服务）
|
||
│ └── lib/windows_x64/wx_key.dll
|
||
│
|
||
└── electron-builder 打包 → release/安装包
|
||
```
|
||
|
||
**核心原则：**
|
||
- 运行期必须作为真实文件存在的内容（exe、DLL、前端 dist）走 `extraResources`，不进 asar
|
||
- 用户数据写 `%APPDATA%/ChatLab`，不写安装目录
|
||
- Electron 主进程只负责窗口和进程管理，不承载业务逻辑
|
||
|
||
---
|
||
|
||
## 安装后的目录结构
|
||
|
||
```
|
||
安装目录/
|
||
ChatLab售后智能助手.exe
|
||
resources/
|
||
app.asar ← Electron 主程序
|
||
backend/
|
||
ChatLabBackend.exe ← Python 后端
|
||
_internal/
|
||
frontend/
|
||
index.html ← React 页面
|
||
assets/
|
||
chatlog.exe ← 微信数据服务
|
||
lib/windows_x64/
|
||
wx_key.dll
|
||
```
|
||
|
||
---
|
||
|
||
## 签名打包（正式发布）
|
||
|
||
```powershell
|
||
$env:CHATLAB_PFX_FILE = "D:\certs\ChatLab-CodeSigning.pfx"
|
||
$env:CHATLAB_PFX_PASSWORD = "证书密码"
|
||
$env:CHATLAB_FORCE_SIGN = "1"
|
||
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\build-desktop.ps1
|
||
```
|
||
|
||
注意事项：
|
||
- 证书不要放项目目录
|
||
- 密码不要写进代码仓库
|
||
- 签名可显著降低 SmartScreen 拦截概率
|
||
|
||
---
|
||
|
||
## 打包后验证
|
||
|
||
1. 检查 `release/` 下安装包是否生成
|
||
2. 在干净 Windows 机器上安装测试
|
||
3. 确认双击启动 → 后端启动 → 页面正常加载
|
||
4. 确认关闭后无残留进程
|
||
5. 确认用户数据在 `%APPDATA%/ChatLab`
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
| 问题 | 原因 | 解决 |
|
||
|---|---|---|
|
||
| 前端空白 | 前端 dist 没复制到 build-resources | 检查 `build-resources/frontend/index.html` 是否存在 |
|
||
| 后端启动失败 | PyInstaller 缺少 hidden imports | 检查 `.spec` 文件，补充缺失模块 |
|
||
| 找不到 exe/DLL | 资源没复制或被打进 asar | 外部 exe/DLL 必须走 `extraResources` |
|
||
| 关闭后残留进程 | 只杀了父进程没杀子进程树 | 使用 `taskkill /pid /f /t` |
|
||
| 客户电脑提示风险 | 安装包未签名 | 使用代码签名证书 |
|