123 lines
5.0 KiB
Markdown
123 lines
5.0 KiB
Markdown
# 打包与分发
|
||
|
||
> T-524 目标：先把当前 Windows 桌面工具打成免安装 onedir `.exe`，方便第一版交付使用。T-538 后用户数据统一收进程序同级 `data/`，暂不做自动更新器、安装器、增量补丁或在线升级。
|
||
|
||
## 一、打包前提
|
||
|
||
- 在 Windows 环境执行。
|
||
- Python 环境已能运行源码版 `python main.py`。
|
||
- 打包脚本使用当前 PATH 中的 `python`；正式出包前先确认 `python --version` 符合项目目标 Python 3.10+。
|
||
- 安装运行依赖和打包依赖：
|
||
|
||
```powershell
|
||
python -m pip install -r requirements-build.txt
|
||
```
|
||
|
||
`requirements-build.txt` 会先安装 `requirements.txt` 的运行依赖，再安装 PyInstaller。
|
||
|
||
## 二、打包命令
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
|
||
```
|
||
|
||
脚本会执行：
|
||
|
||
```powershell
|
||
python -m PyInstaller --noconfirm --clean cmshopee.spec
|
||
```
|
||
|
||
成功后输出：
|
||
|
||
```text
|
||
dist\cmshopee\cmshopee.exe
|
||
```
|
||
|
||
发布给用户时，以整个 `dist\cmshopee\` 文件夹为单位压缩分发，用户双击 `cmshopee.exe` 启动。当前 PyInstaller 5.13.2 的 onedir 是扁平结构，`cmshopee.exe` 与 DLL/PYD/依赖目录同级，`_internal\` 不作为当前验收标准。
|
||
|
||
## 三、绝不打包的本地数据
|
||
|
||
发布包里不能包含以下本地数据、密钥、业务数据或登录态：
|
||
|
||
- `config.json`
|
||
- `config/ai_models.json`
|
||
- `config/cmhub.json`
|
||
- `cmshopee.db`、`cmshopee.db-wal`、`cmshopee.db-shm`
|
||
- `db.sqlite`
|
||
- `chrome_user_data_dir/`
|
||
- `images/`
|
||
- `logs/`
|
||
- `prompts/`
|
||
- `title_prompt.txt`
|
||
- `data/`
|
||
- 运营填写后的 Excel 文件
|
||
|
||
`cmshopee.spec` 不声明任何 `datas`；`scripts/build_exe.ps1` 会在打包后检查 `dist\cmshopee\`，如果发现上述路径会直接失败。
|
||
|
||
## 四、首次运行与本地数据位置
|
||
|
||
T-538 后，打包版不再把全进程工作目录切到 `cmshopee.exe` 所在目录；路径由 `app/appconfig.py` 按显式数据根解析。
|
||
|
||
首次运行时，程序会在 exe 同级创建单独的 `data\` 子目录，并把所有用户本地数据放进去：
|
||
|
||
```text
|
||
cmshopee\
|
||
cmshopee.exe
|
||
<PyInstaller 依赖文件和依赖目录>
|
||
data\
|
||
config.json
|
||
config\
|
||
ai_models.json
|
||
cmhub.json
|
||
cmshopee.db
|
||
chrome_user_data_dir\
|
||
images\
|
||
logs\
|
||
prompts\
|
||
title_prompt.txt
|
||
```
|
||
|
||
源码运行时同理使用项目根目录下的 `data\`。`config.json` 内的 `user_data_root`、`image_dir`、`db_path` 默认仍保存为 `chrome_user_data_dir`、`images`、`cmshopee.db` 等相对值，运行时再解析到 `data\` 下，保持便携。
|
||
|
||
这些文件属于用户本地数据，不随新版本程序包覆盖。
|
||
|
||
### 旧布局迁移
|
||
|
||
如果用户从 T-524 旧包升级，新版首次启动会检查 exe 顶层是否存在旧布局数据，例如 `config.json`、`config\`、`cmshopee.db`、`chrome_user_data_dir\`、`images\`、`logs\`、`prompts\`、`title_prompt.txt`。若 `data\` 中没有同名目标，程序会自动移动到 `data\` 下。
|
||
|
||
如果旧布局和 `data\` 中同时存在同名数据，程序不会覆盖，会以“数据迁移冲突”提示用户先手动合并或备份，避免误丢账号、任务、图片或登录态。此类冲突不是目录不可写，不应直接归类为“数据目录不可写”。
|
||
|
||
启动时会检测 `data\` 是否可写；如果程序放在 `Program Files` 等只读目录导致写入失败，才会以“数据目录不可写”提示“请把程序放到可写目录，勿放 Program Files”并退出。
|
||
|
||
## 五、用户后续更新方式
|
||
|
||
第一版不做自动更新。给用户发新版本时：
|
||
|
||
1. 让用户先关闭 cmshopee。
|
||
2. 建议用户备份当前整个程序文件夹。
|
||
3. 解压新版 `dist\cmshopee\`。
|
||
4. 覆盖新版程序文件和依赖文件。当前 PyInstaller 5.13.2 是扁平 onedir，不能只覆盖 `cmshopee.exe`，也没有 `_internal/` 可单独替换。
|
||
5. 保留旧目录里的 `data\`，不要删除、覆盖或合并它。
|
||
|
||
如果用户把整个旧目录删除再放新版，`data\` 里的账号、任务记录、图片和登录态也会一起丢失，只能从备份恢复。
|
||
|
||
## 六、验证清单
|
||
|
||
打包前后至少执行：
|
||
|
||
```powershell
|
||
python -m compileall app main.py
|
||
python -m unittest discover -s tests
|
||
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
|
||
```
|
||
|
||
打包成功后确认：
|
||
|
||
- `dist\cmshopee\cmshopee.exe` 存在。
|
||
- 当前 PyInstaller 5.13.2 下 `dist\cmshopee\` 是扁平 onedir，`_internal\` 不存在也属于正常。
|
||
- `dist\cmshopee\` 中没有第三节列出的本地数据，尤其不能含 `data\`。
|
||
- 在干净目录首次启动时能生成 `data\config.json` 并进入 GUI。
|
||
- 在目标 Windows 10/11 机器或虚拟机上启动 release exe 后，主窗口标题栏完整可见，左边缘不出屏，用户能用标题栏拖动窗口；小分辨率环境不得出现窗口卡在左上角且标题栏不可拖动的问题（见 T-541）。
|
||
|
||
涉及 Shopee/CDP 的真实更新能力，仍按任务文档要求用测试商品做人工回归；打包任务本身不新增自动绕过登录、验证码或风控的能力。
|