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

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

## 📦 打包环境要求

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

## 🚀 打包步骤

### 1. 激活 Conda 环境
```powershell
conda activate dtmgt
```

### 2. 清理之前的打包文件（推荐）
```powershell
Remove-Item -Recurse -Force build, dist -ErrorAction SilentlyContinue
```

### 3. 执行打包命令

#### **正式版本（无控制台窗口）**
```powershell
# 在项目根目录执行
pyinstaller --clean dtmgtApp.spec
```
生成文件：`dist\dtmgtApp.exe`
- ✅ 无CMD控制台窗口
- ✅ 日志自动保存到 `logs\` 目录
- ✅ 适合生产环境使用

#### **调试版本（带控制台窗口）**
```powershell
# 在项目根目录执行
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`（无控制台），也可以通过命令行参数控制行为：

```powershell
# 查看所有可用参数
.\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 依赖**（已解决）
```python
# 自动收集 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 模块包含**
```python
# 包含整个 UI 目录及所有子模块
('UI', 'UI'),
# 自动收集所有子模块
ui_hiddenimports = collect_submodules('UI')
```

#### 3. **资源文件包含**
```python
datas=[
    ('web', 'web'),      # Web 资源
    ('UI', 'UI'),        # UI 模块
    ('db', 'db'),        # 数据库文件
]
```

#### 4. **排除不需要的模块**
```python
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. 测试运行
```powershell
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 模块
使用调试版运行，确认启动提示窗口正常显示：
```powershell
.\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. 调试打包问题
```powershell
# 启用调试模式
pyinstaller --clean --debug all dtmgtApp.spec
```

## 📞 联系支持

如果遇到打包问题，请提供：
1. 完整的错误信息
2. 打包日志文件 `build\dtmgtApp\warn-dtmgtApp.txt`
3. Python 和依赖包版本信息