8.5 KiB
8.5 KiB
打包与发布指南
本仓库提供三套打包脚本，分别用于主框架整站升级包、单个插件市场包、批量插件市场包。 三者均已支持自动递增版本号，并配套「框架在线升级的数据库变更」机制。
部署（中心站 / 客户端如何对接）不在本文范围，参见
docs/DEPLOY_INTEGRATION.md。
0.0 产物与用途总览
package_framework.php 一次运行同时产出三个文件；插件包由独立脚本产出：
| 产物 | 来源命令 | 输出位置 | 用途 |
|---|---|---|---|
框架整包 ywxapp-<ver>.zip |
package_framework.php |
build/framework/ |
框架升级（整站覆盖） |
框架补丁 ywxapp-<ver>-patch.zip |
package_framework.php |
build/framework/ |
框架增量升级（from_version 起 git diff） |
完整安装包 ywxapp-<ver>-install.zip |
package_framework.php |
build/framework/ |
新站首次部署（白名单：app/config/extend/public/ywxapp/route + 根文件；不含插件、不含真实 .env/database.php/ywxapp.php，内置 .env 占位模板） |
| 插件市场 zip + 测试 SQL | package_all_addon.php / package_appmarket_addon.php |
build/addon/、build/sql/ |
上传到应用市场后台，供客户机后台购买后下载安装 |
⚠️ 重要约定
- 框架整包与完整安装包都刻意不含
addon/插件目录（整包经includeDirs排除；安装包用白名单 + 排除public/static/<插件>/、public/addon/）。全新部署框架后，插件需经后台应用市场独立下载安装，不要把插件打进框架包。package_install.php已废弃并合并进package_framework.php（安装包产物由后者统一产出），请勿再单独调用。- 插件走「后台购买 → 下载 → 安装」的在线分发链路，与框架整包互相独立，二者不要混包。
0. 版本号来源（重要）
| 产物 | 版本号来源 | 是否进包 | 写回位置 |
|---|---|---|---|
| 主框架整站包 | config/ywxapp.php 第 37 行 version |
不进包（被排除） | config/ywxapp.php |
| market 插件包 | addon/appmall/info.php 的 version |
不进包（随插件本身） | addon/appmall/info.php |
| 其他插件包 | addon/<name>/info.php 的 version |
不进包（随插件本身） | addon/<name>/info.php |
- 框架版本与各插件版本互相独立，各自维护、各自递增。
- 打包脚本每次都会把新版本写回对应文件，保证下次打包在此基础上再
+1。 - 写回会改动 git 跟踪文件，属预期行为；但该文件被排除在升级包外，不会覆盖客户机。
1. 主框架整站升级包 — scripts/package_framework.php
生成「整站升级包」（含 app/config/extend/ywxapp/public/route + 根文件 think/composer.json/README.md/LICENSE.txt），
客户端 ywxapp/service/FrameworkService::apply() 解压即完成整站升级。
产物（build/framework/，非 Web 可访问）：
ywxapp-<version>.zip—— 整包（整站，不含插件）ywxapp-<version>-patch.zip—— 增量补丁包（from_version= 基础版本）
安全排除（绝不进包，避免覆盖客户机本地配置与数据）：
runtime/、vendor/、data/、.git、public/uploads、config/database.php、config/ywxapp.php、.env、install.lock、addon/（插件独立分发）。
用法（支持自动递增版本号）
# 不带版本号：自动按 patch +1（读 config/ywxapp.php 当前版本，写回新值）
php scripts/package_framework.php
# 按段递增
php scripts/package_framework.php minor # 如 1.0.2 -> 1.1.0
php scripts/package_framework.php major # 如 1.0.2 -> 2.0.0
# 显式指定新版本
php scripts/package_framework.php 1.2.3
baseVersion为第二可选参数（升级起点/补丁基础版本），缺省取写回前的旧值。- 打包前会跑
regressionCheckConfigVersion()校验，拦截「写坏配置」的历史 bug 写法（若触发直接中断打包）。
数据库升级 SQL 约定
若本次升级涉及数据库结构/数据变更，把增量 SQL 放到仓库 ywxapp/upgrade.sql：
- 整站包包含
ywxapp/目录，upgrade.sql会自动打进包，解压后位于项目根/ywxapp/upgrade.sql。 apply()解压完成后自动检测并执行（coreDir/upgrade.sql或root/upgrade.sql）。- 按语句拆分（忽略
--行注释与/* */块注释），用Db::connect()->execute()执行。 - 幂等：已执行版本记入
runtime/framework/sql_applied.json（版本:文件名为键），重复升级不重复执行；执行成功后会删除该upgrade.sql。 - 执行失败抛
数据库升级失败：...异常，由升级流程提示（文件已提前备份）。 - ⚠️ 无事务回滚，SQL 须写成幂等（如
CREATE TABLE IF NOT EXISTS、ADD COLUMN IF NOT EXISTS），并在预发环境先验证。
2. 单个插件市场包 — scripts/package_appmarket_addon.php
把本地插件打包成市场 zip（结构对齐 AddonService::package()）：addon/<name>/ 为 zip 根，public/static/addon/<name>/ 为 static/ 前缀。
并生成 wxapp_appmarket_addon_list 测试记录 SQL（用于往中心站插一条数据，便于联调）。
产物：
build/addon/<addon>-<version>.zipbuild/sql/<addon>-<version>-appmarket_addon_list.sql（测试记录，file_path为本地绝对路径，中心站部署时需改成实际路径或走后台上传）
用法（支持自动递增版本号）
# 不带版本号：自动按 patch +1（读 addon/<addon>/info.php 当前版本，写回新值）
php scripts/package_appmarket_addon.php appmall
# 按段递增
php scripts/package_appmarket_addon.php appmall minor # 1.0.1 -> 1.1.0
# 显式指定
php scripts/package_appmarket_addon.php appmall 1.2.0
# 兼容旧式（带标题等可选参数，version 缺省则按 patch 自动递增）
php scripts/package_appmarket_addon.php mqttbroker "MQTT代理" "" "基于 Workerman 自研 MQTT Broker" 0
- 版本参数位于
$argv[2]：若匹配x.y.z或major|minor|patch，则视为版本参数，其后title/author/description/price整体左移一位，保持旧调用兼容。
3. 批量插件市场包 — scripts/package_all_addon.php
一次性打包 addon/ 下所有插件。
产物：build/addon/<name>-<version>.zip + build/sql/<name>-<version>-appmarket_addon_list.sql（每个插件一份）。
用法
# 不带 bump：按各插件 info.php 当前版本打包，不改版本号（安全、可重复执行）
php scripts/package_all_addon.php
# bump：每个插件版本按 patch +1 并写回各自 info.php（发版用）
php scripts/package_all_addon.php bump
# 跳过指定插件（与 bump 可组合）
php scripts/package_all_addon.php skip:market
php scripts/package_all_addon.php bump skip:market
⚠️
bump会修改所有被打包插件的info.php版本号。日常只想重新生成 zip 时不要带bump。
4. 典型发版流程
# 1) 框架整站升级（自动 +1，含可选 upgrade.sql）
php scripts/package_framework.php
# 2) 中心站插件（market）发版（自动 +1）
php scripts/package_appmarket_addon.php appmall
# 3) 其余插件批量发版（各 +1）
php scripts/package_all_addon.php bump
- 把
build/framework/ywxapp-<ver>.zip（整包）在中心站后台「主框架版本管理」上传并发布（客户端方可检测；该整包即新站安装包，不含插件）。 - 把
build/addon/*.zip在中心站「应用市场管理 / 插件审核」上传，或走后台「上传升级包」（客户机后台购买后下载安装）。 - 涉及数据库变更时，确保打包前已把增量 SQL 写入
ywxapp/upgrade.sql（随包发布、升级时自动执行）。
5. 常见问题
- Q：怎么让每次打包版本号自动 +1？
A：框架包直接空参运行；插件包空参或带
minor/major；批量包带bump。三者都会写回版本文件。 - Q：框架升级改了数据库表结构，客户机怎么同步？
A：把增量 SQL 放
ywxapp/upgrade.sql，随包发布，apply()自动幂等执行（见第 1 节）。 - Q：补丁包比整包大 / 变更很多？ A：补丁基于 git 工作树相对基础版本的 diff。若工作树相对某基线改动很多，补丁会偏大；先把代码提交到稳定基线后再打，补丁即为当次真实改动。
- Q：打包提示 LF/CRLF 警告？
A：git
autocrlf噪声，非错误，可忽略。