Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Lightbuild 配置参考文档

Lightbuild 项目的 build 配置由 YAML 文件组成：项目根目录中的 project.lightbuild.yaml 文件，以及每个模块中的 lightbuild.yaml 文件。本页面介绍了每个文件中的设置。

项目文件

全局项目设置位于项目根目录中的 project.lightbuild.yaml 文件内。例如：

project:
  name: MyApp

modules:
  - app
  - app-core

repositories:
  - google
  - mavenCentral

lightbuild:
  version: 0.0.30

build:
  java:
    version: 17
  kotlin:
    version: 2.3.20
  jvmTarget: "17"

下表介绍了这些设置：

设置	说明
`project.name`	项目的名称，例如 `MyApp`。Android Studio 会将此名称显示为 Project 窗口的根目录。与 Kotlin DSL 中的 `rootProject.name` 一样，它与应用的名称和应用 ID 是分开的。
`modules`	项目中的模块，例如应用模块 (`app`) 和库模块 (`app-core`)。
`repositories`	Lightbuild 从中解析依赖项的远程仓库。如需了解详情，请参阅代码库。
`lightbuild.version`	项目使用的 Lightbuild 版本。
`build.kotlin.version`	项目使用的 Kotlin 版本。
`build.java.version`	项目所需的 Java 编译器版本。
`build.jvmTarget`	生成的 JVM 字节码的目标版本。

代码库

使用 repositories 列出 Lightbuild 从中解析依赖项的代码库。您可以列出内置的 google 和 mavenCentral 制品库，并使用 maven 添加自定义 Maven 仓库：

repositories:
  - google
  - mavenCentral
  - maven:
      name: "Example Repo"
      url: "https://maven.example.com/releases"

maven 代码库具有以下设置：

设置	说明
`name`	代码库的名称。
`url`	代码库的网址。
`credentials`	可选。`local.properties` 文件中映射到代码库用户名和密码的密钥。如需了解详情，请参阅代码库凭证。

仓库凭证

如果 Maven 仓库需要用户名和密码，请向该仓库添加 credentials 代码块。username 和 password 值不是凭据本身，而是您在项目的 local.properties 文件中定义的键：

repositories:

  - google
  - mavenCentral
  - maven:
      name: "Internal Repo"
      url: "https://maven.example.com/releases"
      credentials:
        username: internalRepoUser
        password: internalRepoPassword

然后，在项目的 local.properties 文件中，将每个键映射到其值。将 REPO_USERNAME 和 REPO_PASSWORD 替换为您的凭证：

# Also define sdk.dir, the path to your Android SDK.
internalRepoUser=REPO_USERNAME
internalRepoPassword=REPO_PASSWORD

模块文件

每个模块的目录中都有一个 lightbuild.yaml 文件，用于定义模块的设置。下表介绍了顶级设置：

设置	说明
`platform`	模块的目标平台：`android`。
`type`	模块类型：`application` 表示应用模块，`library` 表示库模块。如需了解详情，请参阅 Lightbuild 项目结构。
`optionalFeatures`	要为模块启用的可选功能，例如用于支持协议缓冲区的 `com.android.tools.lightbuild.protobuf`。如需了解详情，请参阅协议缓冲区。
`android`	模块的 Android 设置。如需了解详情，请参阅 Android 设置。

Android 设置

android 代码块包含模块的 Android build 设置：

设置	说明
`namespace`	模块的命名空间。如需了解详情，请参阅设置命名空间。
`compileSdk`	模块编译时所针对的 API 级别。如需了解详情，请参阅 SDK 版本。
`minSdk`	模块支持的最低 API 级别。
`targetSdk`	应用的目标 API 级别。仅在应用模块中受支持。
`applicationId`	应用的 ID。在应用模块中设置。
`versionCode`	应用的版本代码。在应用模块中设置。
`versionName`	应用的版本名称。在应用模块中设置。
`packaging`	用于打包应用的 `debug` 和 `release` build 的设置，例如发布签名。仅在应用模块中受支持。如需了解详情，请参阅打包。
`dependencies`	模块对其他模块和外部库的依赖关系。如需了解详情，请参阅依赖项。
`kspProcessors`	为模块生成代码的 KSP 处理器。如需了解详情，请参阅 KSP 处理器。
`tests`	模块的本地测试和插桩测试。如需了解详情，请参阅测试。

SDK 版本

在 version.release.apiLevel 下将 compileSdk、minSdk 和 targetSdk 设置指定为 API 级别。例如，以下设置会针对 API 级别 36 编译模块，支持 API 级别 24 及更高级别，并以目标 API 级别 36 为目标平台：

android:
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36

只有应用模块支持 targetSdk 设置。库模块仅定义 compileSdk 和 minSdk 设置。

依赖项

在 dependencies 代码块中声明模块的依赖项：

module：项目中的其他模块，写作 // 后跟模块名称，例如 //app-core 或 //features/search。
maven：外部库，以 Maven 坐标的形式编写，格式为 group:artifact:version。

例如，以下设置会添加对 app-core 模块和 AndroidX Core KTX 库的依赖项：

android:
  dependencies:
    module:
      - //app-core
    maven:
      - androidx.core:core-ktx:1.18.0

依赖项设置

默认情况下，模块会针对其每个依赖项进行编译，并在运行时包含这些依赖项，但不会将其公开给依赖于它的模块。如需更改模块使用依赖项的方式，请在依赖项后添加英文冒号，然后在下方添加 compile 设置、runtime 设置或同时添加这两项设置：

android:
  dependencies:
    module:
      - //data:
          compile: public
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.annotation:annotation:1.9.1:
          runtime: off

