Android 开发环境判断：BuildConfig、Product Flavor 与运行时检测

前言#

在 Android 开发中，我们经常需要让 App 在不同环境下表现出不同行为：

开发环境下显示调试菜单、输出详细日志、连接本地服务器
测试环境下连接测试服务器、开启性能检测
生产环境下关闭所有调试功能、连接正式服务器

问题来了：如何让代码知道当前运行在什么环境下？

这篇文章将为你梳理 Android 生态中判断开发环境的几种主流方案，从 Gradle 编译期注入到运行时动态检测，一网打尽。

Note

本文基于 Kotlin + Gradle (KTS) 编写，Gradle 插件版本 8.x，AGP 8.x。

1. 方案总览#

方案	原理	时机	可靠性	适用场景
`BuildConfig.DEBUG`	debug buildType 自动生成	编译期	⭐⭐⭐	简单判断 debug/release
自定义 BuildConfig 字段	Gradle 注入常量	编译期	⭐⭐⭐⭐	自定义环境标识
Product Flavor	Gradle 多维度构建	编译期	⭐⭐⭐⭐⭐	多环境（dev/staging/prod）
设备 ID / 签名判断	运行时检测	运行时	⭐⭐⭐	兜底方案
Content Provider 自动初始化	应用启动时	运行时	⭐⭐⭐⭐	第三方 SDK 初始化

2. BuildConfig.DEBUG：最简单的方案#

当你用 Android Studio 创建项目时，Gradle 自动生成了 debug 和 release 两个 buildType。debug 类型下 BuildConfig.DEBUG 自动为 true。

2.1 使用#

1
// 在代码中直接使用
2
if (BuildConfig.DEBUG) {
3
    Log.d("MyApp", "当前是调试模式")
4
    // 显示调试面板
5
} else {
6
    // 生产环境逻辑
7
}

2.2 内部原理#

1
android {
2
    buildTypes {
3
        debug {
4
            // debug 模式下 isDebuggable 默认为 true
5
        }
6
        release {
7
            isDebuggable = false
8
            isMinifyEnabled = true
9
            proguardFiles(...)
10
        }
11
    }
12
}

Gradle 编译时自动生成：

1
public final class BuildConfig {
2
    public static final boolean DEBUG = true;  // debug 时为 true
3
    public static final String BUILD_TYPE = "debug";
4
    // ...
5
}

2.3 局限性#

BuildConfig.DEBUG 只能区分 debug 和 release 两种 buildType。如果你需要区分开发环境、测试环境、预发布环境、生产环境，这个字段就不够用了。

3. 自定义 BuildConfig 字段#

如果 debug/release 不够用，可以在 Gradle 中向 BuildConfig 注入自定义字段。

3.1 添加自定义字段#

1
android {
2
    buildTypes {
3
        debug {
4
            buildConfigField("String", "API_BASE_URL", "\"https://dev-api.example.com\"")
5
            buildConfigField("String", "ENV_NAME", "\"development\"")
6
            buildConfigField("boolean", "ENABLE_ANALYTICS", "false")
7
            buildConfigField("int", "LOG_LEVEL", "2")
8
        }
9
        release {
10
            buildConfigField("String", "API_BASE_URL", "\"https://api.example.com\"")
11
            buildConfigField("String", "ENV_NAME", "\"production\"")
12
            buildConfigField("boolean", "ENABLE_ANALYTICS", "true")
13
            buildConfigField("int", "LOG_LEVEL", "0")
14
        }
15
    }
16
}

3.2 在代码中使用#

1
object AppConfig {
2
    val apiBaseUrl: String get() = BuildConfig.API_BASE_URL
3
    val envName: String get() = BuildConfig.ENV_NAME
4
    val isAnalyticsEnabled: Boolean get() = BuildConfig.ENABLE_ANALYTICS
5
    val logLevel: Int get() = BuildConfig.LOG_LEVEL
6

7
    val isDebug: Boolean
8
        get() = envName == "development"
9
}

3.3 封装为枚举#

