163 lines
8.5 KiB
Markdown
163 lines
8.5 KiB
Markdown
# 打包与发布指南
|
||
|
||
本仓库提供三套打包脚本，分别用于**主框架整站升级包**、**单个插件市场包**、**批量插件市场包**。
|
||
三者均已支持**自动递增版本号**，并配套「框架在线升级的数据库变更」机制。
|
||
|
||
> 部署（中心站 / 客户端如何对接）不在本文范围，参见 `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/`（插件独立分发）。
|
||
|
||
### 用法（支持自动递增版本号）
|
||
|
||
```bash
|
||
# 不带版本号：自动按 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>.zip`
|
||
- `build/sql/<addon>-<version>-appmarket_addon_list.sql`（测试记录，`file_path` 为本地绝对路径，中心站部署时需改成实际路径或走后台上传）
|
||
|
||
### 用法（支持自动递增版本号）
|
||
|
||
```bash
|
||
# 不带版本号：自动按 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`（每个插件一份）。
|
||
|
||
### 用法
|
||
|
||
```bash
|
||
# 不带 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. 典型发版流程
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
1. 把 `build/framework/ywxapp-<ver>.zip`（整包）在中心站后台「主框架版本管理」上传并**发布**（客户端方可检测；该整包即**新站安装包**，不含插件）。
|
||
2. 把 `build/addon/*.zip` 在中心站「应用市场管理 / 插件审核」上传，或走后台「上传升级包」（客户机后台购买后下载安装）。
|
||
3. 涉及数据库变更时，确保打包前已把增量 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` 噪声，非错误，可忽略。
|