游戏引擎 / 系统课时

怎样自动校验构建产物

怎样自动校验构建产物

构建进程成功退出,不代表产物就符合发布要求:包名错、版本未更新、归档损坏或包体超限,都会把问题推迟到渠道审核阶段。本课以 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 官方示例。

Android APK 发布前四项校验及失败阻断流程

编写可失败的 APK 校验器

运行环境需要 Python 3 和 Android SDK Build Tools 中的 aapt2,并让 aapt2 位于 PATH;也可以通过脚本的 --aapt2 指向可执行文件。下列完整脚本保存为 ci/verify-apk.py,输入均来自当前发布任务,不把示例包名写死在程序里。

python
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 上限,必须替换为当次发布计划。

bash
python3 ci/verify-apk.py \
  --apk "<PATH>/app-release.apk" \
  --package-id "<ID>" \
  --version-code 42 \
  --version-name 1.2.3 \
  --max-mib 80

预期输出(校验通过时,实际大小和哈希值不同):

text
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 进入发布环节。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

怎样自动校验构建产物

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通