webgame-apk-release

> Web 游戏 → Android 签名 APK → 可上架交付物。一套流程跑完，出包即验、验完即交。

TL;DR（5 步）

体检 → tsc → 静态导出 → cap sync → gradle assembleRelease → 双校验 → 交付

出包前必答 3 件事：游戏名 / 版本号 / 是否覆盖同名旧包。

Phase 0 · 体检（不做完别往下走）

逐项确认，缺哪项先补哪项：

🛑 STOP · 版本确认：向用户确认 versionName（如 1.2）与 versionCode（必须比上一版大），以及是否删除被取代的旧 APK。
> 版本口径：对外 versionName 以用户口径为准——内部迭代号 ≠ 商店版本号（内部改了 5 版，首发对外仍常为 1.0）；同步更新应用内版本常量（如 src/lib/version.ts），游戏内显示与商店必须一致。

🔴 CHECKPOINT：展示体检结果 + 版本方案，拿到确认再进入 Phase 1。

Phase 1 · 构建

# 1) 类型检查（Next 项目若忽略构建期错误，这一步是唯一防线）
npx tsc --noEmit

# 2) 静态导出（Next → out/；Vite → dist/）
npm run build

# 3) 同步到 Android 工程
export JAVA_HOME="<Temurin JDK 21 路径>"
npx cap sync android

> 体积检查：du -sh out/。若发现素材源目录（原图/拼版预览/PSD 之类）混进了 public/，加一个构建后清理脚本挂到 build（例："build": "next build && node scripts/trim-out.mjs"），它们只服务于生成管线、运行时用不到。

Phase 2 · 签名（首次打包该游戏时）

# 生成独立密钥（每个游戏一把，切勿复用）
keytool -genkeypair -v -keystore android/keystore/<game>-keystore.jks \
  -alias <game> -keyalg RSA -keysize 2048 -validity 10950 \
  -storepass '<口令>' -keypass '<口令>' \
  -dname "CN=<game>, OU=Game, O=<studio>, L=Beijing, ST=Beijing, C=CN"

# android/keystore.properties（加入 .gitignore，密钥与口令都不过库）
storeFile=../keystore/<game>-keystore.jks
storePassword=<口令>
keyAlias=<game>
keyPassword=<口令>

android/app/build.gradle 挂签名：

def keystorePropsFile = rootProject.file('keystore.properties')
def keystoreProps = new Properties()
if (keystorePropsFile.exists()) keystoreProps.load(new FileInputStream(keystorePropsFile))

android {
  signingConfigs {
    release {
      if (keystorePropsFile.exists()) {
        storeFile rootProject.file(keystoreProps['storeFile'])
        storePassword keystoreProps['storePassword']
        keyAlias keystoreProps['keyAlias']
        keyPassword keystoreProps['keyPassword']
      }
    }
  }
  buildTypes {
    release {
      minifyEnabled false
      proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
      if (keystorePropsFile.exists()) signingConfig signingConfigs.release
    }
  }
}

⚠️ 交付时必须提醒用户备份 .jks 与口令：密钥丢失 = 该游戏永远无法再出覆盖更新包。

Phase 3 · 打包

cd android
export JAVA_HOME="<Temurin JDK 21 路径>"        # 不要用 Android Studio 自带 JBR
export GRADLE_USER_HOME="<Windows 风格路径>"      # 例：C:/Users/<你>/.gradle

# Windows
./gradlew.bat assembleRelease --console=plain -q
# macOS / Linux
./gradlew assembleRelease --console=plain -q

产物：android/app/build/outputs/apk/release/app-release.apk

Phase 4 · 双校验（任一不通过 → 回退，禁止交付）

BT=$(ls -d <SDK>/build-tools/* | sort -V | tail -1)   # 取最高版本 build-tools

# ① 身份校验：包名 / versionCode / versionName
"$BT/aapt2" dump badging app-release.apk | head -1

# ② 签名校验：必须出现 V2 Signer，证书 DN 与自家 keystore 一致
"$BT/apksigner" verify --print-certs app-release.apk | head -3

Phase 5 · 交付

1. 复制 APK 到工作区根目录，命名 《游戏名-vX.Y-release.apk》
2. 删除被取代的旧包（删除前须用户确认）
3. 更新日志写进项目 docs/（并在回复里给用户一份可直接粘贴的纯文本版）
4. 汇报：体积、包名、版本、签名指纹、APK 的 SHA-256

失败模式表（三段式 · 现象 → 原因 → 修复）

反例黑名单（违反即返工）

1. 禁止用 Android Studio 的 JBR 当 JAVA_HOME 打包——只用 Temurin JDK 21。
2. 禁止在没有 capacitor.config.ts 的情况下 cap add android——会生成默认包名模板，后续 sync 救不回来。
3. 禁止复用或覆盖其它游戏的 keystore、禁止把口令写进任何会被提交的文件（含本 skill）。
4. 禁止跳过 Phase 4 双校验就交付；禁止未确认就删除旧 APK、未确认就改 versionCode。
5. 禁止把工作区绝对路径写死进流程——路径按参数取，示例值仅作参考。

边界（不在本 skill 范围）

• 应用商店平台侧操作（创建游戏、包体库、提审、测试计划、素材/资质）→ 用对应的平台 skill（如 taptap-publish-game、taptap-package-management）
• 提审/资质确认等后台操作也可由用户自行在开发者后台完成（网页表单部分 CLI 无法代填）；是否由 AI 代跑平台流程以用户意愿为准
• iOS 打包、原生引擎（Unity/Unreal/Cocos）出包
• 游戏玩法代码编写与美术资产生成