在此示例中，依赖于此模块的模块也可以使用 data 模块的类。Jetpack 注解库仅用于编译此模块。Core KTX 使用默认设置。

compile 设置用于控制哪些模块会针对依赖项进行编译：

private（默认）：此模块会针对依赖项进行编译，但依赖于此模块的模块不会。
public：此模块和依赖于它的模块会针对该依赖项进行编译。当模块的公共 API 使用依赖项中的类型时，请使用 public。
off：此模块不会针对依赖项进行编译。

runtime 设置用于控制依赖项在运行时是否可用：

public（默认）：此模块以及依赖于此模块的模块在运行时可以使用该依赖项。
off：依赖项在运行时不可用。对于代码仅在编译时间需要的依赖项（例如注解），请使用 off。

compile 和 runtime 不能同时为 off。在测试依赖项中，compile 只能是 private 或 off。

如需了解这些设置如何与 Kotlin DSL 配置（例如 api 和 compileOnly）对应，请参阅比较 Lightbuild 与 Kotlin DSL。

KSP 处理器

如需使用基于 Kotlin 符号处理 (KSP) 的代码生成器（例如 Moshi 或 Room），请将处理器添加到 kspProcessors 代码块中，并将代码在运行时使用的库添加到 dependencies 代码块中。Lightbuild 会自动应用 KSP 插件，并在构建期间配置代码生成。

例如，以下设置会使用 Moshi 的 KSP 代码生成器配置 Moshi：

android:
  dependencies:
    maven:
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2

协议缓冲区

如需从库模块中的协议缓冲区 (.proto) 文件生成代码，请将协议缓冲区功能添加到模块的 optionalFeatures 列表中，并将协议缓冲区运行时库添加到模块的依赖项中。optionalFeatures 是一个顶级设置，位于 android 代码块之外：

optionalFeatures:
  - com.android.tools.lightbuild.protobuf

android:
  dependencies:
    maven:
      - com.google.protobuf:protobuf-javalite:4.28.2
      - com.google.protobuf:protobuf-kotlin-lite:4.28.2

将模块的 .proto 文件放入其 src/main/proto 目录中。构建模块时，Lightbuild 会为 Protocol Buffers Lite 运行时生成 Java 和 Kotlin 类，这是 Android 的推荐做法。

测试

在 tests 代码块中配置模块的测试：

test：在开发机器的 JVM 上运行的本地测试。在 dependencies 下列出测试的依赖项。
androidTest：在设备或模拟器上运行的插桩测试。将 runner 设置为测试运行程序类，并在 dependencies 下列出测试的依赖项。

例如：

android:
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test.ext:junit:1.3.0
          - androidx.test.espresso:espresso-core:3.7.0

包装

在应用模块中，使用 packaging 代码块配置应用的 debug 和 release build。如需使用您自己的密钥为发布 build 签名，请向 release 配置文件添加 signing 代码块：

android:
  packaging:
    release:
      signing:
        storeFile: "${RELEASE_STORE_FILE}"
        storePassword: "${RELEASE_STORE_PASSWORD}"
        keyAlias: "${RELEASE_KEY_ALIAS}"
        keyPassword: "${RELEASE_KEY_PASSWORD}"

signing 块支持以下设置：

storeFile：密钥库文件的路径，相对于模块的目录，或以 ~/ 开头（表示主目录中的位置）。
storePassword：密钥库的密码。
keyAlias：密钥库中签名密钥的别名。
keyPassword：签名密钥的密码。

为避免将密码存储在项目文件中，请使用 ${NAME} 语法将这些值设置为环境变量引用，如示例所示。您可以直接写入 storeFile 和 keyAlias，也可以引用它们的环境变量。在您构建时，Lightbuild 会将每个引用替换为环境变量的值。每个值都必须仅包含引用：Lightbuild 不会替换属于较长值一部分的引用，例如 ${HOME}/upload-keystore.jks。

示例

以下示例展示了应用模块和库模块的完整模块文件。

应用模块

以下 app/lightbuild.yaml 文件配置了一个依赖于 app-core 库模块的应用模块：

platform: android
type: application
android:
  namespace: com.example.myapp.app
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36
  applicationId: com.example.myapp
  versionCode: 1
  versionName: "1.0"
  dependencies:
    module:
      - //app-core

库模块

以下 app-core/lightbuild.yaml 文件配置了一个库模块，该模块使用 Jetpack Compose 和 Moshi，并包含本地测试和插桩测试：

platform: android
type: library
android:
  namespace: com.example.myapp
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  dependencies:
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.lifecycle:lifecycle-runtime-ktx:2.10.0
      - androidx.activity:activity-compose:1.13.0
      - androidx.lifecycle:lifecycle-runtime-compose:2.10.0
      - androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0
      - androidx.compose.ui:ui:1.10.4
      - androidx.compose.ui:ui-tooling-preview:1.10.4
      - androidx.compose.material3:material3:1.4.0
      - androidx.navigation3:navigation3-ui:1.0.1
      - androidx.navigation3:navigation3-runtime:1.0.1
      - androidx.lifecycle:lifecycle-viewmodel-navigation3:2.10.0
      - androidx.compose.ui:ui-tooling:1.10.4
      - androidx.compose.ui:ui-test-manifest:1.10.4
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
          - org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test:core:1.7.0
          - androidx.test.ext:junit:1.3.0
          - androidx.test:runner:1.7.0
          - androidx.test.espresso:espresso-core:3.7.0
          - androidx.compose.ui:ui-test-junit4:1.10.4

为你推荐

注意：当 JavaScript 处于关闭状态时，系统会显示链接文字
Lightbuild 项目结构
从命令行构建 Lightbuild 项目
Lightbuild 与 Kotlin DSL 比较