本文覆盖 gomobile AAR、Android APK/AAB 构建与签名、MuMu 冒烟测试、AAR 校验与常见问题。 平台支持与功能边界见 Platform.md。
| 产物 | 命令 | 说明 |
|---|---|---|
| Debug APK(arm64-v8a) | .\gradlew.bat :app:assembleDebug |
本地开发 / 真机,默认只打 arm64 |
| Debug APK(x86_64) | .\gradlew.bat :app:assembleDebug -PdebugAbi=x86_64 |
MuMu 等 x86_64 模拟器 |
| Release APK + AAB(已签名) | pwsh -File scripts/build-apk.ps1 -Bundle |
校验签名并输出到 build/dist/ |
| Release APK(全 ABI,手动) | .\gradlew.bat :app:assembleRelease |
arm64-v8a / armeabi-v7a / x86_64 |
| Release AAB | .\gradlew.bat :app:bundleRelease |
应用商店分发 |
| gomobile AAR | pwsh -File scripts/build-aar.ps1 |
输出 app/libs/snishaper-core.aar(不入库) |
| 签名状态 | .\gradlew.bat :app:signingInfo |
打印解析到的密钥库 / 别名,或提示缺失 |
产物路径:app/build/outputs/apk/{debug,release}/、app/build/outputs/bundle/release/;
scripts/build-apk.ps1 另外复制一份到 build/dist/ 并生成 SHA256SUMS.txt。
| 组件 | 版本 |
|---|---|
| JDK | 25(Android Studio jbr 或 Temurin 25) |
| Gradle | 9.8.2(wrapper,默认华为云镜像) |
| Android Gradle Plugin | 9.5.0-rc01(AGP 9 内置 Kotlin,不要应用 org.jetbrains.kotlin.android) |
| Android SDK | compileSdk 37(minor 2)、build-tools 37.0.0、targetSdk 36 |
| Android NDK | 30.0.16248370(gomobile cgo 交叉编译) |
| Go | 1.27 |
| gomobile | golang.org/x/mobile v0.0.0-20260803200217-62cee1672c8e |
| 核心库 | snishaper-core v0.8.4 |
$env:JAVA_HOME = "D:\Jetbrains IDES\Android Studio\jbr"
$env:ANDROID_HOME = "D:\AndroidSDKs"
$env:ANDROID_NDK_HOME = "D:\AndroidSDKs\ndk\30.0.16248370" # 必须指向实际安装的 NDK
$env:GOPROXY = "https://goproxy.cn,direct"
$env:GOSUMDB = "off"也可以直接 dot-source 环境脚本,其中同时打印版本矩阵:
. .\scripts\dev-env.ps1pwsh -File scripts/build-aar.ps1脚本行为:
- 校验
go/gomobile/ NDK / JDK; - 检查
gomobile/mobile的依赖闭包中包含certmanager(CA 支持校验:缺失则说明 CA 功能被误删); - 执行
gomobile bind(arm64-v8a + armeabi-v7a + x86_64,-androidapi 24、-tags with_gvisor、-trimpath -ldflags "-s -w"); - 输出体积 / sha256 摘要到控制台。
等价的单条命令:
cd gomobile
gomobile bind -target=android/arm64,android/arm,android/amd64 `
-androidapi 24 -tags with_gvisor -trimpath -ldflags "-s -w" `
-javapkg com.snishaper.core -o ../app/libs/snishaper-core.aar ./mobileAAR 约 74.7 MB(stripped,三 ABI),属于构建产物,不提交 Git;CI 会重新构建并作为 artifact 上传。
pwsh -File scripts/init-keystore.ps1脚本生成两样东西,都被 .gitignore 忽略:
| 文件 | 内容 |
|---|---|
keystore/release.jks |
PKCS12 密钥库,RSA 4096,有效期 30 年,别名 snishaper |
keystore.properties |
storeFile / storePassword / keyAlias / keyPassword |
控制台会打印随机生成的密码与证书 SHA-256。这两个文件必须离线备份:Android 只允许签名一致的 APK 覆盖安装,密钥丢失后已发布版本将无法升级。
pwsh -File scripts/build-apk.ps1 # signed release APK
pwsh -File scripts/build-apk.ps1 -Bundle # + AAB脚本依次执行:补齐缺失的 AAR → 补齐缺失的前端 bundle → assembleRelease(可选 bundleRelease)→
apksigner verify(未签名直接失败)→ 复制到 build/dist/snishaper-droid-<version>.{apk,aab} → 写 SHA256SUMS.txt。
也可以直接调用 Gradle(keystore.properties 存在时自动签名):
.\gradlew.bat :app:assembleRelease
.\gradlew.bat :app:bundleRelease
.\gradlew.bat :app:signingInfo # 确认签名配置已被读取app/build.gradle.kts 的 release 签名配置固定启用 v2 + v3 + v4:
| 方案 | 状态 | 原因 |
|---|---|---|
| v1(JAR) | 关闭 | minSdk 24 起系统只认 v2+,v1 徒增体积 |
| v2 | 启用 | Android 7.0+ 主流校验 |
| v3 | 启用 | 支持密钥轮换 |
| v4 | 启用 | 生成 .idsig,增量安装用 |
| 顺序 | 来源 | 用法 |
|---|---|---|
| 1 | keystore.properties(仓库根目录) |
本地开发 |
| 2 | 环境变量 SNISHAPER_KEYSTORE / SNISHAPER_KEYSTORE_PASSWORD / SNISHAPER_KEY_ALIAS / SNISHAPER_KEY_PASSWORD |
CI / 无仓库文件场景 |
| 3 | 都没有 | release 产出 app-release-unsigned.apk,build-apk.ps1 会直接报错退出 |
SNISHAPER_KEYSTORE 支持绝对路径或相对仓库根目录的路径。
GitHub Release 工作流从仓库 Secrets 读取:
| Secret | 内容 |
|---|---|
ANDROID_KEYSTORE_BASE64 |
base64 -w0 keystore/release.jks(PowerShell:[Convert]::ToBase64String([IO.File]::ReadAllBytes("keystore/release.jks"))) |
ANDROID_KEYSTORE_PASSWORD |
storePassword |
ANDROID_KEY_ALIAS |
keyAlias |
ANDROID_KEY_PASSWORD |
keyPassword |
四个都齐全时流水线导入密钥并签名,再用 apksigner verify 把关;缺任意一个会打印 ::warning:: 并产出未签名包(发版前务必确认日志中已出现签名校验通过)。
# 1) 确认设备在线(MuMu 需开启 ADB 调试)
adb devices
# 空列表时:启动 MuMu,然后
adb connect 127.0.0.1:16384
# 2) 安装
adb install -r app/build/outputs/apk/debug/app-debug.apk
# 3) 启动
adb shell am start -n com.snishaper.android/.MainActivity
# 4) 日志(无 FATAL EXCEPTION 即通过启动检查)
adb logcat -s Snishaper:* AndroidRuntime:E一键脚本(MuMu 离线时明确提示并 exit 2,不伪造结果):
pwsh -File scripts/mumu-status.ps1
pwsh -File scripts/smoke-test.ps1人工检查项:
- App 启动无崩溃 / 无
FATAL EXCEPTION - Dashboard 可启动 / 停止代理引擎,TUN 可拉起系统 VPN 授权,CA 状态卡正常显示
- 顶部 ☰ 可开关侧边栏,11 项顺序与桌面一致
- 实时连接、配置档案、规则解释、多 CDN 优选池、诊断包可用
- 设置页只有端口、语言、外观、主题、自动更新规则、TUN MTU、证书、IPv6、CF IP 池
- 规则编辑支持 mitm / tls-rf / quic / transparent / migration 全部模式
- 日志页常驻显示引擎环形缓冲,暂停 / 清空 / 导出可用
python3 scripts/verify_aar.py
cd gomobile
go list -deps ./mobile | Select-String certmanager # 应有输出(CA 支持已在依赖图中)校验内容:AAR 存在 / minSdkVersion=24 / 三个 ABI / arm64 与 x86_64 的 16 KB 页对齐 / classes.jar 仅含 App、Listener 与 gobind 运行时类 / 无证书文件内嵌。
| Workflow | 触发 | 内容 |
|---|---|---|
.github/workflows/android.yml |
push / PR / 手动 | JDK + Android SDK + NDK + Go + gcc → gomobile AAR → verify_aar → lint test assembleDebug → APK/AAR artifacts |
.github/workflows/release.yml |
手动 dispatch(确认版本 + 渠道,bot 提交版本号并打 tag) | 导入签名密钥 → signingInfo lint test assembleRelease bundleRelease → apksigner verify → 发布 GitHub Release(签名 APK + AAB + AAR + SHA256SUMS.txt) |
| 现象 | 原因与处理 |
|---|---|
gomobile bind 报 ANDROID_NDK_HOME 相关错误 |
环境变量指向不存在的 NDK 版本;改为实际安装版本(如 30.0.16248370) |
sum.golang.org 超时 / 模块校验失败 |
设置 GOPROXY=https://goproxy.cn,direct 与 GOSUMDB=off |
编译报找不到 com.snishaper.core.mobile.* |
AAR 尚未生成或 app/libs/snishaper-core.aar 缺失;先执行 scripts/build-aar.ps1 |
release 产出 app-release-unsigned.apk |
没有读到签名材料;.\gradlew.bat :app:signingInfo 查看缺失项,执行 scripts/init-keystore.ps1 |
apksigner 报 DOES NOT VERIFY |
密钥库与旧包不一致(换过密钥);卸载旧版后重装,或恢复原 keystore/release.jks |
应用 org.jetbrains.kotlin.android 时报 “no longer required since AGP 9.0” |
AGP 9 已内置 Kotlin,删除该插件(本仓库已处理) |
| Gradle 下载慢 / 超时 | 仓库默认使用华为云 Maven 镜像;如镜像不可用可临时切回官方源 |
MuMu adb devices 为空 |
在 MuMu 设置中开启 ADB 调试,或 adb connect 127.0.0.1:16384 |
| Release 包体积大 | 三个 ABI 的 .so 未压缩存放(16 KB 对齐要求)属预期;分发用 AAB 或按 ABI 拆分 |