dtm-py-all/打包说明.md

DTM 工业测试管理系统 - PyInstaller 打包说明

📦 打包环境要求

• Python 版本: Python 3.7+
• Conda 环境: dtmgt
• 打包工具: PyInstaller

🚀 打包步骤

1. 激活 Conda 环境

conda activate dtmgt

2. 清理之前的打包文件（推荐）

Remove-Item -Recurse -Force build, dist -ErrorAction SilentlyContinue

3. 执行打包命令

正式版本（无控制台窗口）

# 在项目根目录执行
pyinstaller --clean dtmgtApp.spec

生成文件：dist\dtmgtApp.exe

• ✅ 无CMD控制台窗口
• ✅ 日志自动保存到 logs\ 目录
• ✅ 适合生产环境使用

调试版本（带控制台窗口）

# 在项目根目录执行
pyinstaller --clean dtmgtApp-debug.spec

生成文件：dist\dtmgtApp-debug.exe

• ✅ 显示CMD控制台窗口
• ✅ 实时查看日志输出
• ✅ 适合开发调试使用

4. 查看打包结果

打包成功后，可执行文件位于：

• 正式版：dist\dtmgtApp.exe
• 调试版：dist\dtmgtApp-debug.exe

📋 控制台窗口控制

方式一：使用不同的spec文件

Spec 文件	Console	用途	日志输出
dtmgtApp.spec	False	生产环境	logs/dtmgt_*.log
dtmgtApp-debug.spec	True	调试开发	控制台实时显示

方式二：使用命令行参数（正式版）

即使使用 dtmgtApp.exe（无控制台），也可以通过命令行参数控制行为：

# 查看所有可用参数
.\dtmgtApp.exe --help

# 常用参数示例
.\dtmgtApp.exe --mock              # 启用PLC模拟模式
.\dtmgtApp.exe --no-ui             # 不启动UI（仅后台服务）
.\dtmgtApp.exe --port 8080         # 指定HTTP服务端口

日志文件位置

正式版（无控制台）运行时，日志自动保存到：

<exe所在目录>\logs\dtmgt_YYYYMMDD_HHMMSS.log

例如：

E:\WORK\DTM-PY-ALL\dist\logs\dtmgt_20251209_143052.log

🔧 Spec 文件配置说明

关键配置项

1. SSL DLL 依赖（已解决）

# 自动收集 Conda 环境中的 SSL DLL
conda_dll_dir = os.path.join(conda_prefix, 'Library', 'bin')
# 包含: libcrypto-1_1-x64.dll, libssl-1_1-x64.dll

2. UI 模块包含

# 包含整个 UI 目录及所有子模块
('UI', 'UI'),
# 自动收集所有子模块
ui_hiddenimports = collect_submodules('UI')

3. 资源文件包含

datas=[
    ('web', 'web'),      # Web 资源
    ('UI', 'UI'),        # UI 模块
    ('db', 'db'),        # 数据库文件
]

4. 排除不需要的模块

excludes=[
    'serial.tools.list_ports_osx',  # macOS 串口工具
    'PyQt5.QtDBus',                 # DBus 支持
]
# 过滤不需要的 SQL 驱动（保留 SQLite）
a.binaries = [x for x in a.binaries if not (
    'qsqlpsql' in x[0] or   # PostgreSQL
    'qsqlmysql' in x[0] or  # MySQL
    'qsqlodbc' in x[0]      # ODBC
)]

⚠️ 常见警告说明

1. Hidden import "sip" not found

• 影响: 无影响
• 原因: PyQt5 旧版本遗留，新版本使用 PyQt5.sip
• 处理: 可忽略

2. Ignoring macOS frameworks

• 影响: 无影响
• 原因: pyserial 跨平台代码，Windows 上不会使用
• 处理: 已在 excludes 中排除

3. Library not found: LIBPQ.dll

• 影响: 无影响（不使用 PostgreSQL）
• 原因: PyQt5 PostgreSQL 驱动缺少依赖
• 处理: 已过滤掉 PostgreSQL 驱动

4. cannot import name 'ttk' from 'tkinter'

• 影响: 启动提示窗口无法显示，程序崩溃
• 原因: PyInstaller 未自动包含 tkinter.ttk 模块
• 处理: 已在 spec 文件的 hiddenimports 中添加 'tkinter.ttk' 和 '_tkinter'

✅ 验证打包结果

1. 检查文件大小

正常的打包文件应该在 100-300 MB 之间（包含所有依赖）

2. 测试运行

cd dist

# 正式版（无控制台）
.\dtmgtApp.exe

# 调试版（带控制台）
.\dtmgtApp-debug.exe

# 使用PLC模拟模式运行
.\dtmgtApp.exe --mock

3. 检查必要的 DLL

打包后的可执行文件应该包含：

• libcrypto-1_1-x64.dll
• libssl-1_1-x64.dll
• _ssl.pyd
• _hashlib.pyd

4. 检查 tkinter 模块

使用调试版运行，确认启动提示窗口正常显示：

.\dtmgtApp-debug.exe
# 应该能看到蓝色边框的“系统启动中”提示窗口

🔧 故障排查

问题 1: SSL DLL 缺失错误

ImportError: DLL load failed while importing _ssl

解决方案: 确保在 Conda 环境中打包，spec 文件会自动收集 SSL DLL

问题 2: 找不到 UI 模块

ModuleNotFoundError: No module named 'UI.views'

解决方案: 确保 spec 文件中包含了 ('UI', 'UI') 并使用了 collect_submodules('UI')

问题 3: 找不到数据库文件

sqlite3.OperationalError: unable to open database file

解决方案: 检查代码中的数据库路径，使用相对路径或 sys._MEIPASS

📝 打包优化建议

1. 减小文件体积

• 排除不需要的模块（已配置）
• 使用 --exclude-module 排除大型库

2. 提高启动速度

• 考虑使用 --onedir 模式（而非 --onefile）
• 减少不必要的 hiddenimports

3. 调试打包问题

# 启用调试模式
pyinstaller --clean --debug all dtmgtApp.spec

📞 联系支持

如果遇到打包问题，请提供：

1. 完整的错误信息
2. 打包日志文件 build\dtmgtApp\warn-dtmgtApp.txt
3. Python 和依赖包版本信息