AIRI stage-pocket 的 Android 构建指南Capacitor 环境搭建、开发联调与图标资源再生成【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇技术指南基于 AIRI 仓库中 stage-pocket 的 Android 文档 展开覆盖 Android 端的环境前置条件SDK/Build-Tools/Java 版本、pnpm dev:android的完整开发联调链路、Capacitor 关键配置项的真实取值以及应用图标与启动屏资源的再生成方法。读完本篇你可以独立完成 AIRI 移动端stage-pocket的 Android 工程初始化、真机/模拟器运行并正确维护多分辨率的 launcher 图标与 splash 资源。一、stage-pocket 的 Android 工程定位stage-pocket 是 AIRI 的移动端应用proj-airi/stage-pocketLLM powered virtual character前端为 Vue 3 Vite 工程原生壳基于 Capacitor 生成。apps/stage-pocket/android/目录就是标准的 Gradle 工程入口清单 AndroidManifest.xml 声明了INTERNET、MODIFY_AUDIO_SETTINGS、RECORD_AUDIO三项权限usesCleartextTraffictrue用于支持开发期的明文开发服务器MainActivity.kt 继承 Capacitor 的BridgeActivity在load()中注册MicrophonePermissionPlugin、WebAuthenticationPlugin两个原生插件并通过AiriHostBridge这个 JavaScript 接口安装了一个基于 OkHttp 的 WebSocket 桥HostWebSocketBridge/OkHttpHostWebSocketSessionFactory用于把宿主的 WebSocket 能力注入 WebView开发模式下MainActivity还会安装一个DebugTlsBypassWebViewClient仅当serverUrl为 https 且证书错误的主机、端口与开发服务器完全一致时才跳过证书校验源码注释明确要求该 bypass 仅限调试且范围限定在配置的 dev server origin。从 capacitor.settings.gradle 可以看到当前工程引入的原生插件及其版本capacitor/android8.3.1、capacitor/app8.1.0、capacitor/barcode-scanner3.0.2、capacitor/local-notifications8.0.2、capacitor-native-settings8.1.0。该文件由capacitor update自动生成头部注释明确写着 DO NOT EDIT THIS FILE。二、环境前置条件官方文档列出的前置条件如下依赖要求Node.js18Android Studio需包含 JDK 与 Android SDKAndroid SDK Platform 36通过 Android Studio → SDK Manager 安装Android SDK Build-Tools通过 Android Studio → SDK Manager 安装设置以下环境变量原文示例为 Windows 路径写法Linux/macOS 请按本机 SDK 实际位置填写如ANDROID_HOME~/Android/SdkANDROID_HOMEC:/Users/you/AppData/Local/Android/Sdk JAVA_HOMEC:/Program Files/Android/Android Studio/jbr文档特别强调Gradle 需要 Java 21。Android Studio 自带的 JBRJetBrains Runtime可直接满足要求。如果没有显式设置JAVA_HOMEGradle 可能回退到系统里较旧的 Java 版本并抛出invalid source release: 21错误。这一要求与仓库中的构建链一致gradle-wrapper.properties 锁定了 Gradle 8.14.3gradle-8.14.3-all.zip而 Gradle 8.14 本身即要求 JDK 21 来运行构建。gradle.properties 中另设置了org.gradle.jvmargs-Xmx1536m与android.useAndroidXtrue。三、SDK 版本与构建参数README 声明 vs 实际构建配置文档在开头声明了 SDK 级别Min SDK: 24Android 7.0Target SDK: 36Android 16而从实际构建配置看variables.gradle.kts 中的取值是val minSdkVersion by extra(26) val compileSdkVersion by extra(36) val targetSdkVersion by extra(36)即compileSdkVersion与targetSdkVersion均为 36与文档的 Target SDK 声明一致minSdkVersion实际配置为 26Android 8.0 及以上。以当前仓库的构建文件为准最低系统支持应按 minSdk 26 理解README 中的 24 可能是历史遗留的旧值。该文件还集中管理了 Android 端的依赖版本例如okhttpVersion 4.12.0对应上文 MainActivity 使用的 OkHttp WebSocket 桥、androidxCoreVersion 1.17.0、coreSplashScreenVersion 1.2.0、junitVersion 4.13.2等便于统一升级。应用自身的版本号独立存放在 app-version.propertiesAIRI_VERSION_NAME0.12.0-beta.2 AIRI_VERSION_CODE18这与仓库根 package.json 中proj-airi/root的version: 0.12.0-beta.2保持一致说明 Android 端版本号由版本发布流程同步维护。四、开发流程从安装依赖到跑上设备首次安装依赖在仓库根目录执行根目录锁定pnpm11.24.0pnpm install的 postinstall 还会顺带构建 workspace 内部包pnpm install在设备 / 模拟器上运行先把工程在 Android Studio 中打开然后用文档给出的两种等价方式指定目标设备pnpm dev:android -- target CAPACITOR_DEVICE_ID # 或者 CAPACITOR_DEVICE_ID_ANDROIDCAPACITOR_DEVICE_ID pnpm dev:android两种写法背后的机制可以在 stage-pocket 的 package.json 和 monorepo 内的cap-vite工具包中印证dev:android脚本实际是cap-vite -- android由 workspace 包 cap-vite 驱动 Vite dev server 与 Capacitor 的联调resolveCapRunArgs的逻辑是如果参数里没有显式--target则读取环境变量CAPACITOR_DEVICE_ID_ANDROID作为目标仍没有时执行cap run android --list --json取第一个可用设备/模拟器两者都拿不到会抛出明确错误提示连接设备、启动模拟器或显式传--target。这与 README 给出的两种用法一一对应从仓库根目录也可以用 package.json 中定义的聚合脚本pnpm dev:pocket:android启动它等价于pnpm -rF proj-airi/stage-pocket run dev:android。开发服务器与产物同步capacitor.config.ts 揭示了联调期的关键行为const serverURL env.CAPACITOR_DEV_SERVER_URL const appId argv.includes(android) ? ai.moeru.airi_pocket : ai.moeru.airi-pocket const config: CapacitorConfig { appId, appName: AIRI, webDir: dist, server: serverURL ? { url: serverURL, cleartext: false } : undefined, android: { buildOptions: { keystorePath: env.CAPACITOR_ANDROID_KEYSTORE_PATH, keystoreAlias: env.CAPACITOR_ANDROID_KEYSTORE_ALIAS, keystorePassword: env.CAPACITOR_ANDROID_KEYSTORE_PASSWORD, keystoreAliasPassword: env.CAPACITOR_ANDROID_KEYSTORE_ALIAS_PASSWORD, releaseType: APK, signingType: apksigner, }, }, }要点appId 按平台区分Android 端为ai.moeru.airi_pocket注意 Android 应用 id 不能包含连字符所以用了下划线。Manifest 中的自定义深链 scheme 是ai.moeru.airi-pockethost 为links见 AndroidManifest.xmlwebDir: distcap sync会把 Vite 构建产物同步到原生工程CAPACITOR_DEV_SERVER_URL设置后WebView 会加载该外部开发服务器地址cleartext: false这正是 MainActivity 中 Debug TLS bypass 生效的场景Release 签名通过四个环境变量keystore 路径、别名、两个密码注入产出releaseType: APK、signingType: apksigner的签名包。五、更新应用图标与启动屏Splash文档说明源素材存放在../resources/即apps/stage-pocket/resources/相对于android/目录。需要说明的是当前仓库快照中未见该目录它属于需要按文档约定在本地准备的设计素材目录文件用途icon-only.png应用图标1024×1024无背景icon-foreground.png自适应图标Adaptive Icon前景层1024×1024splash.png启动屏2732×2732图标背景色为白色#FFFFFF定义在 ic_launcher_background.xmlresources color nameic_launcher_background#FFFFFF/color /resources更新源素材后在apps/stage-pocket/下执行以下命令重新生成全部 Android 尺寸# from apps/stage-pocket/ npx capacitor/assets3.0.5 generate --android \ --iconBackgroundColor #FFFFFF \ --iconBackgroundColorDark #000000 \ --splashBackgroundColor #FFFFFF \ --splashBackgroundColorDark #000000该命令会覆盖app/src/main/res/mipmap-*/与app/src/main/res/drawable-*/下的所有文件。仓库现状与之一致mipmap-ldpi到mipmap-xxxhdpi各密度下各有ic_launcher.png、ic_launcher_round.png、ic_launcher_foreground.pngdrawable-*目录下则按横竖屏 × 密度组合存放多份splash.png例如drawable-port-xxxhdpi/splash.png为 1280×1920、drawable-land-xxxhdpi/splash.png为 1920×1280。必须验证的已知坑点执行完工具后要检查 mipmap-anydpi-v26/ic_launcher.xml 和同目录的ic_launcher_round.xml是否仍然引用color/ic_launcher_background而不是mipmap/ic_launcher_backgroundadaptive-icon xmlns:androidhttp://schemas.android.com/apk/res/android background android:drawablecolor/ic_launcher_background/ foreground android:drawablemipmap/ic_launcher_foreground/ /adaptive-icon工具有时会把背景引用写成错误的mipmap/...形式导致编译期找不到资源此时用git checkout恢复这两个文件即可。六、生成物、Git 忽略项与 Gradle 陷阱文档 Notes 部分列出的三条注意事项都是实际维护 Android 壳工程时的高频坑app/src/main/assets/public/与app/src/main/assets/capacitor.config.json由cap sync生成已被 gitignore——不要手工编辑改动应落在 Vite 工程侧后重新 synclocal.propertiesSDK 路径是机器相关的已被 gitignore——每台开发机首次打开工程时由本机ANDROID_HOME生成不要把org.gradle.java.home加进 gradle.properties——Android Studio 有时会替你在其中写入该配置通常指向某个 IDE 内置 JDK。若被自动添加应删除坚持用环境变量JAVA_HOME控制 Gradle 使用的 Java 21这正是第二节中invalid source release: 21错误的根治方式。另外从 settings.gradle.kts 可见工程结构除:app外还包含:capacitor-cordova-android-plugins并在末尾apply(from capacitor.settings.gradle)挂入 Capacitor 生成的原生模块。七、小结事项关键信息前置Node 18、Android Studio含 JBR 21、SDK Platform 36、Build-Tools设置ANDROID_HOME与JAVA_HOME版本compileSdk/targetSdk 36minSdk 构建配置为 26应用版本 0.12.0-beta.2versionCode 18联调pnpm install后pnpm dev:android -- target ID或CAPACITOR_DEVICE_ID_ANDROIDID pnpm dev:android配置webDir: distCAPACITOR_DEV_SERVER_URL指定 dev serverrelease 签名走CAPACITOR_ANDROID_KEYSTORE_*环境变量APK apksigner资源源素材 1024×1024 图标 / 2732×2732 启动屏npx capacitor/assets3.0.5 generate --android全量再生成注意校验mipmap-anydpi-v26的背景色引用禁忌不编辑capacitor.settings.gradle不提交assets/public/、capacitor.config.json、local.propertiesgradle.properties中不放org.gradle.java.home以上流程均基于当前仓库apps/stage-pocket/android/的实际文件状态整理可对照 README、variables.gradle.kts、capacitor.config.ts 与 MainActivity.kt 继续深入。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考