GitHub项目如何打包成TV端可安装的APK/IPK/TAR包？

Question

常见技术问题： GitHub开源项目（如基于React Native、Flutter或原生Android的TV应用）在打包为TV端可安装包时，常因未适配TV特性而失败。典型问题包括：未声明``导致Google Play拒绝TV设备安装；缺少TV专属启动Activity（`CATEGORY_LEANBACK_LAUNCHER`）或焦点导航逻辑，使遥控器无法操作；资源目录未提供`res/values-v17/`等TV适配配置；构建时未指定`targetSdkVersion` ≥ 26（Android TV最低要求）；或混淆规则未排除TV相关类引发运行时异常。此外，Tizen平台需生成IPK（依赖`sdb package`和`.tizen-metadata`），WebOS则需打包为`.ipk`（通过`ares-package`）或`.tar.gz`（含`appinfo.json`及签名证书）。缺乏统一CI/CD脚本自动化多平台构建，亦是团队高频痛点。

Answer 1

```html

一、常见技术问题：TV端多平台打包失败的表层现象

• Google Play Console 拒绝上架：因 <uses-feature android:name="android.hardware.touchscreen" android:required="false"/> 缺失，系统默认要求触摸屏，导致TV设备被过滤；
• 启动黑屏或闪退：未配置 CATEGORY_LEANBACK_LAUNCHER 的 Activity，Android TV Launcher 无法识别主入口；
• 遥控器焦点失灵：未在 AndroidManifest.xml 中为关键控件添加 android:focusable="true" 及 android:nextFocusDown/Up/Left/Right 属性；
• Tizen 构建中断：sdb package 报错 "Missing .tizen-metadata or malformed config"，因未生成元数据文件或 config.xml 缺少 <tizen:application> 声明；
• WebOS 安装失败：使用 ares-package 打包时提示 "appinfo.json not found" 或签名证书未绑定到 cert-profiles。

二、深度归因分析：从构建链路到运行时行为的全栈诊断

TV适配失败本质是「平台语义鸿沟」——移动优先框架（React Native/Flutter）默认屏蔽TV交互范式。以下为典型根因分层模型：

graph TD
  A[源码层] -->|Flutter/RN组件未重写onKeyDown| B(焦点事件丢失)
  A -->|未条件编译TV资源| C(res/values-v17/缺失)
  B --> D[构建层]
  C --> D
  D -->|AGP未启用tv-support| E(targetSdkVersion < 26)
  D -->|R8混淆未保留Leanback类| F(NoSuchMethodError on LeanbackFragment)
  E --> G[分发层]
  F --> G
  G -->|Play Store Filter Engine| H(TV设备不可见)

三、跨平台标准化解决方案矩阵

平台	核心构建命令	必备元文件	关键Manifest/Config声明
Android TV	./gradlew assembleRelease -PtargetSdkVersion=34	res/values-v17/bools.xml, res/drawable-hdpi-tv/	<activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LEANBACK_LAUNCHER"/></intent-filter></activity>
Tizen	sdb package -t wgt app.wgt	.tizen-metadata, config.xml	<tizen:application id="org.example.tvapp" package="org.example" version="1.0.0"><tizen:profile name="tv-samsung"/></tizen:application>
webOS	ares-package ./ 或 tar -czf app.tar.gz appinfo.json icon.png index.html	appinfo.json, signature.pub	{"id":"com.example.tv","version":"1.0.0","vendor":"Example Inc","type":"web","main":"index.html","title":"TV App"}

四、CI/CD 自动化实践：统一多平台构建流水线

以下为 GitHub Actions 中支持 Android TV / Tizen / webOS 的复合构建脚本核心逻辑（YAML 片段）：

jobs:
  build-all-platforms:
    strategy:
      matrix:
        platform: [android-tv, tizen, webos]
    steps:
      - uses: actions/checkout@v4
      - name: Setup JDK & SDK
        uses: actions/setup-java@v3
        with:
          java-version: '17'
      - name: Build ${{ matrix.platform }}
        run: |
          case "${{ matrix.platform }}" in
            "android-tv")
              echo "Building Android TV APK..."
              ./gradlew assembleRelease -Pandroid.useAndroidX=true
              ;;
            "tizen")
              echo "Packaging Tizen IPK..."
              sdb connect $TIZEN_DEVICE
              sdb shell "mkdir -p /opt/usr/apps/org.example.tv"
              sdb push ./build/tizen/ org.example.tv/
              sdb package -t ipk ./build/tizen/
              ;;
            "webos")
              echo "Creating webOS package..."
              ares-package --sign default ./src/webos/
              ;;
          esac

五、高阶避坑指南：面向5年+工程师的架构级建议

• 抽象交互层：在 Flutter 中封装 TVFocusManager，监听 RawKeyboard.instance.addListener 替代手势事件；
• 资源条件编译：Android 项目中用 sourceSets 分离 tvDebug/tvRelease 构建变体，隔离 Leanback 依赖；
• 签名治理：建立 keystore-secrets Vault，对 Tizen author-signature.pem 和 webOS cert-profiles 进行密钥生命周期管理；
• 自动化兼容性验证：集成 adb shell am start -a android.intent.action.MAIN -c android.intent.category.LEANBACK_LAUNCHER -n com.example/.MainActivity 到测试阶段；
• Play Store 元数据校验：在 CI 中调用 bundletool dump manifest --bundle=app.aab | grep -E "(LEANBACK_LAUNCHER|touchscreen.*false)" 实现门禁检查。

```