get_wechat/桌面应用打包简版指南.md

桌面应用打包简版指南

一句话总结

技术栈：React 前端 + Python FastAPI 后端 + Electron 外壳 + electron-builder 安装包

用户双击桌面图标 → Electron 启动 → 自动拉起后端 → 窗口加载后端页面。

---

打包前准备

1. 安装依赖

# 前端依赖
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 可用

---

一键打包

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 -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

---

签名打包（正式发布）

$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
客户电脑提示风险	安装包未签名	使用代码签名证书