6.0 KiB
6.0 KiB
打包发布设计
1. 文档定位
本文档定义第一阶段的本地打包和发布规则。当前阶段只考虑将软件打包为可在 Windows 电脑上运行的桌面程序。
暂不包含：
- 局域网分发。
- 自动更新。
- 多版本启动器。
- 强制升级策略。
- 远程版本策略管理。
这些能力后续需要时再单独补充设计文档。
2. 打包目标
- 将 PySide6 桌面程序打包为 Windows 可运行程序。
- 目标电脑无需预装 Python 环境。
- 打包产物应包含运行所需依赖、资源文件、默认配置和模板。
- 打包后的程序应能在 Windows 10 / Windows 11 上启动。
- 打包结构应方便排查 Qt 插件、资源、配置和日志问题。
3. 推荐打包方式
使用 PyInstaller。
第一阶段推荐使用 onedir 模式：
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. 发布目录结构
推荐打包后的发布目录：
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\，用于首次播种和运行时兜底补种；用户目录已有同名文件时不得覆盖。
规则：
- 资源文件路径不能写死为开发机绝对路径。
- 程序需要通过统一的资源路径函数获取资源。
- 打包环境和开发环境应使用同一套路径访问规则。
建议提供路径辅助函数：
get_app_dir()
get_resource_path(relative_path)
get_config_path(relative_path)
get_log_dir()
get_output_dir()
8. PyInstaller 配置
第一阶段可以先使用命令行打包；项目稳定后应维护 .spec 文件。
建议命令：
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 文件中硬编码。
- 打包产物的版本号、窗口显示版本号和发布目录版本号应一致。
建议维护：
src/version.py
示例：
APP_NAME = "自动合成印花服饰效果图工具"
APP_VERSION = "1.0.0"
发布目录建议带版本号：
CMBot-1.0.0/
10. 打包前检查
打包前必须检查：
- Python 版本是否为 3.7。
- 依赖是否安装成功。
- 程序是否可以在开发环境启动。
- 默认配置文件是否存在。
- 默认模板文件是否存在。
- 资源文件路径是否正确。
- 应用版本号是否正确。
建议命令：
python --version
pip freeze
python src/main.py
11. 打包后验证
打包后必须验证：
- 双击
CMBot.exe可以启动。 - 标题栏显示正确版本号。
- 可以打开衣服图片文件夹。
- 可以打开印花图片文件夹。
- 可以显示预览区。
- 可以拖动、缩放、旋转印花。
- 可以导出当前单张图片。
- 可以生成日志文件。
- 程序关闭后再次启动正常。
若测试机器没有 Python 环境，应优先在该机器上验证。
12. 发布产物
第一阶段发布产物建议为压缩包：
CMBot-1.0.0.zip
压缩包内包含：
CMBot-1.0.0/
CMBot.exe
_internal/
config/
resources/
README.txt
不应包含：
- 源代码。
- 测试文件。
- 开发环境缓存。
- 临时输出图片。
- 本机私人配置。
- 打包中间目录。
13. 暂不做
第一阶段不做：
- 局域网共享目录发布。
- 自动检查新版本。
- 自动下载更新。
- 多版本共存启动器。
- 按电脑名控制版本。
- 安装程序。
- Windows 注册表写入。
- 开机自启动。
如果后续要增加这些能力，应新增或扩展发布分发文档，不能直接混入当前第一阶段打包规则。