三步搭建 Docker Android 模拟器：从选镜像到 ADB 连通的完整上手指南

三步搭建 Docker Android 模拟器：从选镜像到 ADB 连通的完整上手指南

【免费下载链接】docker-android🤖 A minimal and customizable Docker image running the Android emulator as a service.项目地址: https://gitcode.com/GitHub_Trending/dockera/docker-android

你是不是也遇到过这样的场景：应用刚写完一个新版本，想在 Android 13 上快速回归一遍，手边却既没有真机，也没有一套能随时复用的测试设备？又或者在 CI/CD 流水线里，每次想跑一次 UI 自动化，都要临时找机器、装模拟器，折腾半天还没开始干活。docker-android就是为解决这类问题而生的项目——它把 Android 模拟器打包成一个轻量、可定制的 Docker 镜像，让模拟器像一项服务一样随启随停、按需扩容，无论是个人本地调试还是团队持续集成，都能在一分钟内用起来。

一句话概括：docker-android 是一个以最小化体积为目标、基于 Alpine 优化的 Docker 镜像，内置 Android 模拟器、ADB 服务器和支持 libvirt 的 QEMU，开箱即用地把 Android 模拟器变成可远程连接的容器服务。

别再临时找设备了：把模拟器变成一项随叫随到的服务

传统做法里，跑一个 Android 模拟器通常要经历：下载几十 GB 的 Android Studio、创建 AVD、调整显卡和内存配置、忍受缓慢的启动……而到了 CI 环境，这套流程更是噩梦——每台构建机都得重复安装，镜像冲突、版本不一致的问题层出不穷。

docker-android 的思路完全不同：它把"模拟器环境"整体固化进镜像，你想用哪个 Android 版本，就构建或拉取对应的镜像；想开几个并行测试环境，就启动几个容器。模拟器不再是你机器上的一个"程序"，而是一台可以被反复创建、销毁、克隆的"虚拟设备"，用完即扔，干净利落。

三分钟快速上手：从零到 ADB 连通

下面这套流程，是大多数场景下的标准路径。建议你先按默认配置完整走一遍，体会一下"一条命令起一台模拟器"的爽快感。

第一步：克隆项目并构建镜像

先把项目源码拿到本地：

git clone https://gitcode.com/GitHub_Trending/dockera/docker-android cd docker-android

然后执行构建命令。默认会安装 Android SDK、平台工具和模拟器，并选用API 33（Android 13）+ Google APIs + x86_64这套配置：

docker build -t android-emulator .

首次构建需要下载系统镜像，耗时取决于网络环境，耐心等待即可；构建完成后，后续启动就是秒级响应。

第二步：一键启动容器

构建完成后，把宿主的 KVM 设备挂载进容器，并映射 5555 端口供 ADB 连接：

docker run -it --rm --device /dev/kvm -p 5555:5555 android-emulator

容器启动后会自动完成三件事：拉起 ADB 服务、创建名为android的 AVD、以无窗口（headless）模式启动模拟器。如果你想更省事，项目里还内置了docker-compose.yml，一条命令即可开箱即用：

docker compose up android-emulator

第三步：用 ADB 连上这台"远程手机"

等几秒钟、系统内核完成引导后，在宿主机上执行：

adb connect 127.0.0.1:5555

adb devices能看到设备在线，就意味着你已经拥有了一台完整的 Android 设备。装应用、跑测试、抓日志，和连真机没有任何区别。

核心特性拆解：这些设计为什么值得你关注

理解了基本用法后，再来看几个关键设计，它们决定了这个项目在真实场景里到底好不好用。

版本与类型：一个参数换一套系统

docker-android 支持通过三个构建参数自由组合出不同的镜像：

参数	作用	示例值
API_LEVEL	指定 Android 系统版本	28 / 30 / 33 / 34
IMG_TYPE	镜像类型	google_apis或google_apis_playstore
ARCHITECTURE	CPU 架构	x86_64或x86

比如想构建带 Google Play 商店的 Android 13 镜像：

docker build --build-arg API_LEVEL=33 --build-arg IMG_TYPE=google_apis_playstore -t android-emulator:playstore .

这意味着你可以在 CI 里轻松维护一套"版本矩阵"，同一份测试脚本依次跑过 API 28、30、33 等多个环境，兼容性问题无处遁形。

数据持久化：重启不丢状态

模拟器每次重启会清空数据（这是刻意设计，保证环境干净）。但如果你需要保留已安装的应用或用户数据，把 AVD 目录挂载出来即可：

docker run -it --rm --device /dev/kvm -p 5555:5555 -v ~/android_avd:/data android-emulator

