63 lines
6.4 KiB
Markdown
63 lines
6.4 KiB
Markdown
# Android 环境、构建与交付
|
||
|
||
## 安装门槛
|
||
|
||
Android Studio 是正常安装软件，由用户运行已核验官方安装包。安装包放用户普通下载目录，不放仓库或 Codex bin。准备好后停止等待用户安装，不自动运行安装器。安装时建议采用默认位置，首次向导安装 Android SDK；不必创建项目，也不必先下载模拟器或 NDK。
|
||
|
||
首次完成后记录实际安装版本、JDK、SDK、Build Tools、Kotlin、Compose、AGP 与 Gradle 的兼容组合，锁入版本目录、Wrapper 和依赖校验文件。安装位置用环境探测／local.properties，不写到可提交源码。官方参考：
|
||
|
||
- https://developer.android.com/studio
|
||
- https://developer.android.com/studio/install
|
||
- https://developer.android.com/kotlin/multiplatform/plugin
|
||
- https://kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html
|
||
|
||
## 工程与路径
|
||
|
||
源码位于相邻 `安卓程序源代码/`，模块 androidApp、sharedCore、sharedUi。在 Android Studio 打开工程根，不分别打开子模块。先验证中文和空格路径；若 Android 工具拒绝该路径，通过受保护的仓库外 ASCII 构建目录同步源码并执行，结果回收到交付目录。同步只包含源码及明确资源，不复制私有登记、密钥、缓存或 `.git`；脚本记录源摘要，不覆盖用户目录。
|
||
|
||
已安装工具链：Android Studio Quail 4 Patch 1（用户确认中文）、JBR 25.0.3、SDK 37；工程固定 Gradle 9.5.0、AGP 9.3.1、Kotlin 2.4.20、Compose 1.12.1。Wrapper 使用官方发行地址和 SHA-256。首次 `:androidApp:assembleDebug` 与 `:sharedCore:jvmTest` 已在隔离 ASCII 路径通过；这只是骨架及协议验证，不等于功能验收。lint 与真实 BLE 已有通过记录，具体覆盖范围见测试结果归档。
|
||
|
||
在仓库根执行下列命令，参数替换为本机实际目录，不把替换后的路径提交：
|
||
|
||
```text
|
||
python "移动端相关内容/安卓app/构建与发布/build_android.py" --work-root "<受保护临时目录的ASCII路径>" --jdk "<Android Studio的jbr目录>" --sdk "<Android SDK目录>"
|
||
```
|
||
|
||
脚本每次创建独立 `qms-build-*` 子目录，只复制工程源码，忽略 build、.gradle、.kotlin、local.properties。默认使用 Wrapper；可用 `--gradle` 指定已核验的同版本 Gradle，避免重复下载。默认运行 JVM 测试和 assembleDebug，可在末尾显式传任务列表。保留构建目录用于查看测试报告和 `androidApp/build/outputs/apk/debug/androidApp-debug.apk`；验证后只清理本次明确目录。Android 调试签名沿用用户默认 Android 密钥目录，不复制到源码或隔离工程。
|
||
|
||
路径实测：AGP 默认拒绝非 ASCII 路径；启用 `android.overridePathCheck=true` 后编译继续，但当前 JBR／Gradle 下 JVM 测试出现类加载失败。在 ASCII 隔离目录同一测试通过，故当前使用该回退。2026-09-25 已在全新且包含空格的 ASCII 构建根目录重新执行全部 92 个任务，JVM 测试及两个 debug APK 均成功；保留中文源码位置。
|
||
|
||
## APK 与签名
|
||
|
||
- 应用名“奇妙小屏幕”，applicationId 为 `org.qimiaoscreen.controller`，minSdk 26，首版版本 0.1.0。
|
||
- 仅 debug 签名，沿用本机调试密钥并记录证书摘要（不记录私钥）。正式签名只有用户明确命令才配置或执行。
|
||
- 调试签名更换可能无法覆盖安装；不能自动卸载并清除用户配置来掩盖。需要时先报告原因。
|
||
- App versionCode 独立递增，设备版本／协议版本分别登记，不能因设备部署自动提升 App 版本。
|
||
- 每次交付放 `交付包/<App版本>-<versionCode>/`：APK、SHA256SUMS、manifest.json、README.md。manifest 包含 App／协议／兼容设备信息、源摘要、工具链版本和签名证书摘要，不包含本机路径或测试机标识。
|
||
- APK 与发布元数据保留在私有 Git 仓库，需要时沿用 Git LFS；构建缓存、SDK、真实登记、调试及正式签名私钥都不提交。
|
||
- 本任务不导出核桃派 IMG／OTA；设备功能时间按根规则更新，设备发布版本不因普通部署占号。
|
||
|
||
## 交付前检查
|
||
|
||
从隔离目录依文档重新构建并验证；完成相关测试、协议互操作和真实 BLE 联调；运行根仓库卫生检查。交付说明准确区分通过、未验证和不适用。第二台手机验收 APK 放到同一清晰可找到的交付目录，用户安装后再进行实机互斥测试。
|
||
|
||
## 可重复打包
|
||
|
||
```text
|
||
python "移动端相关内容/安卓app/构建与发布/package_debug.py" --build "<本轮隔离工程目录>" --sdk "<Android SDK目录>"
|
||
```
|
||
|
||
运行前将 JAVA_HOME 指向正常安装的 Android Studio jbr。脚本逐文件核对隔离工程与当前源码的 SHA-256，调用 Build Tools 36.0.0 的 apksigner 验证 Android Debug 证书，创建版本独立目录，保存 APK、摘要、工具链和源文件清单。已存在交付目录拒绝覆盖。结果默认标为开发验证包，必须结合测试报告说明验收范围，不用打包成功替代验收。versionCode 2 包含本轮连接清理和界面信息补充，可覆盖同证书的 code 1。
|
||
|
||
本轮 App 0.2.0 / versionCode 3 为四栏界面及设备记忆优化，仍仅 debug 签名。关于页显示本次 Gradle 构建日期（北京时间），不修改设备发布版本。
|
||
|
||
## 构建排障与测试复盘
|
||
|
||
手动调用隔离工程 Wrapper 时，每个新 shell 都须明确使用已登记的 JDK/SDK（JAVA_HOME/ANDROID_HOME）；前一工具调用的进程环境不会自动传到下一次调用。缺少 SDK location 时先检查环境，不重复下载工具、不改动中文源码位置。
|
||
|
||
Gradle Kotlin DSL 里 `java` 可能被插件扩展名遮蔽；构建日期实现显式 import `ZonedDateTime`、`ZoneId`、`DateTimeFormatter`，避免直接以 `java.time...` 引用引发解析错误。日期仍使用北京时间，不通过硬编码本机路径解决。
|
||
|
||
Python 在 Windows 缺少 IANA tzdata 时，固定北京时间时间戳可使用标准库 `timezone(timedelta(hours=8))`；这一方法只适用于明确要求的固定 UTC+08:00 时间，不当作任意地区夏令时转换方案，也不因该情况自动新增依赖。
|
||
|
||
打包前重新核对隔离源码、实际 APK、构建日期和签名摘要；测试源码调整也要同步隔离工程，不能测试旧测试 APK。测试/构建遇到的新问题在完成后更新相应文档并在最终反馈说明，具体输入和真机排障见 [测试排障指南](../如何安卓测试/常见问题与排障.md)。
|