1
enum class AppEnvironment(val envName: String) {
2
    DEVELOPMENT("development"),
3
    STAGING("staging"),
4
    PRODUCTION("production");
5

6
    companion object {
7
        fun current(): AppEnvironment = when (BuildConfig.ENV_NAME) {
8
            "development" -> DEVELOPMENT
9
            "staging" -> STAGING
10
            else -> PRODUCTION
11
        }
12
    }
13
}
14

15
// 使用
16
fun initializeApp() {
17
    when (AppEnvironment.current()) {
18
        AppEnvironment.DEVELOPMENT -> {
19
            // 开启严格模式
20
            StrictMode.enableDefaults()
21
        }
22
        AppEnvironment.STAGING -> {
23
            // 连接测试服务器
24
        }
25
        AppEnvironment.PRODUCTION -> {
26
            // 初始化崩溃上报
27
            CrashReport.init()
28
        }
29
    }
30
}

4. Product Flavor：多环境构建的正确姿势#

对于需要多套环境配置的项目，Product Flavor 是官方推荐的标准做法。

4.1 定义 Flavor#

1
android {
2
    flavorDimensions += "environment"
3

4
    productFlavors {
5
        create("dev") {
6
            dimension = "environment"
7
            applicationIdSuffix = ".dev"
8
            versionNameSuffix = "-dev"
9
            buildConfigField("String", "API_BASE_URL", "\"https://dev-api.example.com\"")
10
            buildConfigField("String", "ENV", "\"dev\"")
11
            manifestPlaceholders["appLabel"] = "MyApp Dev"
12
        }
13
        create("staging") {
14
            dimension = "environment"
15
            applicationIdSuffix = ".staging"
16
            versionNameSuffix = "-staging"
17
            buildConfigField("String", "API_BASE_URL", "\"https://staging-api.example.com\"")
18
            buildConfigField("String", "ENV", "\"staging\"")
19
            manifestPlaceholders["appLabel"] = "MyApp Staging"
20
        }
21
        create("prod") {
22
            dimension = "environment"
23
            buildConfigField("String", "API_BASE_URL", "\"https://api.example.com\"")
24
            buildConfigField("String", "ENV", "\"prod\"")
25
            manifestPlaceholders["appLabel"] = "MyApp"
26
        }
27
    }
28
}

4.2 Flavor + BuildType 的组合#

Product Flavor 和 BuildType 是正交的，Gradle 会为每种组合生成一个 variant：

1
devDebug          # 开发环境 + 调试构建
2
devRelease        # 开发环境 + 发布构建
3
stagingDebug      # 测试环境 + 调试构建
4
stagingRelease    # 测试环境 + 发布构建
5
prodDebug         # 生产环境 + 调试构建
6
prodRelease       # 生产环境 + 发布构建

4.3 按 Variant 存放资源#

你可以为不同 flavor 创建不同的资源目录：

1
app/
2
└── src/
3
    ├── main/           # 公共代码和资源
4
    ├── dev/            # dev flavor 专属
5
    │   ├── java/.../DevConfig.kt
6
    │   └── res/values/strings.xml
7
    ├── staging/        # staging flavor 专属
8
    │   ├── java/.../StagingConfig.kt
9
    │   └── res/values/strings.xml
10
    └── prod/           # prod flavor 专属
11
        ├── java/.../ProdConfig.kt
12
        └── res/values/strings.xml

关键技巧：在 main 中定义接口，在各 flavor 中提供实现：

1
interface EnvironmentConfig {
2
    val baseUrl: String
3
    val enableLogging: Boolean
4
    val enableStrictMode: Boolean
5
}
6

7
// src/dev/java/.../DevEnvironmentConfig.kt
8
object DevEnvironmentConfig : EnvironmentConfig {
9
    override val baseUrl = "https://dev-api.example.com"
10
    override val enableLogging = true
11
    override val enableStrictMode = true
12
}
13

14
// src/prod/java/.../ProdEnvironmentConfig.kt
15
object ProdEnvironmentConfig : EnvironmentConfig {
16
    override val baseUrl = "https://api.example.com"
17
    override val enableLogging = false
18
    override val enableStrictMode = false
19
}

然后在 Dagger / Koin 等 DI 容器中注入对应的实现。

