Android 深度实践

Appearance

gradle.properties 配置 ​

源：Gradle 官方文档 - Build Environment

gradle.properties 文件用于配置 Gradle 构建环境、JVM 参数和项目属性，合理配置可以显著提升构建性能和开发体验。

gradle.properties 文件位置 ​

全局配置 ​

位置：~/.gradle/gradle.properties

作用范围：所有 Gradle 项目

适用场景：

  • 全局 JVM 参数
  • 个人开发环境配置
  • 私有仓库凭证

项目配置 ​

位置：<project-root>/gradle.properties

作用范围：当前项目

适用场景：

  • 项目特定配置
  • 团队共享配置
  • 项目属性定义

子项目配置 ​

位置：<project-root>/<subproject>/gradle.properties

作用范围：特定子项目

JVM 参数配置 ​

堆内存配置 ​

properties
# 设置最大堆内存 4GB
org.gradle.jvmargs=-Xmx4096m

# 设置初始堆内存
org.gradle.jvmargs=-Xms512m -Xmx4096m

# 设置元空间大小
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m

推荐配置：

项目规模推荐配置
小型项目（< 10模块）-Xmx2048m
中型项目（10-50模块）-Xmx4096m
大型项目（> 50模块）-Xmx6144m 或更高

垃圾回收器配置 ​

properties
# 使用 G1 垃圾回收器（推荐）
org.gradle.jvmargs=-Xmx4096m -XX:+UseG1GC

# 使用 Z GC（JDK 15+，超大项目）
org.gradle.jvmargs=-Xmx8192m -XX:+UseZGC

错误诊断 ​

properties
# OOM 时生成 heap dump
org.gradle.jvmargs=-Xmx4096m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/dumps

# 打印 GC 详情
org.gradle.jvmargs=-Xmx4096m -XX:+PrintGCDetails -XX:+PrintGCDateStamps

Gradle Daemon 配置 ​

启用 Daemon ​

properties
# 启用 Gradle Daemon（默认启用）
org.gradle.daemon=true

优势：

  • 避免每次构建启动 JVM
  • 缓存类加载和项目模型
  • 显著提升构建速度

Daemon 超时 ​

properties
# Daemon 空闲超时（毫秒）
org.gradle.daemon.idletimeout=3600000  # 1小时

Daemon JVM 参数 ​

properties
# 专门为 Daemon 设置 JVM 参数
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -Dfile.encoding=UTF-8

并行构建配置 ​

启用并行构建 ​

properties
# 启用并行构建
org.gradle.parallel=true

# 设置并行 workers 数量（默认为 CPU 核心数）
org.gradle.workers.max=4

注意：

  • 适用于多模块项目
  • 确保模块间依赖正确配置
  • 可能增加内存消耗

按需配置 ​

properties
# 仅配置需要的项目（实验性）
org.gradle.configureondemand=true

构建缓存配置 ​

启用构建缓存 ​

properties
# 启用本地构建缓存
org.gradle.caching=true

效果：

  • 复用之前构建的输出
  • 跨分支构建加速
  • 团队成员共享缓存

文件监控 ​

properties
# 启用文件系统监控（提升增量构建）
org.gradle.vfs.watch=true

优势：

  • 监听文件系统变化
  • 避免重复扫描
  • 提升二次构建速度

Android 专用属性 ​

Kapt 配置 ​

properties
# 启用 Kapt 增量编译
kapt.incremental.apt=true

# 使用 Worker API 并行执行
kapt.use.worker.api=true

# 缓存 Kapt 输出
kapt.include.compile.classpath=false

R8/ProGuard 配置 ​

properties
# 启用 R8 Full Mode
android.enableR8.fullMode=true

# 启用资源缩减
android.enableResourceOptimizations=true

BuildConfig 和 R 类 ​

properties
# 非常量 R 类（提升编译速度）
android.nonFinalResIds=true

# 非传递性 R 类
android.nonTransitiveRClass=true

# 默认不生成 BuildConfig
android.defaults.buildfeatures.buildconfig=false

其他 Android 属性 ​

properties
# 启用 Jetifier（AndroidX 迁移）
android.useAndroidX=true
android.enableJetifier=true

# 禁用自动生成 Android Test Orchestrator
android.experimental.testOptions.emulatorSnapshots.maxSnapshotsForTestFailures=0

日志和调试 ​

日志级别 ​

properties
# 设置日志级别
org.gradle.logging.level=info

级别：quiet, warn, lifecycle, info, debug

