zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

fix(packaging): 发布包 exe 的 PE 版本资源必须等于发布版本（v0.2.2）

Browse Source 
缺陷（v0.2.1 实测）：把 opendance-windows-v0.2.1.zip 解开、在 Windows 上
「右键 → 属性 → 详细信息」，显示的是

    文件版本    0.1.0
    产品版本    0.1.0

而产物名、Git tag、README 全是 v0.2.1 —— 正是文档 §11.2 要禁止的
「不可核对的发布」。

根因：export_presets.cfg 的 application/file_version /
application/product_version 被硬编码在 0.1.0，而它们**不会**跟随
project.godot 的 application/config/version 自动更新；check-version.sh 当时
只比 project.godot ↔ project.yaml（两处一致），所以静态校验全绿、产物却是错的。
漂移发生在没人看的第三个位置 —— 校验位置少一个，等于没校验。

证据：
  strings -a -el OpenDance.exe  ->  FileVersion 0.1.0 / ProductVersion 0.1.0
  VS_FIXEDFILEINFO @0x67b976c   ->  FileVersion 0.1.0.0 / ProductVersion 0.0.0.0
对照组：官方模板 windows_release_x86_64.exe 的 FileVersion = 4.7.2，
说明本机 rcedit 改写是生效的，问题纯粹在预设的值本身。

修复：
  * build/sync-export-version.sh（新增）：导出前把版本号写进导出预设，
    幂等、拒绝非 X.Y.Z；
  * build/check-pe-version.sh（新增）：直接读 exe 的 PE 版本资源 ——
    VS_FIXEDFILEINFO（签名 0xFEEF04BD 后 16 字节，grep -abo 取偏移约 40 ms）
    与 StringFileInfo（strings -el，资源管理器属性页显示的就是它）。
    两处都查：实测固定信息里的 ProductVersion 恒为 0.0.0.0；
  * build/check-version.sh：新增导出预设两个键的校验；
  * build/export-windows.sh：导出前同步、导出后直接复核产物；
  * build/package-release.sh：打包前校验源 exe、解包后再校验包内 exe；
  * build/verify.sh：新增步骤 1/5「产物 PE 版本资源」（未导出则跳过）；
  * tests/test_about.gd：新增 test_export_preset_version_matches_project_version。

反向验证：把预设 file_version 改回 0.1.0 →
  check-version.sh 退出码 1（报出两处不一致）；
  无头测试 753 通过 / 1 失败，失败项正是
  「导出预设的 file_version 与版本号唯一来源一致」。

实测 v0.2.2 产物：PE FileVersion 0.2.2.0 / StringFileInfo 0.2.2，
版本号在 project.godot / project.yaml / export_presets.cfg / exe 元数据 /
产物名 / tag 六处一致。verify.sh 全绿（754 通过 / 0 失败 / 5 跳过）。

