Docker Android Build Box

![docker icon]([] ![Docker Image CI]([]

概述

一个优化的Docker镜像，包含Android SDK和Flutter SDK，旨在为Android和Flutter项目提供完整的构建环境。

核心功能与组件

包含的软件组件

latest镜像始终安装最新软件，包括最近8个Android SDK平台及其关联构建工具。Dockerhub描述（点击上方Docker徽章可访问）提供latest镜像中已安装软件的实时列表。有关标记版本和latest镜像中安装的各种软件详情，请参见矩阵文件。

最新标记版本包含以下组件：

• Ubuntu 22.04
• Java - OpenJDK
  • 8 (1.8)
  • 11
  • 17
  • 21
• Android SDK平台：
  • 28、29、30、31、32、33、34、35
• Android构建工具：
  • 28.0.1 28.0.2 28.0.3
  • 29.0.2 29.0.3
  • 30.0.0 30.0.2 30.0.3
  • 31.0.0
  • 32.0.0
  • 33.0.0 33.0.1 33.0.2 33.0.3
  • 34.0.0
  • 35.0.0
• Android NDK - r28b
• Android bundletool
• Android模拟器
• cmake
• TestNG
• Python 3.8.10
• Node.js 22、npm、React Native
• Ruby、RubyGems
• fastlane
• Flutter 3.32.4
• jEnv（Java版本管理工具）

拉取Docker镜像

该Docker镜像基于本仓库的Dockerfile通过Github Action自动公开构建，无隐藏内容。

拉取最新镜像：

sh
docker pull mingc/android-build-box:latest

提示：建议使用特定稳定版本的标签而非latest，以避免构建中断。例如mingc/android-build-box:1.25.0。

查看标签列表获取所有可用标签，变更日志了解标签间差异，兼容性矩阵查看各标签对应的软件版本（如标签1.2.0包含SDK x、y、z等）。

使用方法

使用镜像构建Android项目

缓存使用方法请参见缓存部分。

通过以下命令使用该镜像构建Android项目：

sh
cd <android项目目录>  # 切换到项目根目录
docker run --rm -v `pwd`:/project mingc/android-build-box bash -c 'cd /project; ./gradlew build'

构建.aab格式发布包：

sh
cd <android项目目录>  # 切换到项目根目录
docker run --rm -v `pwd`:/project mingc/android-build-box bash -c 'cd /project; ./gradlew bundleRelease'

以交互式bash shell运行容器：

sh
docker run -v `pwd`:/project -it mingc/android-build-box bash -l

缓存配置

缓存不会减少总磁盘空间需求，反而可能增加（例如Android SDK缓存可能使空间翻倍）。需注意镜像本身约占16.2GB，缓存可能额外占用6GB。

jEnv缓存

为缓存全局Java设置（/root/.jenv/version），需缓存整个jEnv文件夹/root/.jenv/：

1. 在主机创建缓存目录：

   sh
   mkdir ~/.dockercache/jenv
   

2. 创建命名卷jenv-cache：

   sh
   docker volume create --driver local --opt type=none --opt device=~/.dockercache/jenv/ --opt o=bind jenv-cache
   

3. 运行容器时挂载该卷：

   sh
   docker run --rm -v jenv-cache:"/root/.jenv/" mingc/android-build-box bash -l `echo "Hello World"`
   

Gradle缓存

添加以下参数以缓存Gradle主目录：

sh
-v "$HOME/.dockercache/gradle":"/root/.gradle"

示例：

sh
docker run --rm -v `pwd`:/project -v "$HOME/.dockercache/gradle":"/root/.gradle" mingc/android-build-box bash -c 'cd /project; ./gradlew build'

在gradle.properties中启用缓存：

sh
org.gradle.caching=true

Android SDK缓存

缓存SDK可灵活更新/移除平台/构建工具。1.25.0版本中/opt/android-sdk/约需6GB空间。

1. 在主机创建缓存目录：

   sh
   mkdir ~/.dockercache/android-sdk
   

2. 创建命名卷android-sdk-cache：

   sh
   docker volume create --driver local --opt type=none --opt device=~/.dockercache/android-sdk/ --opt o=bind android-sdk-cache
   

3. 运行容器时挂载该卷：

   sh
   docker run --rm -v android-sdk-cache:"/opt/android-sdk/" mingc/android-build-box bash -l
   

使用sdkmanager管理SDK组件：

• 列出已安装组件：sdkmanager --list_installed
• 卸载平台：sdkmanager --uninstall 'platforms;android-26'
• 安装平台：sdkmanager --install 'platforms;android-26'

完整文档参见sdkmanager***文档。

建议的gradle.properties配置

推荐设置以下JVM参数：

sh
org.gradle.jvmargs=-Xmx8192m -XX:MaxMetaspaceSize=1024m -XX:+UseContainerSupport -XX:MaxRAMPercentage=97.5

参数说明：

• -Xmx8192m：JVM最大内存（支持g为单位）
• -XX:MaxMetaspaceSize=1024m：元空间最大大小（修复Gradle bug gradle/gradle#***）
• -XX:+UseContainerSupport：允许JVM感知容器环境（默认启用）
• -XX:MaxRAMPercentage=97.5：JVM最大使用容器内存的97.5%

容器总内存应大于Xmx + MaxMetaspaceSize + 预留空间（如10GB容器可分配8GB Xmx + 1GB MaxMetaspaceSize + 1GB预留）。

在Bitbucket Pipelines中构建Android项目

在Bitbucket仓库的bitbucket-pipelines.yml中指定该镜像：

yml
image: mingc/android-build-box:latest

pipelines:
  default:
    - step:
        caches:
          - gradle
          - gradle-wrapper
          - android-emulator
        script:
          - . ~/.bash_profile
          - jenv global 11  # 切换Java版本
          - bash ./gradlew assemble
definitions:
  caches:
    gradle-wrapper: ~/.gradle/wrapper
    android-emulator: $ANDROID_HOME/system-images/android-21

在Github Actions中构建Flutter项目

示例.github/workflows/main.yml：

yml
name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-20.04
    container: mingc/android-build-box:latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/cache@v3
      with:
        path: /root/.gradle/caches
        key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
        restore-keys: |
          ${{ runner.os }}-gradle-
    - name: Build
      run: |
        echo "Work dir: $(pwd)"
        echo "User: $(whoami)"
        flutter --version
        flutter analyze
        flutter build apk
    - name: Archive apk
      uses: actions/upload-artifact@v3
      with:
        name: apk
        path: build/app/outputs/apk
    - name: Test
      run: flutter test
    - name: Clean build to avoid action/cache error
      run: rm -fr build

在Docker中运行Android模拟器

以下脚本创建并启动ARM模拟器（用于集成测试/ instrumentation测试）：

sh
#!/bin/bash

export ADB_INSTALL_TIMEOUT=30  # 增加ADB超时时间

# 下载ARM系统镜像
sdkmanager "system-images;android-22;default;armeabi-v7a"

# 创建AVD模拟器（100MB SD卡）
echo "no" | avdmanager create avd \
    -n Android_5.1_API_22 \
    -k "system-images;android-22;default;armeabi-v7a" \
    -c 100M \
    --force

# 后台启动模拟器
$ANDROID_HOME/emulator/emulator -avd Android_5.1_API_22 -no-skin -no-audio -no-window -no-boot-anim -gpu off &

# 需添加延迟等待模拟器启动

注意：暂不支持x86_64模拟器，详见Issue #18。

切换系统Java版本

1.23.0及以上版本使用jEnv管理Java版本（旧版本使用update-alternatives，文档见此处）。

使用jEnv前需加载环境：

sh
. ~/.bash_profile

查看可用Java版本：

sh
jenv versions

设置全局Java 8：

sh
jenv global 1.8

设置当前目录Java版本（会创建.java-version文件）：

sh
jenv local 11

构建Docker镜像

构建前确保有足够磁盘空间（镜像大小约10-16GB）。需Docker Engine 19.03+（支持buildx）。

构建命令

sh
docker buildx build -t android-build-box .

构建目标

支持三种构建目标（默认complete-flutter）：

自定义软件版本

默认安装最新软件，可通过构建参数指定版本（需设置_TAGGED=tagged）：

sh
docker buildx build --target minimal \
  --build-arg ANDROID_SDK_TOOLS_TAGGED="tagged" \
  --build-arg ANDROID_SDK_TOOLS_VERSION="4333796" \
  --build-arg JENV_TAGGED="tagged" \
  --build-arg JENV_RELEASE="0.5.6" .

变更日志

详见专用变更日志。

兼容性

详见兼容性矩阵。

贡献

欢迎通过Pull Request改进镜像。文档修改请以DOCS:为提交前缀，CI配置修改以CI:为前缀。

参考资料

• Dockerfile参考
• 编写Dockerfile的最佳实践
• 构建自己的镜像
• uber android build environment
• Refactoring a Dockerfile for image size
• Label Schema