警告控制 ​

properties
# 隐藏废弃功能警告
org.gradle.warning.mode=none

# 警告模式（all, summary, none）
org.gradle.warning.mode=summary

控制台输出 ​

properties
# 富文本控制台（颜色、进度条）
org.gradle.console=rich

# 其他选项：plain, auto, verbose

项目自定义属性 ​

定义项目属性 ​

properties
# gradle.properties
app_version_name=1.0.5
app_version_code=10

enable_leak_canary=true
api_base_url=https://api.example.com

在构建脚本中使用 ​

kotlin
// build.gradle.kts
val appVersionName: String by project
val appVersionCode: String by project
val enableLeakCanary: String by project

android {
    defaultConfig {
        versionName = appVersionName
        versionCode = appVersionCode.toInt()
    }
}

dependencies {
    if (enableLeakCanary.toBoolean()) {
        debugImplementation("com.squareup.leakcanary:leakcanary-android:2.12")
    }
}

条件属性 ​

kotlin
val myProperty: String? = project.findProperty("myProperty") as? String
val flag = project.hasProperty("enable_feature")

环境变量集成 ​

从环境变量读取 ​

properties
# 使用环境变量
systemProp.http.proxyHost=${env.HTTP_PROXY_HOST}
systemProp.http.proxyPort=${env.HTTP_PROXY_PORT}

CI/CD 环境 ​

properties
# CI 标志
is_ci_build=false

在 CI 中覆盖：

bash
export ORG_GRADLE_PROJECT_is_ci_build=true

使用：

kotlin
val isCiBuild: String by project
if (isCiBuild.toBoolean()) {
    // CI专用配置
}

网络代理配置 ​

HTTP 代理 ​

properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=username
systemProp.http.proxyPassword=password

# 不使用代理的主机
systemProp.http.nonProxyHosts=*.example.com|localhost

HTTPS 代理 ​

properties
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=username
systemProp.https.proxyPassword=password

性能优化配置模板 ​

推荐配置（中型项目） ​

properties
# JVM 参数
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# Gradle Daemon
org.gradle.daemon=true
org.gradle.daemon.idletimeout=3600000

# 并行构建
org.gradle.parallel=true
org.gradle.workers.max=4

# 构建缓存
org.gradle.caching=true
org.gradle.vfs.watch=true

# 配置缓存（实验性）
org.gradle.configuration-cache=true

# 日志控制
org.gradle.console=rich
org.gradle.warning.mode=summary

# Android 优化
android.useAndroidX=true
android.nonFinalResIds=true
android.nonTransitiveRClass=true
kapt.incremental.apt=true
kapt.use.worker.api=true

大型项目配置 ​

properties
# 更大的堆内存
org.gradle.jvmargs=-Xmx8192m -XX:MaxMetaspaceSize=2048m -XX:+UseG1GC -Dfile.encoding=UTF-8

# 更多 workers
org.gradle.workers.max=8

# 其他同上...

敏感信息管理 ​

不要提交敏感信息 ​

❌ 错误做法：

properties
# gradle.properties（提交到版本控制）
api_key=abc123secret
db_password=mypassword

✅ 正确做法：

方案一：使用本地文件

properties
# gradle.properties
# 不提交 local.properties
properties
# local.properties（不提交到版本控制）
api_key=abc123secret
db_password=mypassword

读取：

kotlin
val localProperties = Properties()
file("local.properties").inputStream().use {
    localProperties.load(it)
}

val apiKey = localProperties.getProperty("api_key")

方案二：使用环境变量

``bash export ORG_GRADLE_PROJECT_api_key=abc123secret


```kotlin
val apiKey: String by project

方案三：使用全局 gradle.properties

properties
# ~/.gradle/gradle.properties（用户目录，不提交）
api_key=abc123secret

最佳实践 ​

合理分配内存：

  • 根据项目规模设置
  • 留意 OOM 错误
  • 监控 Daemon 内存使用

启用性能优化：

  • 并行构建
  • 构建缓存
  • 文件监控

Android 项目优化：

  • 非常量 R 类
  • 非传递性 R 类
  • Kapt 增量编译

敏感信息安全：

  • 使用环境变量
  • 使用 local.properties
  • 使用全局 gradle.properties
  • 永远不要提交密码到版本控制

版本控制：

  • 提交项目 gradle.properties
  • 不提交 local.properties
  • 使用注释说明必需属性

团队协作：

  • 文档化必需属性
  • 提供默认值
  • 使用 findProperty 安全读取