• 移动开发
• 数据同步

导读：syncthing-android 是 Syncthing 的 Android 封装版，其核心是一个需要交叉编译的 Go 原生二进制libsyncthing.so，因此命令行构建依赖 Android SDK、NDK、Go、Java、Python 等一整套复杂工具链。本文以 docker/README.md 为骨架，完整讲解如何用 Docker 构建应用——从创建 Builder 镜像、初始化 Git 子模块，到执行buildNative与assembleDebug两个 Gradle 任务、最终取出 APK，并结合 docker/Dockerfile、docker/prebuild.sh 与 syncthing/build-syncthing.py 等仓库源码，深入剖析镜像分层、预构建缓存机制与四架构交叉编译原理，帮助你在不污染本机环境的前提下获得可复现、可交付的构建流程。

为什么要用 Docker 构建

syncthing-android 的构建不是普通的 Android 项目构建。它由两个 Gradle 模块组成（见 settings.gradle.kts 中的include(":app", ":syncthing")）：

• :app—— Android 应用本体（Java/Kotlin + AndroidX）；
• :syncthing—— 负责把 Syncthing 的 Go 源码交叉编译成 Android 可加载的libsyncthing.so动态库。

这意味着一次完整构建需要同时具备：

此外，Go 的 cgo 交叉编译对系统的 gcc、头文件等非常敏感（Dockerfile 中甚至专门注释了--reinstall+build-essentials这个解决 cgo 编译 Go 标准库问题的“暗黑技巧”）。手工在宿主机上对齐这些版本与系统库非常容易出错。

而 Docker 方案的核心思路是：先把整套工具链固化成一个 builder 镜像，再把宿主机的源码目录挂载进容器执行 Gradle 构建。宿主无需安装任何 Android/Go 工具链，环境 100% 可复现。

第 1 步：准备工作——克隆仓库并初始化子模块

构建前需要先拿到完整源码。仓库中的 Syncthing 核心代码是以 Git 子模块形式引入的（见 .gitmodules，子模块路径为syncthing/src/github.com/syncthing/syncthing）。

如果最初不是用--recursive克隆的，需要在项目根目录执行：

git submodule init git submodule update

这与 docker/README.md 中构建步骤第 1 条的命令一致（在 bash 中用分号连接即可）。子模块缺失时buildNative会在go run build.go阶段失败，因此这是硬性前置条件。

第 2 步：创建 Builder 镜像

在仓库根目录（已检出 syncthing-android 的位置）执行：

docker build -t syncthing-android-builder:latest -f ./docker/Dockerfile .

该命令把当前目录（-f指定的 docker/Dockerfile 所在的上下文根）构建为镜像syncthing-android-builder:latest。整个过程约需数分钟到十几分钟，取决于网络与机器性能，且只有首次构建需要（之后可复用镜像）。

Builder 镜像的分层拆解

Dockerfile 的逻辑可以拆成五层，逐层理解对排错很有帮助：

1. 基础镜像与系统依赖（L1-L13）

FROM eclipse-temurin:11-jdk-jammy ENV GO_VERSION 1.22.7 ARG ANDROID_SDK_FILENAME=commandlinetools-linux-9123335_latest.zip WORKDIR /opt RUN apt-get update && apt-get install --reinstall --no-install-recommends -y \ build-essential gcc unzip git gnupg python3

• 选择 Temurin JDK 11，正好满足 app 模块sourceCompatibility = JavaVersion.VERSION_11（见 app/build.gradle.kts）的要求；
• --reinstall build-essential gcc是官方注释点名的 cgo 兼容补丁，不要删除；
• ANDROID_SDK_FILENAME用ARG声明，可用--build-arg覆盖，默认值来自 Android 官方命令行工具发布页。

2. Go 工具链（L15-L20）

RUN wget -nv https://dl.google.com/go/go${GO_VERSION}.linux-amd64.tar.gz && \ tar -zxf go${GO_VERSION}.linux-amd64.tar.gz && \ rm go${GO_VERSION}.linux-amd64.tar.gz ENV GOROOT /opt/go ENV PATH /opt/go/bin:${PATH}

Go 版本被ENV GO_VERSION固定为 1.22.7，保证镜像内的编译行为与项目 CI 一致。

3. Android SDK 与 NDK（L22-L41）