4.4 在 AndroidManifest 中区分#

1
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
    <application
3
        android:label="${appLabel}"
4
        android:networkSecurityConfig="@xml/network_security_config_dev">
5
        <!-- 允许明文流量（开发环境需要） -->
6
        <uses-library android:name="..." />
7
    </application>
8
</manifest>
9

10
<!-- src/main/res/xml/network_security_config_dev.xml -->
11
<network-security-config>
12
    <domain-config cleartextTrafficPermitted="true">
13
        <domain includeSubdomains="true">localhost</domain>
14
        <domain includeSubdomains="true">10.0.2.2</domain>
15
    </domain-config>
16
    <debug-overrides>
17
        <trust-anchors>
18
            <certificates src="system" />
19
            <certificates src="user" />  <!-- 信任用户安装的证书（抓包用） -->
20
        </trust-anchors>
21
    </debug-overrides>
22
</network-security-config>

5. 运行时检测方案#

有些情况下，你可能需要在运行时判断环境，而不是依赖编译期注入。

5.1 检测是否开启调试#

1
fun isDebugBuild(context: Context): Boolean {
2
    return (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
3
}
4

5
// 使用
6
if (isDebugBuild(this)) {
7
    Log.d("Debug", "当前 App 开启了 debuggable 标志")
8
}

5.2 检测是否从 Google Play 安装#

1
fun isFromPlayStore(context: Context): Boolean {
2
    val installer = context.packageManager.getInstallerPackageName(context.packageName)
3
    return installer == "com.android.vending"
4
        || installer == "com.google.android.feedback"
5
}

5.3 检测应用签名是否与发布签名一致#

1
import android.content.pm.PackageManager
2
import java.security.MessageDigest
3

4
fun isReleaseSignature(context: Context): Boolean {
5
    val releaseSignature = "A1:B2:C3:D4:..."  // 正式签名的 SHA-1
6

7
    return try {
8
        val packageInfo = context.packageManager.getPackageInfo(
9
            context.packageName,
10
            PackageManager.GET_SIGNING_CERTIFICATES
11
        )
12
        val signatures = packageInfo.signingInfo.apkContentsSigners
13
        val currentSignature = signatures.map { sig ->
14
            val md = MessageDigest.getInstance("SHA-1")
15
            md.digest(sig.toByteArray()).joinToString(":") {
16
                "%02X".format(it)
17
            }
18
        }.firstOrNull() ?: ""
19

20
        currentSignature.equals(releaseSignature, ignoreCase = true)
21
    } catch (e: Exception) {
22
        false
23
    }
24
}

5.4 检测是否为模拟器#

1
fun isEmulator(): Boolean {
2
    return (Build.FINGERPRINT.startsWith("generic")
3
        || Build.FINGERPRINT.startsWith("unknown")
4
        || Build.MODEL.contains("google_sdk")
5
        || Build.MODEL.contains("Emulator")
6
        || Build.MODEL.contains("Android SDK built for x86")
7
        || Build.MANUFACTURER.contains("Genymotion")
8
        || (Build.BRAND.startsWith("generic") && Build.DEVICE.startsWith("generic"))
9
        || "google_sdk" == Build.PRODUCT)
10
}

5.5 检测是否 Root#

1
fun isDeviceRooted(): Boolean {
2
    // 检测常见的 su 二进制文件
3
    val suPaths = arrayOf(
4
        "/system/bin/su",
5
        "/system/xbin/su",
6
        "/system/sbin/su",
7
        "/sbin/su",
8
        "/vendor/bin/su",
9
        "/data/local/su",
10
        "/data/local/bin/su",
11
        "/data/local/xbin/su"
12
    )
13
    return suPaths.any { path -> File(path).exists() }
14
}

6. Content Provider 自动初始化#

有些库（如 LeakCanary、Stetho）利用 Content Provider 的自动初始化特性，在 Application 启动前就完成初始化。

1
class DevInitProvider : ContentProvider() {
2

3
    override fun onCreate(): Boolean {
4
        val context = context ?: return false
5
        if (BuildConfig.DEBUG) {
6
            // 在 Application.onCreate() 之前自动初始化
7
            Stetho.initializeWithDefaults(context)
8
            LeakCanary.install(context as Application)
9
        }
10
        return true
11
    }
12

13
    override fun query(...): Cursor? = null
14
    override fun getType(...): String? = null
15
    override fun insert(...): Uri? = null
16
    override fun delete(...): Int = 0
17
    override fun update(...): Int = 0
18
}

1
<provider
2
    android:name=".DevInitProvider"
3
    android:authorities="${applicationId}.DevInitProvider"
4
    android:exported="false" />

注意：${applicationId} 可以配合 flavor 的 applicationIdSuffix，让不同环境的 Provider 不受影响。

7. 综合实践：一套完整的方案#

以下是一套推荐的最佳实践：

7.1 Gradle 配置#

1
android {
2
    flavorDimensions += "environment"
3

4
    productFlavors {
5
        create("dev") {
6
            dimension = "environment"
7
            applicationIdSuffix = ".dev"
8
            buildConfigField("String", "ENV", "\"dev\"")
9
        }
10
        create("prod") {
11
            dimension = "environment"
12
            buildConfigField("String", "ENV", "\"prod\"")
13
        }
14
    }
15

16
    buildTypes {
17
        debug {
18
            isDebuggable = true
19
        }
20
        release {
21
            isMinifyEnabled = true
22
            proguardFiles(...)
23
        }
24
    }
25
}

7.2 统一的环境管理类#

1
object Environment {
2

3
    enum class Type {
4
        DEV, PROD
5
    }
6

7
    val type: Type get() = when (BuildConfig.ENV) {
8
        "dev" -> Type.DEV
9
        else -> Type.PROD
10
    }
11

12
    val isDebug: Boolean get() = type == Type.DEV || BuildConfig.DEBUG
13

14
    val baseUrl: String get() = when (type) {
15
        Type.DEV -> "https://dev-api.example.com"
16
        Type.PROD -> "https://api.example.com"
17
    }
18
}

7.3 使用示例#

1
class MyApp : Application() {
2

3
    override fun onCreate() {
4
        super.onCreate()
5

6
        when (Environment.type) {
7
            Environment.Type.DEV -> {
8
                Timber.plant(Timber.DebugTree())
9
                StrictMode.enableDefaults()
10
            }
11
            Environment.Type.PROD -> {
12
                Timber.plant(ReleaseTree())
13
                CrashReport.init(this)
14
            }
15
        }
16

17
        initRetrofit(Environment.baseUrl)
18
    }
19
}

8. 总结对比#

方案	一句话描述	适合谁
`BuildConfig.DEBUG`	最快速的方式，零配置	个人项目、简单场景
自定义 BuildConfig 字段	灵活注入常量	需要自定义环境标识
Product Flavor	官方正解，一套代码多套应用	正式项目、多环境部署
运行时检测	兜底方案	安全校验、特殊需求
Content Provider	自动初始化	第三方 SDK

推荐路径：小项目直接用 BuildConfig.DEBUG，正规项目上 Product Flavor，再搭配 BuildConfig.DEBUG 做双重判断，完美覆盖所有场景。

音乐

音乐

前言#

1. 方案总览#

2. BuildConfig.DEBUG：最简单的方案#

2.1 使用#

2.2 内部原理#

2.3 局限性#

3. 自定义 BuildConfig 字段#

3.1 添加自定义字段#

3.2 在代码中使用#

3.3 封装为枚举#

4. Product Flavor：多环境构建的正确姿势#

4.1 定义 Flavor#

4.2 Flavor + BuildType 的组合#

4.3 按 Variant 存放资源#

4.4 在 AndroidManifest 中区分#

5. 运行时检测方案#

5.1 检测是否开启调试#

5.2 检测是否从 Google Play 安装#

5.3 检测应用签名是否与发布签名一致#

5.4 检测是否为模拟器#

5.5 检测是否 Root#

6. Content Provider 自动初始化#

7. 综合实践：一套完整的方案#

7.1 Gradle 配置#

7.2 统一的环境管理类#

7.3 使用示例#

8. 总结对比#

参考资料#

文章分享

评论区