《Cocos 游戏开发实战》18.1 发布检查清单

18.1 发布检查清单

这一节要还一笔账。第 1.1 节开工时，我们把《方块冲刺》的验收标准写成了三张表——功能需求 FR-01 到 FR-08、非功能需求 NFR-01 到 NFR-06、用例 UC-01 到 UC-05——还把它们压缩成一个可执行的纯函数 evaluateAcceptance。整个卷二都在朝这些标准走。现在到了发布前夜，该把它们逐条变成可勾选的检查项。

本节把《方块冲刺》推进到「可发布」：先回看 1.1 的三张验收表，再按功能、非功能、用例、三端构建、合规五个维度展开检查清单，给出构建面板的实际取值，最后用一张发布单把「我发的是哪个包、验了哪些项」固定下来。收口时，你的发布流程从「打包上传」升级为「照着清单走一遍」。

18.1.1 回看 1.1：验收标准长什么样

先把 1.1 定下的硬指标原样列出来。非功能需求（NFR）是发布前最容易被忽略、却最能决定成败的一组：

1.1 里还写了 ACCEPTANCE_BUDGET 与 evaluateAcceptance：它把 fps、firstPaintMs、firstPackageKb、crashFreeRate 四个采样值喂进去，返回「过没过、哪几项没过」。发布前的验收不是「感觉还行」，而是把实测采样喂给这个函数，让它返回 pass: true。

功能需求（FR-01…FR-08）与用例（UC-01…UC-05）则分别回答「玩起来对不对」和「关键路径通不通」。下面四节就是这三张表的验收动作。

18.1.2 功能维度：对照 FR-01…FR-08

• FR-01 自动跑 + 速度随关卡递增：进第 5 关，速度明显快于第 1 关
• FR-02 点击/空格跳跃，二段跳上限 2 次：连按三次，第三次不生效
• FR-03 收集金币分数实时更新：吃一枚，分数立刻 +1
• FR-04 三种道具各 8 秒，同类刷新不叠加：连吃两个加速，计时不累加
• FR-05 撞障碍进入结算、可重开：结算页「重开」能回到关卡 1
• FR-06 关卡进度、最高分、金币总额持久化：杀进程重进，三项都在
• FR-07 中英文切换：切到英文，UI 文案无残留中文
• FR-08 微信端分享与激励视频复活：真机上各走一次

FR-04 那条最值得现场测：「同类道具刷新时长不叠加」是数值设计的关键约束，一旦叠加，玩家能靠连续吃道具无限无敌。检查项写成「连吃两个加速，计时不累加」，比写「道具逻辑正确」有用得多。

18.1.3 非功能维度：对照 NFR-01…NFR-06

• NFR-01 主流机 ≥ 60 fps、低端机 ≥ 55 fps：在目标低端机上跑满一局
• NFR-02 中端机首屏 ≤ 1.2 秒：看启动埋点的 firstPaint 采样
• NFR-03 微信主包 ≤ 4 MB：量构建产物，超了回到 15.1 继续分包
• NFR-04 崩溃免疫率 ≥ 99.5%：上线后持续看，发布前先确认上报链路通
• NFR-05 内存峰值 ≤ 180 MB：连续玩十关，看 Profiler 峰值
• NFR-06 Draw Call ≤ 60：进最复杂的一关，看渲染统计
• 把四项采样喂给 evaluateAcceptance，返回 pass: true

NFR-01 与 NFR-06 是耦合的：合批没做好，Draw Call 一高，低端机帧率就掉（13.1 讲过）。所以这两条要一起看，别只测帧率、不看 Draw Call——后者才是你能动手改的那个。

数字要带条件。NFR-01 的「低端机」指 2019 年前后发布的骁龙 6 系机型；在旗舰机上跑出的 60 fps 不能作为验收依据。无法实测的项，明确写「参考值，需在你的目标机型上复测」。

18.1.4 用例维度：对照 UC-01…UC-05

用例是「谁在什么情况下怎么做」，它验证的是关键路径而不是单点功能：

• UC-01 首次进入：冷启动 → 主菜单 → 点「开始」→ 关卡 1，无白屏
• UC-02 单局游玩：跑 → 跳 → 吃金币 → 撞障碍 → 结算，全程不掉帧
• UC-03 复活：结算页看激励视频 → 原地复活 → 继续
• UC-04 断线重进：切后台再回，靠存档恢复到主菜单
• UC-05 换设备：新设备登录 → 拉云存档 → 继续

UC-04 是最容易被忽略的一条：微信小游戏切后台后 director 会暂停，回来后必须靠存档恢复，而不是靠内存里的状态。检查时不要只切后台，要真的杀进程再进。

18.1.5 三端构建维度

• H5、微信小游戏、原生（Android 至少一个 ABI）三个构建各出一份产物
• H5：base 为相对路径，能部署到子目录
• 微信：appid 已填真实值，不是测试号
• 原生：appABIs 含 arm64-v8a（iOS 必须 arm64）
• 三端 md5Cache 都为 true（发布期）
• 三端 sourceMaps 都为 false（发布期）
• 构建产物按版本号归档，CDN 入口可切换（回滚 P2 的前提）

构建面板里，与上面几条对应的实际取值：

{
  "md5Cache": true,
  "sourceMaps": false,
  "mainBundleCompressionType": "merge_all_json",
  "remoteServerAddress": "https://cdn.example.com/blockdash/",
  "packageName": "com.example.blockdash"
}

mainBundleCompressionType 选 merge_all_json 是把主包内的 JSON 合并压缩，能显著减小首包——这是 NFR-03 的又一个抓手。但注意它只压主包，bundle-levels 分包要单独在分包配置里勾压缩。