RUN mkdir -p /opt/android-sdk && cd /opt/android-sdk && \ wget -q https://dl.google.com/android/repository/${ANDROID_SDK_FILENAME} && \ unzip -q ${ANDROID_SDK_FILENAME} && \ rm ${ANDROID_SDK_FILENAME} ENV ANDROID_HOME /opt/android-sdk ARG SDKMANAGER="${ANDROID_HOME}/cmdline-tools/bin/sdkmanager --sdk_root=${ANDROID_HOME}" RUN yes | $SDKMANAGER --licenses > /dev/null ENV NDK_VERSION 25.2.9519653 RUN $SDKMANAGER tools platform-tools \ "build-tools;34.0.0" "platforms;android-34" \ "extras;android;m2repository" "ndk;${NDK_VERSION}" RUN yes | $SDKMANAGER --licenses

注意这里的版本号不是随便填的，必须与 Gradle 侧严格对齐：

• 顶层 build.gradle.kts 中extra.set("ndkVersionShared", "25.2.9519653")，注释明确写着“Changes to this value must be reflected in./docker/Dockerfile”；
• app/build.gradle.kts 中同样有“Changes to these values need to be reflected in../docker/Dockerfile”的注释，其compileSdk = 34、buildToolsVersion = "34.0.0"、ndkVersion = 25.2.9519653与 Dockerfile 一一对应。

4. 预构建缓存层（L43-L54）

ENV SYNCTHING_ANDROID_PREBUILT 1 ENV GOCACHE /opt/gocache ENV GOPATH /opt/gopath ADD . /opt/syncthing-android RUN /opt/syncthing-android/docker/prebuild.sh WORKDIR /mnt

这是本 Dockerfile 最巧妙的一层：它在镜像构建期间就把源码复制进镜像，跑一遍 prebuild.sh，把 Gradle 依赖与 Go 的编译缓存预填充到镜像层里：

#!/bin/bash -e if [ -z "$SYNCTHING_ANDROID_PREBUILT" ]; then echo "Prebuild disabled" rm -rf syncthing-android exit 0 fi echo "Prepopulating gradle and go build/pkg cache" cd syncthing-android ./gradlew --no-daemon lint buildNative cd .. rm -rf syncthing-android

含义：

• SYNCTHING_ANDROID_PREBUILT=1开启预构建；若置空，prebuild 会直接删掉源码退出（此时镜像仅含工具链）；
• 预构建执行lint buildNative：buildNative需要 Go 交叉编译四个架构并下载 Gradle 依赖，这些产物分别落入GOCACHE（/opt/gocache）与GOPATH（/opt/gopath），全部被 Docker 层缓存固化；
• 结束后删除源码副本，保证最终镜像不携带源码，保持纯净。

之后每次docker run做增量构建时，Gradle 依赖与 Go 模块缓存都已在镜像层中，构建速度大幅提升。这也是为什么真正构建时的./gradlew buildNative能快速命中缓存。

5. 默认工作目录（L56）

WORKDIR /mnt与 README 中-v /tmp/syncthing-android:/mnt的挂载约定呼应：宿主机源码目录必须挂载到容器的/mnt。

第 3 步：执行实际构建

在仓库根目录执行（README 原命令）：

docker run --rm -v /tmp/syncthing-android:/mnt syncthing-android-builder ./gradlew buildNative assembleDebug

参数拆解：

两个 Gradle 任务各做了什么

buildNative—— 定义在 syncthing/build.gradle.kts：

tasks.register<PythonTask>("buildNative") { val ndkVersionShared = rootProject.extra.get("ndkVersionShared") environment("NDK_VERSION", "$ndkVersionShared") inputs.dir("$projectDir/src/") outputs.dir("$projectDir/../app/src/main/jniLibs/") command = "-u ./build-syncthing.py" }

它通过ru.vyarus.use-python插件以 Python 3 运行 syncthing/build-syncthing.py，输入是syncthing/src/源码，输出是app/src/main/jniLibs/。从源码看，脚本的核心流程是：

1. 读取 app/build.gradle.kts 中的minSdk（当前为 21），用于确定 NDK clang 工具链的 API 级别；
2. 解析ANDROID_NDK_HOME或由NDK_VERSION+ANDROID_HOME推导 NDK 路径；
3. git fetch --tags拉取 Syncthing 子模块的 tag，保证git describe可用；
4. 对四个 ABI 逐一执行go run build.go -goos android ...交叉编译，并用 NDK 自带的对应 clang 作为 C 编译器（CGO_ENABLED=1）：
   • arm→armeabi
   • arm64→arm64-v8a
   • x86→x86
   • x86_64→x86_64
5. 把每个架构编译出的syncthing可执行文件改名为libsyncthing.so，拷贝到app/src/main/jniLibs/<abi>/。

assembleDebug—— 标准 Android Gradle 任务，把:app模块连同jniLibs里的四个libsyncthing.so一起打进 debug APK。这里有一个关键联动：app/build.gradle.kts 中

