F-Droid 中文文档 下载 App

F-Droid 构建元数据 YAML 参考：Builds 块完整字段说明

Builds 块是什么

元数据 YAML 中的 Builds 块定义了 F-Droid 如何从源码构建你的应用。每个版本都需要一条完整的 Builds 条目。

完整字段列表

Builds:
  - versionName: '1.2.3'          # 版本名称（字符串）
    versionCode: 123               # 版本号（整数）
    commit: abc123def456...        # 精确锁定的 commit hash 或 tag 名
    subdir: app                     # 源码子目录（可选，build.gradle 不在根目录时）
    gradle:
      - yes                         # 使用 Gradle 构建（最常见）
    maven:
      - yes                         # 使用 Maven 构建
    ant:
      - yes                         # 使用 Ant 构建
    srclibs:                        # 第三方源码库（可选）
      - Retrofit@2.9.0
    prebuild:                       # 构建前命令（可选）
      - sh -c "rm -rf build"
    build:                          # 自定义构建命令（可选，覆盖默认）
      - sh -c "cd app && ./gradlew assembleRelease"
    output: app/build/outputs/apk/release/app-release.apk  # 输出 APK 路径
    rm:                             # 构建前删除的文件/目录（可选）
      - build.gradle.local
    patches:                        # 需要应用的补丁文件（可选）
      - fdroid-fix.patch
    gradleprops:                    # 传递给 Gradle 的属性
      - minSdkVersion=24
    gradle_version: '7.4.2'         # 指定 Gradle 版本（可选）
    sudo:                           # 是否用 sudo 运行构建（很少需要）
      - sh -c "chmod 777 /tmp"
    oldsdklib:                      # 处理旧 SDK 构建问题（可选）
      - -v 28
    target: android-33              # 指定目标 Android SDK（可选）
    ndk: r25b                       # 指定 NDK 版本（可选）
    forceversion: true              # 强制版本号（特殊情况）
    commitforceversion: true        # commit 中强制版本号
    initAfter: 2023-01-01           # 该条目适用的最早日期（用于旧版本）

常见构建场景的 YAML 示例

Gradle 标准构建（最常见）

Builds:
  - versionName: '2.0'
    versionCode: 20
    commit: v2.0
    gradle:
      - yes
    output: app/build/outputs/apk/release/app-release.apk
    prebuild:
      - sed -i 's/versionCode 19/versionCode 20/' build.gradle

多模块 Gradle 项目

Builds:
  - versionName: '1.5'
    versionCode: 15
    commit: 3ab4c5d
    subdir: mobile/app        # APK 模块所在目录
    gradle:
      - yes

使用 srclibs（第三方库从源码构建）

Builds:
  - versionName: '1.0'
    versionCode: 10
    commit: abc123
    gradle:
      - yes
    srclibs:
      - Retrofit@2.9.0
      - OkHttp@4.10.0

srclibs 让 fdroidserver 从源码构建指定的第三方库，而不是下载预编译的 JAR/AAR。

需要补丁的构建

有时你的源码需要小修小补才能在 F-Droid 构建环境中成功。用 patches 字段：

Builds:
  - versionName: '1.0'
    versionCode: 10
    commit: abc123
    gradle:
      - yes
    patches:
      - fdroid-fix-build-env.patch

补丁文件放在 metadata/your-app-name/ 目录下。

自定义构建脚本

如果 Gradle/Maven 都不适用，用 build 字段完全自定义：

Builds:
  - versionName: '1.0'
    versionCode: 10
    commit: abc123
    build:
      - sh -c "export ANDROID_HOME=/opt/android-sdk && ./build.sh"
    output: dist/app-release.apk

Builds 块的常见坑

坑 1：commit 用了 branch HEAD

错误：commit: main — branch 会移动，今天 build 成功明天可能失败。

正确：commit: a1b2c3d4e5f6... — 精确 commit hash，不会变。

坑 2：版本号在 build.gradle 中声明

如果你的版本号在 build.gradle 里写的，fdroidserver 会自动读取。但确保 YAML 中的 versionName 和 versionCode 与 build.gradle 中的一致。

坑 3：output 路径不对

确保 output 路径是相对于源码根目录的。Gradle 默认输出路径是 app/build/outputs/apk/release/app-release.apk，但如果项目结构特殊，可能不同。

本地构建成功后，用 find . -name "*.apk" 确认实际输出路径。

坑 4：构建依赖外部服务

如果构建过程中需要从 maven.google.com 或 jcenter.bintray.com 下载依赖，构建服务器必须能访问这些。F-Droid 构建服务器有自己的 maven 镜像缓存。

坑 5：需要签名密钥

F-Droid 构建时会自动用测试密钥签名。你在本地构建成功不代表官方构建会成功——但如果在 Docker 容器中用 fdroidserver 跑成功了，官方构建大概率也会成功。

验证 Builds 块

写完 YAML 后，本地验证：

# 语法和规则检查
fdroid lint your-app

# 实际构建测试
fdroid build your-app

fdroid lint 能发现绝大多数 YAML 问题，比如：