18.1.6 合规与商店维度

• 隐私政策页面已接入，且首次启动能弹出（内购与埋点都涉及个人信息）
• 内购商品 ID 与商店后台一致，沙盒环境测过一笔
• 微信小游戏已通过内容审核，版本与本地一致
• 原生包已签名，Android 用正式 keystore（不要用 debug 签名）
• 应用图标、启动图、简介三处素材齐全
• 崩溃上报 SDK 已接入，且能收到测试崩溃（验证 NFR-04 的链路）

合规这条最容易被工程同学忽略，但它拦发布的能力最强。隐私政策没弹窗在多个渠道会直接导致审核不通过，和代码质量无关。把它放进清单，而不是靠记性。

18.1.7 发布流程时间线

清单不是发布当天才用的，它分布在发布前的几天里：

这张表的关键是 T-3 天冻结功能。很多团队 T-1 天还在合新代码，结果是「构建过了但没时间测」——清单上的勾是打了，但打勾的人自己都不信。

18.1.8 常见发布失败与对应检查项

下面这些是「检查清单没做，发布当场翻车」的高频场景，每条都能在清单里找到对应项：

倒数第二条要特别当心：发布不只是传产物，还要传配置。configs/levels.json 若改过，它的 manifest 版本也得跟着走，否则用户下到的还是旧配置。

18.1.9 把验收跑成脚本

1.1 的 evaluateAcceptance 在这里派上用场。发布前把实测采样写成一份 JSON，交给它判定：

// 与 1.1 的 evaluateAcceptance 配套使用（此处只示意数据形态）
export interface ReleaseSample {
  fps: number;
  firstPaintMs: number;
  firstPackageKb: number;
  crashFreeRate: number;
}

export const RELEASE_SAMPLE: ReleaseSample = {
  fps: 58,
  firstPaintMs: 1050,
  firstPackageKb: 3980,
  crashFreeRate: 0.997,
};

把这份采样喂给 evaluateAcceptance，它返回 pass: true 才算 NFR 过关。注意 firstPackageKb 的单位是 KB：3980 KB ≈ 3.9 MB，刚好压着 NFR-03 的 4096 KB 红线。单位错一个数量级，验收就会给出相反结论——这是发布脚本里最隐蔽的坑。

18.1.10 在编辑器里看什么

本节涉及项目设置，需 Cocos Creator 3.8 编辑器打开，本节不可命令行复现。

打开「项目 → 项目设置 → 项目数据」，会看到：

{
  "designResolution": {
    "width": 960,
    "height": 540,
    "fitWidth": false,
    "fitHeight": true
  },
  "orientation": { "portrait": false, "landscape": true }
}

fitWidth: false + fitHeight: true 就是 1.1.2 说的「按高度适配」，配合 Canvas 上的 SHOW_ALL 策略，在超宽屏上会留出安全区而不是拉伸变形。

另外挂一个版本信息组件，把「我发的是哪个包」变成可查的事实。这是 L2 片段，符号都核过：

import { _decorator, Component, Label, sys } from 'cc';

const { ccclass, property } = _decorator;

@ccclass('VersionInfo')
export class VersionInfo extends Component {
  @property(Label)
  label: Label | null = null;

  start(): void {
    if (!this.label) return;
    const parts = [
      `v${sys.localStorage.getItem('app:version') ?? '0.0.0'}`,
      `build ${sys.localStorage.getItem('app:build') ?? '-'}`,
      sys.platform,
    ];
    this.label.string = parts.join('  ·  ');
  }
}

sys.platform 直接显示当前平台，用户在「关于」页截图时，你一眼就知道是哪个端。发布前把 app:version 和 app:build 写进本地存储（由构建脚本注入），别硬编码——硬编码的版本号迟早和真实包不一致。

18.1.11 发布单模板

把上面的清单落成一张「发布单」，每次发布填一份，存档备查：

发布单  block-dash
──────────────────────────────
版本号      1.3.0
build 号    20261005.1
发布日期    2026-10-05
负责人      ___

FR 验收（逐条打勾，附证据）
  FR-01…FR-08  [ ]   录像/记录：___
NFR 验收（实测采样）
  NFR-01 fps          ___ fps
  NFR-02 firstPaint   ___ ms
  NFR-03 firstPackage ___ KB
  NFR-04 crashFree    ___
  NFR-05 内存峰值     ___ MB
  NFR-06 DrawCall     ___
  evaluateAcceptance  pass = ___
UC 验收
  UC-01…UC-05  [ ]   记录：___

灰度
  初始比例 5% ／ 观察 30 分钟 ／ 回滚 P0/P1/P2 已确认

归档
  H5   build/web-mobile/1.3.0/
  微信 build/wechatgame/1.3.0/
  原生 build/android/1.3.0/

「证据」那一列是发布单的灵魂。打了勾但拿不出证据的项，等于没做。 尤其 NFR 那一组，一定要写清是在哪台设备、跑了多久、什么条件下测的。

18.1.12 工程收口

到这一节，卷二的主线就走完了。工程里现在有：

• 一套完整的构建配置（三端 + 分包 + CDN）
• 一份可勾选的发布检查清单，逐条对应 FR / NFR / UC 三张表
• 一个 VersionInfo 组件，让线上问题可定位到具体包
• 一张发布单模板，把每次发布的证据固定下来

清单的价值不在「发布那天用一次」，而在把它变成每次发布的固定动作。下一节做复盘：把这 18 章里真正踩过的坑收敛成一份清单，供下一个项目直接复用。

阅读导航：上一节：目录 · 下一节：18.2 复盘：Cocos 工程里最容易踩的坑 。