project.afterEvaluate { android.buildTypes.forEach { tasks.named("merge${it.name.capitalized()}JniLibFolders") { dependsOn(":syncthing:buildNative") } } }

即打包前强制先完成原生编译；同时packagingOptions { jniLibs { useLegacyPackaging = true } }保证libsyncthing.so在 App Bundle 安装场景下能出现在正确位置（源码注释专门强调了这一点）。

注意：命令默认是在:syncthing与:app两个模块（见 settings.gradle.kts）上聚合执行，无需单独进入目录。

第 4 步：取出 APK 产物

构建成功后，APK 会落在宿主机挂载目录内的 Gradle 默认输出路径：

app/build/outputs/apk/debug/app-debug.apk

README 中“Retrieve APKs from./app/build/outputs”即指此处（宿主机上对应/tmp/syncthing-android/app/build/outputs）。由于挂载是双向的，容器内写入的文件会实时同步到宿主机。若要产出 release APK，可把任务换成./gradlew buildNative assembleRelease，但 app/build.gradle.kts 中 release 签名是通过环境变量（SYNCTHING_RELEASE_STORE_FILE、SIGNING_PASSWORD、SYNCTHING_RELEASE_KEY_ALIAS）注入的，未设置时不会签名，这一点需自行留意。

第 5 步：验证与排错要点

验证构建产物：解包 APK 可确认四个 ABI 的libsyncthing.so是否齐全：

unzip -l app/build/outputs/apk/debug/app-debug.apk | grep libsyncthing.so

运行时，app/src/main/java/com/nutomic/syncthingandroid/service/SyncthingRunnable.java 会通过chmod 500赋予该动态库可执行权限，并以-home、-no-browser、-logflags=0等参数启动它——也就是说 APK 里的.so其实是被当作命令行程序来运行的，这也是构建时特意用go build产出可执行文件再改名的原因。

常见问题与排查方向：

• buildNative报错找不到libsyncthing.so/ go 源码缺失：八成是子模块未初始化，回到第 1 步执行git submodule init; git submodule update。
• sdkmanager卡在 license：Dockerfile 已用yes | sdkmanager --licenses自动接受，若自行构建镜像时改动过 SDK 版本，需保留该步骤。
• 版本漂移：修改 app/build.gradle.kts 或顶层 build.gradle.kts 中的 SDK/NDK 版本时，必须同步更新 docker/Dockerfile 中对应的build-tools、platforms、NDK_VERSION（两处源码注释均有明确提示），否则容器内工具链与 Gradle 期望不一致会直接构建失败。
• 首次构建慢：buildNative需要下载 Go 模块并交叉编译四个架构，首次无缓存时耗时较长；第二次起依赖prebuild.sh预填充的镜像缓存会显著加速。若经常改动 Go 依赖，可考虑docker build时复用旧镜像层以保留GOCACHE/GOPATH缓存。

与传统命令行构建的对比

项目根 README.md 的 “Building” 章节也提供了不依赖 Docker 的构建路径：手动安装 SDK/NDK（版本以 docker/Dockerfile 为准）、Go、JDK 11、Python 3，然后./gradlew buildNative与./gradlew assembleDebug。两种方式跑的是同一套 Gradle 任务链，差异只在于：

• Docker 方式：零宿主机依赖、环境完全可复现、适合 CI 与交付场景；
• 手动方式：需要自行对齐 README.md 中列出的全部依赖版本，且 Windows 上必须使用 Command Prompt 并把路径分隔符改为\（README 明确注明）。

两者产物的路径与结构完全一致，即app/build/outputs下的 APK 与app/src/main/jniLibs/下的四个 ABI 动态库。需要说明的是，该项目当前处于停更维护状态（根 README.md 已声明 discontinued），但上述 Docker 构建链路对仓库现有版本的复现与二次开发依然完整有效。

小结

一条命令即可固化整套 Android + Go 交叉编译工具链，另一条命令即可完成从源码到 APK 的全部构建，这就是 syncthing-android 的 Docker 构建方案。其核心要点可以概括为三件事：以 docker/Dockerfile 固化工具链版本（Go 1.22.7、NDK 25.2.9519653、SDK 34）、以 docker/prebuild.sh 预填充 Gradle/Go 缓存、以/mnt挂载衔接 build-syncthing.py 的四架构交叉编译与assembleDebug的 APK 打包。掌握这一流程后，无论是本地复现、CI 集成，还是基于 syncthing/build.gradle.kts 定制 ABI 列表，都可以在完全隔离的容器环境中稳定推进。

• 移动开发
• 数据同步