TorqueWrench/frontend/打包说明.md

wrench_gui.py 打包说明

一、环境准备

1. 安装 Python 依赖

确保已安装所有必需的 Python 包：

# 进入 frontend 目录
cd frontend

# 安装依赖
pip install -r requirements.txt

# 安装 PyInstaller（如果未安装）
pip install pyinstaller

2. 检查文件结构

确保以下文件存在：

TorqueWrench/
├── frontend/
│   ├── wrench_gui.py          # 主程序
│   ├── device_manager.py      # 设备管理模块
│   ├── wrench_gui.spec        # PyInstaller 配置文件
│   ├── build_exe.bat          # Windows 打包脚本
│   └── build_exe.sh           # Linux/Mac 打包脚本
├── wrench_controller.py       # 扳手控制模块（父目录）
└── config.json                # 配置文件（父目录）

---

二、打包步骤

Windows 系统

1. 打开命令提示符或 PowerShell

2. 进入 frontend 目录

   cd F:\PyPro\TorqueWrench\frontend
   

3. 执行打包脚本

   build_exe.bat
   

   或者手动执行：

   pyinstaller wrench_gui.spec
   

Linux/Mac 系统

1. 打开终端

2. 进入 frontend 目录

   cd /path/to/TorqueWrench/frontend
   

3. 给脚本添加执行权限

   chmod +x build_exe.sh
   

4. 执行打包脚本

   ./build_exe.sh
   

   或者手动执行：

   pyinstaller wrench_gui.spec
   

---

三、打包输出

打包完成后，会在 frontend/dist/ 目录下生成可执行文件：

Windows

• 位置: frontend/dist/wrench_gui/wrench_gui.exe
• 大小: 约 15-30 MB（取决于依赖）

Linux/Mac

• 位置: frontend/dist/wrench_gui/wrench_gui
• 大小: 约 15-30 MB

---

四、运行打包后的程序

1. 准备配置文件

将 config.json 复制到可执行文件所在目录：

Windows:

copy ..\config.json dist\wrench_gui\config.json

Linux/Mac:

cp ../config.json dist/wrench_gui/config.json

2. 启动后端服务

确保后端 API 服务已启动：

# 进入 backend 目录
cd ../backend

# 启动后端（Windows）
start_backend.bat

# 或启动后端（Linux/Mac）
./start_backend.sh

3. 运行可执行文件

Windows:

• 双击 dist/wrench_gui/wrench_gui.exe
• 或在命令行执行：

  dist\wrench_gui\wrench_gui.exe
  

Linux/Mac:

./dist/wrench_gui/wrench_gui

---

五、常见问题

1. 打包失败：找不到模块

问题: ModuleNotFoundError: No module named 'xxx'

解决:

• 检查是否已安装所有依赖：pip install -r requirements.txt
• 检查 wrench_gui.spec 中的 hiddenimports 是否包含缺失的模块

2. 运行时报错：找不到 config.json

问题: 程序启动时报错找不到配置文件

解决:

• 确保 config.json 在可执行文件同一目录下
• 检查 wrench_gui.spec 中的 datas 配置是否正确

3. 打包后的程序很大（>50MB）

原因: PyInstaller 会打包所有依赖库

优化:

• 使用虚拟环境，只安装必需的包
• 在 wrench_gui.spec 的 excludes 中添加不需要的模块

4. 控制台窗口也显示（Windows）

问题: 打包后的程序同时显示 GUI 和控制台窗口

解决:

• 检查 wrench_gui.spec 中 console=False 是否设置正确

5. 图标设置

如果需要自定义程序图标：

1. 准备图标文件（.ico 格式，Windows）
2. 修改 wrench_gui.spec：

   icon='icon.ico',  # 图标文件路径
   

3. 重新打包

---

六、打包选项说明

wrench_gui.spec 关键配置

• console=False: 不显示控制台窗口（GUI应用）
• upx=True: 使用 UPX 压缩（减小文件大小）
• datas: 包含的数据文件（如配置文件）
• hiddenimports: 需要显式导入的隐藏模块

单文件打包（可选）

如果需要打包成单个 .exe 文件，修改 wrench_gui.spec：

exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,  # 改为 True
    name='wrench_gui',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=False,
)

然后添加 COLLECT 部分（PyInstaller 会自动处理）。

---

七、分发打包后的程序

1. 最小分发包

需要包含的文件：

wrench_gui/
├── wrench_gui.exe          # 可执行文件
├── config.json              # 配置文件
└── README.txt               # 使用说明（可选）

2. 完整分发包（推荐）

wrench_gui/
├── wrench_gui.exe
├── config.json
├── README.txt
└── 使用说明.pdf            # 用户手册

3. 注意事项

• 确保目标机器已安装必要的运行时库（如 Visual C++ Redistributable，Windows）
• 如果使用了 UPX 压缩，某些杀毒软件可能会误报，建议关闭 UPX 或添加白名单

---

八、快速打包命令（一键打包）

Windows

cd frontend && build_exe.bat

Linux/Mac

cd frontend && chmod +x build_exe.sh && ./build_exe.sh

---

九、验证打包结果

打包完成后，建议测试：

1. 运行可执行文件

   • 检查是否能正常启动
   • 检查是否能连接到后端 API
   • 检查设备管理功能是否正常

2. 检查文件大小

   • 正常大小：15-30 MB
   • 如果过大（>50MB），检查依赖

3. 测试功能

   • 工单列表加载
   • 设备选择
   • 拧紧操作
   • 数据提交

---

十、技术支持

如果遇到打包问题：

1. 查看 PyInstaller 官方文档：https://pyinstaller.org/
2. 检查错误日志：build/wrench_gui/warn-wrench_gui.txt
3. 使用调试模式：在 wrench_gui.spec 中设置 debug=True