游戏引擎 / 系统课时
怎样自动校验构建产物
怎样自动校验构建产物
构建进程成功退出,不代表产物就符合发布要求:包名错、版本未更新、归档损坏或包体超限,都会把问题推迟到渠道审核阶段。本课以 Cocos Creator 生成的 Android APK 为对象,编写可在 CI 中阻断发布的四项检查。
学习目标
- 从 APK 实际清单核对包名和版本,而不是相信文件名。
- 检查 ZIP 内容完整性、必要文件与包体大小。
- 将失败转换为 CI 非零退出码,并记录产物 SHA-256。
从最终 APK 而不是工程目录检查
原生 Android 构建通常先由 Cocos Creator 生成原生工程,再通过 Android 构建工具产出 APK。验证对象应是将要分发的最终 .apk 文件,而不是 build/android 工程目录;不同构建方式下实际输出路径可能不同,应由流水线明确传入。
这次检查四类事实:APK 中的 applicationId、versionCode、versionName 是否与发布计划一致;压缩包能否完整读取;是否包含 AndroidManifest.xml 和 DEX 文件;最终 APK 文件的字节数是否超过渠道预算。aapt2 dump badging 从 APK 清单读取真实包信息,Python 标准库 zipfile 检查 ZIP 条目的 CRC。命令格式可参照Android 官方示例。

编写可失败的 APK 校验器
运行环境需要 Python 3 和 Android SDK Build Tools 中的 aapt2,并让 aapt2 位于 PATH;也可以通过脚本的 --aapt2 指向可执行文件。下列完整脚本保存为 ci/verify-apk.py,输入均来自当前发布任务,不把示例包名写死在程序里。
import argparse
import hashlib
import re
import subprocess
import zipfile
from pathlib import Path
def fail(message):
raise SystemExit(f"FAIL: {message}")
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--apk", type=Path, required=True)
parser.add_argument("--package-id", required=True)
parser.add_argument("--version-code", required=True)
parser.add_argument("--version-name", required=True)
parser.add_argument("--max-mib", type=float, required=True)
parser.add_argument("--aapt2", default="aapt2")
args = parser.parse_args()
if not args.apk.is_file():
fail("APK 文件不存在")
size = args.apk.stat().st_size
if size == 0 or args.max_mib <= 0:
fail("APK 为空或体积上限无效")
if size > args.max_mib * 1024 * 1024:
fail("APK 体积超过上限")
# 先验证容器结构与全部条目的 CRC,再读取清单元数据。
try:
with zipfile.ZipFile(args.apk) as archive:
names = set(archive.namelist())
if "AndroidManifest.xml" not in names:
fail("缺少 AndroidManifest.xml")
if not any(name.endswith(".dex") for name in names):
fail("缺少 DEX 文件")
damaged = archive.testzip()
if damaged is not None:
fail(f"文件 CRC 校验失败:{damaged}")
except (OSError, RuntimeError, zipfile.BadZipFile) as exc:
fail(f"APK 归档损坏:{exc}")
try:
result = subprocess.run(
[args.aapt2, "dump", "badging", str(args.apk)],
check=True, capture_output=True, text=True
)
except (OSError, subprocess.CalledProcessError) as exc:
fail(f"aapt2 读取失败:{exc}")
# package 行来自 APK,而非 CI 命名规则或源工程配置。
match = re.search(
r"^package:\s+name='([^']+)'\s+versionCode='([^']+)'\s+versionName='([^']*)'",
result.stdout, re.MULTILINE
)
if match is None:
fail("无法解析 APK 包名及版本")
actual = match.groups()
expected = (args.package_id, args.version_code, args.version_name)
if actual != expected:
fail(f"清单不匹配:实际={actual},预期={expected}")
digest = hashlib.sha256()
with args.apk.open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
digest.update(chunk)
print(f"PASS package/version, ZIP CRC, size ({size / 1024**2:.2f} MiB)")
print(f"sha256={digest.hexdigest()}")
if __name__ == "__main__":
main()预期结果:脚本通过后续命令接收真实 APK 和发布参数;全部检查合格时输出 PASS 与 SHA-256,任一检查失败则以非零状态退出。此脚本不依赖 Cocos 编辑器运行,只依赖待验证的 APK 和 Android SDK 工具。
在流水线中执行和验收
确认 Creator 的原生工程已经由 Android 构建流程编译成最终 APK 后,执行下面的命令。<PATH> 表示实际 APK 所在目录,<ID> 替换成发布渠道要求的真实包名;42、1.2.3 和 80 只是演示版本号与 80 MiB 上限,必须替换为当次发布计划。
python3 ci/verify-apk.py \
--apk "<PATH>/app-release.apk" \
--package-id "<ID>" \
--version-code 42 \
--version-name 1.2.3 \
--max-mib 80预期输出(校验通过时,实际大小和哈希值不同):
PASS package/version, ZIP CRC, size (<SIZE> MiB)
sha256=<HASH>任一项失败时脚本抛出 SystemExit 并以非零状态退出,CI 应立即停止发布。可以用一次故意错误的 --version-code 和一次低于实际包体积的 --max-mib 做反向验收,确认不是只打印错误而仍然上传产物。
校验范围与发布边界
CRC 能发现 ZIP 条目损坏,却不能证明 APK 的来源可信或签名有效;SHA-256 在这里只是计算制品指纹,只有与可信记录的哈希值比较才能验证传输前后是否一致。正式 Android 发布仍需额外执行 apksigner verify 等签名检查,并按发布渠道要求验证 APK 或 AAB;AAB 不应套用本例的 APK 元数据检查命令。
包体积阈值按目标渠道和包类型分别维护,防止把 Web 文件夹大小、APK 和 AAB 混为一谈。最终应把校验脚本置于上传和分发操作之前,让只有包身份正确、版本匹配、内容可读且体积合规的 APK 进入发布环节。