拆解artcraft-android构建流水线:8个阶段与build-common.sh主编排器深度解析

原创2026-11-05 11:09:471,458 阅读

拆解artcraft-android构建流水线:8个阶段与build-common.sh主编排器深度解析

artcraft-android 是一个开源的 Android 移植构建器,它把 14 款 ArtCraft 桌面创作应用(PhotoCraft、VectorCraft、SubCraft 等)编译成本地签名的 64 位 ARM APK。整条构建流水线由 build-common.sh 这一主编排器驱动,从工具链自检、SDK 自动引导,到源码校验、启动器生成、签名打包,共划分为 8 个可观察阶段。本文用通俗的方式带你完整走完这条流水线。

artcraft-android 构建流水线生成的 Android 应用全景

一个大脑,两个入口:build.sh 与 build-debug.sh

流水线有两个极简入口脚本,它们只负责一件事——定位自身并把控制权交给主编排器:

入口脚本 作用
build.sh 构建优化后的 release APK
build-debug.sh 构建体积更大、便于排查问题的 debug APK

两个脚本的核心逻辑完全一致(见 build.sh#L3-L4):解析自身所在目录,然后 exec bash lib/build-common.sh release/debug "$@"。真正的"大脑"是长达 4150 行的 lib/build-common.sh,它按 say 1 到 say 8 打印 8 个阶段进度,每一步都可独立定位排查。

8 个阶段速览

阶段 提示语 做什么 源码位置
1 Checking build tools... 检查 git / Cargo / Python 3.11+ / cargo-ndk L197-L227
2 Finding Android SDK and NDK... 发现或自动下载 SDK、NDK、Gradle JDK L426-L457
3 Fetching official source... 克隆/复用上游客源并做完整性校验 L459-L591
4 Preparing the GameActivity launcher... 准备 Android 启动器(适配器或自动生成) L593-L829
5 Preparing a builder-owned signing key... 生成或复用本地 JKS 签名密钥 L3973-L4000
6 Building $TITLE... cargo-ndk 编译 + Gradle 打包签名 L4002-L4136
7 Verifying the Android file bridge... 验证 APK 里的启动 Activity 与原生库 L4138-L4139
8 Build succeeded. 输出 APK、体积、SHA-256 与日志 L4141-L4149

阶段 1-2:零配置引导工具链

阶段 1 会依次验证 git、Cargo、Python 3.11+(需要 tomllib 解析清单文件),并在缺少 cargo-ndk 时自动执行 cargo install cargo-ndk --locked 安装。

阶段 2 是"零配置"体验的关键:编排器会按环境变量 → 项目内 android-sdk/ → 常见系统路径的顺序寻找 Android SDK;缺失时自动从 Google 官方仓库索引解析最新版 command-line tools 下载地址并安装 platform、build-tools 与 NDK。Gradle 需要的 JDK 也走同样的策略——优先用本机 JDK 17-23,找不到就自动下载 Temurin 21 到 .cache/jdk(见 bootstrap_gradle_jdk)。这意味着一台几乎"裸机"的开发机也能直接跑通流水线。

阶段 3:源码获取与完整性校验 🛡️

这一阶段体现了流水线对"翻车场景"的深度思考:

  • 复用优先:若 source/<app>/ 已存在,则校验其 Git origin 是否匹配、工作树是否完整(source_tree_is_complete),避免覆盖你在本地做的移植修改;
  • 防断克隆:新克隆先落到临时目录 source/.clone-$APP.$$,验证 crates/ 与 apps/ 下所有被跟踪文件都在磁盘上,才允许正式落位,防止"被杀进程/磁盘写满"造成的半截克隆被后续构建误用;
  • 版本策略:默认 -stable 通过 git ls-remote 解析最新的 v* 发布 tag,也可用 -main、-tag=<tag>、-branch=<branch> 切换;
  • 上游热修复:对上游 main 上已知的编译回归,内嵌的 Python 补丁会"条件修复"——只有坏代码仍在时才动手(L545-L580)。随后由 lib/scrolling.sh(双指滚动)和 lib/subcraft.sh(SubCraft 文件投递)分别打上应用层补丁。

阶段 4:启动器准备——两种移植模型

阶段 4 决定"谁来启动这个 App",支持两种模型(详见 adapters/README.md):

  1. 定制适配器:若 adapters/<app>/prepare.sh 存在(如 adapters/photocraft/prepare.sh),直接运行它。适配器自带 Java Activity(如 PhotoCraftActivity.java)实现 SAF 文件选择等深度集成;
  2. 自动生成器:否则由 build-common.sh 内嵌的 Python 生成器扫描上游 workspace,合成 apps/<app>-android/ 启动器,并从 templates/android/ 拷入共享运行时模块(system_fonts.rs、ime_bridge.rs、saf_bridge.rs、UpdateCheck.java),再借助 lib/app_icons.py 生成分辨率分级的启动图标、用 lib/file_associations.py 写入文件关联的 intent filter。生成器带版本号标记(当前为 GENERATOR_VERSION="61"),模板升级后可自动重建旧启动器。

阶段 5-6:签名密钥与编译打包

阶段 5 在 keys/ 下用 keytool 生成 RSA-2048 JKS 密钥对(密码用 secrets 随机生成),目录权限收紧到 700/600,保证同一构建者后续版本可"覆盖安装"。

阶段 6 是火力全开的部分:

  • 先读取 workspace 的 version 作为 APK 版本号,让产物落地为 output/<app>-<version>.apk;
  • 用 cargo ndk -t arm64-v8a 把原生库编译进 jniLibs;
  • 由 lib/android_project.py 每次重新生成 AndroidManifest.xml、主题资源与 Gradle 工程(AGP 8.7.3,Gradle wrapper 来自 templates/gradle/);
  • 最后执行 ./gradlew assembleRelease(或 assembleDebug),通过 ARTCRAFT_KEYSTORE* 环境变量注入签名,并原子化地把 APK 拷贝到 output/。

阶段 7-8:产物验证与交付

"构建成功"不等于"能装能跑"。阶段 7 的 verify_android_bridge 会用 aapt2 dump badging 确认 APK 里真的存在可启动的 launcher activity,并用 Python 扫描 dex 与 .so,确保 Java SAF 桥和原生库都被打进包里——否则宁可报错也不放行。阶段 8 输出应用名、模式、APK 路径、体积、SHA-256 与日志文件位置,收尾干净利落。

让流水线更可靠的工程细节 🔧

  • 全局锁:flock 保证同一时间只有一个构建在跑,避免两个构建互相替换启动器 crate 导致"Could not determine current working directory"的诡异错误(L179-L195);
  • 失败必留名:trap ERR 会打印出错的具体行号和命令,日志永远说得清"死在哪";
  • 只加不删:所有失败路径都会明确提示"未删除任何源码与项目文件",本地移植成果受保护;
  • CI 协同:GitHub Actions 用 14 个 App 的并行矩阵 + sccache/Cargo/Gradle 三层缓存调用同一条流水线,设计细节见 docs/ci-workflow.md。

相关文件清单

文件 角色
lib/build-common.sh 主编排器(8 阶段全在此)
lib/android_project.py 生成 Manifest 与 Gradle 工程
lib/app_icons.py / lib/file_associations.py 图标与文件关联生成
lib/scrolling.sh / lib/ime.sh / lib/subcraft.sh 应用层运行时补丁
adapters/ PhotoCraft / VectorCraft / SubCraft 定制适配器
clean.sh 一键清理 source/、build/、output/、keys/ 等构建状态
architecture.md 完整架构技术参考

一句话总结:artcraft-android 的构建流水线把"装环境、拉源码、做移植、编产物、验产物"全部收敛进一个带 8 个进度阶段的主编排器,配合锁、trap 和完整性校验,让"一行 bash build.sh -photocraft"就能在裸机上得到一个可安装的 APK——这正是它最值得拆解和借鉴的地方。

登录后查看全文
artcraft-android