AVD 的默认存储路径是容器内的/data，挂载之后，下次启动会直接复用已有状态。

远程可视：配合 scrcpy 实时看屏幕

模拟器默认无窗口运行，但你可以通过 scrcpy 把它变成"看得见"的设备。先执行adb connect，再本地运行：

scrcpy

就能实时看到并操作模拟器屏幕，非常适合演示、录制和人工点检。默认的 Pixel 预设分辨率是 1080x1920，画面清晰度完全够用。

常见问题与避坑指南

上手过程中，下面几个问题出现的频率最高，提前了解能帮你省下不少排查时间。

没有 /dev/kvm，模拟器奇慢无比

模拟器依赖 KVM 做硬件加速。在云服务器或虚拟机里运行时，需要确认宿主机开启了嵌套虚拟化（如 VMware/ESXi 的Virtualize Intel VT-x/EPT）。检测方法很简单：

ls -l /dev/kvm

如果文件不存在，模拟器要么无法启动，要么慢到无法使用。项目仓库里的install_android.sh脚本也内置了这一步检查，可以作为参考。

PlayStore 镜像连不上 ADB

使用google_apis_playstore镜像时，模拟器与客户端之间需要一致的 ADB 密钥。解决办法：先在本机用adb keygen adbkey生成一对密钥（会得到adbkey和adbkey.pub），再放到项目的keys/目录下覆盖默认文件，然后重新构建镜像。

内存与磁盘不够

API 33 的镜像建议预留4GB 内存和至少 8GB 磁盘空间。模拟器默认使用 8GB 内存和 4 核，如果宿主资源紧张，可以随时覆盖：

docker run -it --rm --device /dev/kvm -p 5555:5555 -e MEMORY=4096 -e CORES=2 android-emulator

启动超时或一直显示 Booting

容器日志里会以 JSON 形式输出状态更新（ANDROID_BOOTING→ANDROID_READY）。如果卡在引导阶段超过 300 秒，多半是资源不足或 KVM 未生效，按上面两条排查即可。

进阶技巧：把镜像用到极致

基础玩法掌握后，这几个进阶技巧能进一步提升效率和体验。

技巧一：构建不装 SDK 的精简镜像

如果 SDK 放在共享存储（如 NFS）上、由多个容器共用，可以在构建时跳过 SDK 安装，把镜像体积从 GB 级压到几百 MB：

docker build -t android-emulator --build-arg INSTALL_ANDROID_SDK=0 .

运行时再通过挂载把 SDK 放进/opt/android即可。下表是官方给出的常见变体体积对比，供你规划存储：

构建变体	未压缩	压缩后
API 33 + 模拟器	5.84 GB	1.97 GB
API 28 + 模拟器	4.29 GB	1.46 GB
不含 SDK 与模拟器	414 MB	138 MB

技巧二：启用 GPU 加速

项目同时提供了基于 CUDA 的 GPU 版本（Dockerfile.gpu）。如果你的 CI 机器配有 NVIDIA 显卡，直接用预置的 compose 服务：

docker compose up android-emulator-cuda

需要 PlayStore 版本则用android-emulator-cuda-store。GPU 加速对渲染密集型测试（如游戏、地图类应用）的提升非常明显。

技巧三：用环境变量微调运行时行为

启动时通过环境变量可以控制多项行为，例如关闭系统动画（CI 跑 UI 测试必备）、跳过 ADB 鉴权、调整分区大小等：

变量	默认值	说明
DISABLE_ANIMATION	false	设为 true 关闭动画，加速测试
SKIP_AUTH	true	设为 false 则要求 ADB 密钥认证
EXTRA_FLAGS	见仓库默认值	追加模拟器启动参数，如调整分区大小

写在最后：从"能用"到"好用"

docker-android 的价值在于，它把 Android 模拟器从"个人工具"升级成了"团队基础设施"。对个人开发者，它是本地快速验证的轻量方案；对团队和 CI 平台，它是可编排、可复制的测试资源池。

给你的下一步建议：先按本文的三步流程跑通一个 API 33 的默认镜像，确认 ADB 连通；然后尝试用构建参数组合出 PlayStore 或不同 API 级别的变体；最后把它接入你的 CI 流水线，用 compose 文件管理多套并行测试环境。当"再开一台模拟器"变成一行命令时，你会发现测试这件事，比想象中从容得多。

【免费下载链接】docker-android🤖 A minimal and customizable Docker image running the Android emulator as a service.项目地址: https://gitcode.com/GitHub_Trending/dockera/docker-android