同时把 LZMA 压缩的取舍写清楚：deflate 包 38,248,818 B 仍超 IIS
30,000,000 B 上限，故 Release 资产仍是 LZMA 整包（26,628,529 B，不拆分卷）；
若上限放开或改由 Web /static 分发，用 ZIP_METHOD=deflate 重打包即可得到
资源管理器可直接双击解压的包。
This commit is contained in:
zijunchiang
2026-09-17 04:22:57 +08:00
parent 14ee5f7ec9
commit ba988f6ca6
13 changed files with 450 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -13
View File
@@ -22,10 +22,36 @@ OpenDance Studio **阶段二**: Windows 客户端（Godot 4）。
| 跨实现交叉校验 | OK 关节角与 Web 服务端 TypeScript 实现**逐帧一致** |
| 场景选择与物理落地 | OK `scenes[]` 可选、重力/风/摩擦/碰撞体落地并可日志核对 |
| 连接保活与设备去重 | OK welcome/config 声明静默超时与心跳；应用层 ping/pong；按 deviceId 去重 |
| 发布整包 | OK 单个 `opendance-windows-v0.2.1.zip` + `SHA256SUMS`(不拆分卷) |
| 版本号展示 | OK 「关于」清单显示 `v0.2.0`，来源唯一(`project.godot`) |
| 发布整包 | OK 单个 `opendance-windows-v0.2.2.zip` + `SHA256SUMS`(不拆分卷) |
| 版本号展示 | OK 「关于」清单显示 `v0.2.2`；`project.godot` / `project.yaml` / `export_presets.cfg` / exe 的 PE 版本资源 / 产物名 / tag 全部一致 |
| 场景物理与保活 | OK 新增真实 GLB 端到端用例 + 17 秒保活对照用例（751 项断言全过） |
## v0.2.2 修订（发布包 exe 的版本元数据）
**缺陷**：v0.2.1 的包在 Windows 上「右键 → 属性 → 详细信息」显示
**文件版本 0.1.0 / 产品版本 0.1.0**，而产物名与 Git tag 都是 v0.2.1。
**根因**：`export_presets.cfg` 的 `application/file_version` /
`application/product_version` 被硬编码在 `0.1.0`，而它们**不会**跟随
`project.godot` 的 `application/config/version` 自动更新；`check-version.sh`
当时只比 `project.godot` ↔ `project.yaml`（两处一致），所以静态校验全绿、
产物却是错的 —— 漂移发生在没人看的第三个位置。
**修复**：
| 环节 | 做法 |
|--|--|
| 同步 | `build/sync-export-version.sh`（新增）：导出前把版本号写进导出预设（幂等，拒绝非 `X.Y.Z`） |
| 静态防线 | `build/check-version.sh`：新增对导出预设两个键的校验 |
| 产物防线 | `build/check-pe-version.sh`（新增）：直接读 exe 的 PE 版本资源 —— `VS_FIXEDFILEINFO`（签名 `0xFEEF04BD` 后 16 字节）+ `StringFileInfo`（`strings -el`，属性页显示的就是它）。两处都查：本机实测固定信息里的 `ProductVersion` 恒为 `0.0.0.0` |
| 打包 | `build/package-release.sh`：打包前校验源 exe、解包后再校验包内 exe |
| 一键验证 | `build/verify.sh`：新增步骤 1/5（未导出则跳过） |
| 单元测试 | `tests/test_about.gd`：预设两个键必须等于版本号唯一来源 |
实测修复后产物：`VS_FIXEDFILEINFO FileVersion = 0.2.2.0`、
`StringFileInfo FileVersion/ProductVersion = 0.2.2`。详见
[`tasks/017-pe-version.md`](tasks/017-pe-version.md)。
## v0.2.1 修订（两处修复 + 一批"真机等价"测试）
1. **场景包围盒不再用 `global_transform`**：`SceneRuntime._compute_aabb()` 原本在
@@ -57,11 +83,12 @@ GODOT_BIN=/path/to/godot bash build/verify.sh
GODOT_BIN=/path/to/godot bash build/export-windows.sh release
# 打包发布产物（单个完整 zip + SHA256SUMS）
bash build/package-release.sh 0.2.1
bash build/package-release.sh 0.2.2
```
当前版本：**v0.2.1**（`project.godot` 的 `application/config/version`，
与 `project.yaml`、导出产物名、Git tag、「关于」清单展示一致）。
当前版本：**v0.2.2**（`project.godot` 的 `application/config/version`，
与 `project.yaml`、`export_presets.cfg`、导出产物名、Git tag、「关于」清单展示、
以及 exe 的 PE 版本资源全部一致）。
详细使用说明见 [`README.txt`](README.txt)，工程约束见 [`DSH.md`](DSH.md)。
@@ -142,7 +169,7 @@ GODOT_BIN=/path/to/godot bash build/export-windows.sh release
powershell -ExecutionPolicy Bypass -File build\export-windows.ps1
# 打成可分发的 zip（单个完整包 + SHA256SUMS）
bash build/package-release.sh 0.2.1
bash build/package-release.sh 0.2.2
```
| 产物 | 位置 | 说明 |
@@ -150,7 +177,7 @@ bash build/package-release.sh 0.2.1
| `OpenDance.exe` | `build/windows/` | 主程序，约 104 MB；脚本校验前 2 字节为 `MZ`(合法 PE) |
| `OpenDance.pck` | `build/windows/` | 资源包，约 107 KB; **必须与 exe 同目录** |
| `OpenDance.console.exe` | `build/windows/` | 控制台包装器，可能生成，非必需 |
| `opendance-windows-v0.2.1.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` |
| `opendance-windows-v0.2.2.zip` | `dist-release/` | 发布包：exe + pck + `THIRD_PARTY.md` + `README.txt` + `README.md` + `contracts/` |
| `SHA256SUMS` | `dist-release/` | 裸文件名，与 zip 同目录时可 `sha256sum -c SHA256SUMS` 直接校验 |
导出前必须安装与编辑器同版本的 export templates，否则脚本会报「未找到导出模板」。
@@ -247,12 +274,21 @@ src/
`zip.part0/1/2`（无法直接解压）。现改为**只上传单个完整包**，超限时打包脚本
直接告警并要求运维放宽上限，不再回退分卷；做法见
`opendance-web/deploy/proxy/README.md` 第九节。
6. **v0.2.0 的 zip 用的是 LZMA 压缩**（`ZIP_METHOD=lzma` 打出来的），因为发布时
IIS 上限尚未放开：整包从约 38 MB 降到约 26 MB 才能传上去。
**代价：Windows 10 的资源管理器不支持 LZMA(method 14) 的 zip，必须用
7-Zip / WinRAR / PeaZip 解压**（Win11 24H2+ 起资源管理器原生支持 7z 等格式，
但本项目未在 Windows 上实测）。若 IIS 上限已放开，请改用默认的 deflate 包
（`bash build/package-release.sh 0.2.1`，产物约 38 MB，双击即可解压）。
6. **v0.2.0 / v0.2.1 / v0.2.2 的 zip 用的是 LZMA 压缩**（`ZIP_METHOD=lzma`
打出来的），因为这几次发布时 IIS 上限都尚未放开：整包从约 38 MB 降到约 26 MB
才能传上去。**代价：Windows 10 的资源管理器不支持 LZMA(method 14) 的 zip，
必须用 7-Zip / WinRAR / PeaZip 解压**（Win11 24H2+ 起资源管理器原生支持 7z
等格式，但本项目未在 Windows 上实测）。
若 IIS 上限已放开、或你能把包放到别处分发（例如 Web 服务端的 `/static`，
不受 IIS 那个限制约束），请改用资源管理器可直接双击解压的 deflate 包：
`ZIP_METHOD=deflate bash build/package-release.sh 0.2.2`（约 38 MB）。
7. **发布包 exe 的版本元数据**（T-WIN-017）：v0.2.1 之前在 Windows
「属性 → 详细信息」里显示的是 `0.1.0`，因为 `export_presets.cfg` 的
`application/file_version` / `application/product_version` 被硬编码且无人校验。
v0.2.2 起由 `build/sync-export-version.sh` 在导出前同步、由
`build/check-pe-version.sh` 直接读 exe 的 PE 版本资源复核
（`VS_FIXEDFILEINFO` + `StringFileInfo` 两处都查），
`check-version.sh` / `package-release.sh` / `verify.sh` / `test_about.gd` 均已接入。
## 第三方开源声明