264 lines
6.0 KiB
Markdown
264 lines
6.0 KiB
Markdown
# 打包发布设计
|
||
|
||
## 1. 文档定位
|
||
|
||
本文档定义第一阶段的本地打包和发布规则。当前阶段只考虑将软件打包为可在 Windows 电脑上运行的桌面程序。
|
||
|
||
暂不包含：
|
||
|
||
- 局域网分发。
|
||
- 自动更新。
|
||
- 多版本启动器。
|
||
- 强制升级策略。
|
||
- 远程版本策略管理。
|
||
|
||
这些能力后续需要时再单独补充设计文档。
|
||
|
||
## 2. 打包目标
|
||
|
||
- 将 PySide6 桌面程序打包为 Windows 可运行程序。
|
||
- 目标电脑无需预装 Python 环境。
|
||
- 打包产物应包含运行所需依赖、资源文件、默认配置和模板。
|
||
- 打包后的程序应能在 Windows 10 / Windows 11 上启动。
|
||
- 打包结构应方便排查 Qt 插件、资源、配置和日志问题。
|
||
|
||
## 3. 推荐打包方式
|
||
|
||
使用 PyInstaller。
|
||
|
||
第一阶段推荐使用 `onedir` 模式：
|
||
|
||
```bash
|
||
pyinstaller --onedir --windowed src/main.py
|
||
```
|
||
|
||
原因：
|
||
|
||
- PySide6 / Qt 依赖文件较多，`onedir` 更容易排查问题。
|
||
- 启动速度通常优于 `onefile`。
|
||
- 资源文件、配置文件、模板文件更容易随程序目录管理。
|
||
- 后续如需局域网分发或增量替换，目录模式更合适。
|
||
|
||
不推荐第一阶段使用 `onefile`：
|
||
|
||
- 启动时需要解压临时文件。
|
||
- Qt 插件问题更难排查。
|
||
- 日志、模板和配置路径更容易混乱。
|
||
|
||
## 4. Python 与依赖要求
|
||
|
||
必须遵守：
|
||
|
||
- Python 版本：Python 3.7。
|
||
- GUI 框架：PySide6。
|
||
- 推荐 PySide6 版本：`PySide6==6.5.3`。
|
||
- 图片处理：Pillow。
|
||
- 打包工具：PyInstaller。
|
||
|
||
依赖版本应在项目根目录的 `requirements.txt` 中锁定。
|
||
|
||
打包前必须确认依赖可以在 Python 3.7 环境中安装。
|
||
|
||
## 5. 发布目录结构
|
||
|
||
推荐打包后的发布目录：
|
||
|
||
```text
|
||
CMBot/
|
||
CMBot.exe
|
||
_internal/
|
||
config/
|
||
app_config.json
|
||
templates.json
|
||
resources/
|
||
icons/
|
||
styles/
|
||
logs/
|
||
output/
|
||
README.txt
|
||
```
|
||
|
||
说明：
|
||
|
||
- `CMBot.exe`：主程序入口。
|
||
- `_internal/`：PyInstaller 依赖目录。
|
||
- `config/`：默认配置和模板配置。
|
||
- `resources/`：图标、样式等资源。
|
||
- `logs/`：运行日志目录，程序启动时可自动创建。
|
||
- `output/`：默认输出目录，可自动创建。
|
||
- `README.txt`：给用户的简短使用说明。
|
||
|
||
## 6. 可写目录规则
|
||
|
||
程序运行时可能写入：
|
||
|
||
- 日志文件。
|
||
- 用户配置。
|
||
- 自定义模板。
|
||
- 导出图片。
|
||
|
||
规则：
|
||
|
||
- 程序必须确保 `logs/` 目录存在。
|
||
- 程序必须确保默认 `output/` 目录存在。
|
||
- 配置和模板写入前必须确认目录可写。
|
||
- 如果安装目录不可写，应提示用户选择可写目录，或后续改用用户数据目录。
|
||
|
||
第一阶段可以默认将配置、模板、日志和输出放在程序目录下，但必须处理目录不可写的错误。
|
||
|
||
## 7. 资源文件打包
|
||
|
||
需要随程序打包的资源：
|
||
|
||
- 应用图标。
|
||
- UI 样式文件。
|
||
- 默认模板文件。
|
||
- 默认配置文件。
|
||
- AI 穿搭出厂配置：`ai_models.json`（不含真实 key）、`outfit_prompt.txt`、`title_prompt.txt`。这些文件应进入发布包的 `app\config\`，用于首次播种和运行时兜底补种；用户目录已有同名文件时不得覆盖。
|
||
|
||
规则：
|
||
|
||
- 资源文件路径不能写死为开发机绝对路径。
|
||
- 程序需要通过统一的资源路径函数获取资源。
|
||
- 打包环境和开发环境应使用同一套路径访问规则。
|
||
|
||
建议提供路径辅助函数：
|
||
|
||
```text
|
||
get_app_dir()
|
||
get_resource_path(relative_path)
|
||
get_config_path(relative_path)
|
||
get_log_dir()
|
||
get_output_dir()
|
||
```
|
||
|
||
## 8. PyInstaller 配置
|
||
|
||
第一阶段可以先使用命令行打包；项目稳定后应维护 `.spec` 文件。
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
pyinstaller ^
|
||
--onedir ^
|
||
--windowed ^
|
||
--name CMBot ^
|
||
--add-data "resources;resources" ^
|
||
--add-data "config;config" ^
|
||
src/main.py
|
||
```
|
||
|
||
注意：
|
||
|
||
- Windows 下 `--add-data` 的源路径和目标路径使用分号 `;` 分隔。
|
||
- 如果在 PowerShell 中执行，换行符和引号需要按实际环境调整。
|
||
- 打包命令应后续固化到脚本中，例如 `scripts/build.ps1`。
|
||
|
||
## 9. 版本号规则
|
||
|
||
软件需要有明确版本号。
|
||
|
||
规则：
|
||
|
||
- 当前版本号必须显示在标题栏软件名称右侧。
|
||
- 版本号应从统一位置读取，不应在多个 UI 文件中硬编码。
|
||
- 打包产物的版本号、窗口显示版本号和发布目录版本号应一致。
|
||
|
||
建议维护：
|
||
|
||
```text
|
||
src/version.py
|
||
```
|
||
|
||
示例：
|
||
|
||
```python
|
||
APP_NAME = "自动合成印花服饰效果图工具"
|
||
APP_VERSION = "1.0.0"
|
||
```
|
||
|
||
发布目录建议带版本号：
|
||
|
||
```text
|
||
CMBot-1.0.0/
|
||
```
|
||
|
||
## 10. 打包前检查
|
||
|
||
打包前必须检查：
|
||
|
||
- Python 版本是否为 3.7。
|
||
- 依赖是否安装成功。
|
||
- 程序是否可以在开发环境启动。
|
||
- 默认配置文件是否存在。
|
||
- 默认模板文件是否存在。
|
||
- 资源文件路径是否正确。
|
||
- 应用版本号是否正确。
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
python --version
|
||
pip freeze
|
||
python src/main.py
|
||
```
|
||
|
||
## 11. 打包后验证
|
||
|
||
打包后必须验证：
|
||
|
||
- 双击 `CMBot.exe` 可以启动。
|
||
- 标题栏显示正确版本号。
|
||
- 可以打开衣服图片文件夹。
|
||
- 可以打开印花图片文件夹。
|
||
- 可以显示预览区。
|
||
- 可以拖动、缩放、旋转印花。
|
||
- 可以导出当前单张图片。
|
||
- 可以生成日志文件。
|
||
- 程序关闭后再次启动正常。
|
||
|
||
若测试机器没有 Python 环境，应优先在该机器上验证。
|
||
|
||
## 12. 发布产物
|
||
|
||
第一阶段发布产物建议为压缩包：
|
||
|
||
```text
|
||
CMBot-1.0.0.zip
|
||
```
|
||
|
||
压缩包内包含：
|
||
|
||
```text
|
||
CMBot-1.0.0/
|
||
CMBot.exe
|
||
_internal/
|
||
config/
|
||
resources/
|
||
README.txt
|
||
```
|
||
|
||
不应包含：
|
||
|
||
- 源代码。
|
||
- 测试文件。
|
||
- 开发环境缓存。
|
||
- 临时输出图片。
|
||
- 本机私人配置。
|
||
- 打包中间目录。
|
||
|
||
## 13. 暂不做
|
||
|
||
第一阶段不做：
|
||
|
||
- 局域网共享目录发布。
|
||
- 自动检查新版本。
|
||
- 自动下载更新。
|
||
- 多版本共存启动器。
|
||
- 按电脑名控制版本。
|
||
- 安装程序。
|
||
- Windows 注册表写入。
|
||
- 开机自启动。
|
||
|
||
如果后续要增加这些能力，应新增或扩展发布分发文档，不能直接混入当前第一阶段打包规则。
|