Gradle 项目

plaintext

Help me get started with Tuist. Follow the setup at:
https://tuist.dev/en/docs/guides/get-started/gradle-project

按照此路径将现有的 Gradle 项目接入 Tuist。dev.tuist Gradle 插件会将 Gradle 的本地构建缓存连接到 Tuist 的远程缓存，并将构建和测试数据上传到仪表板，而无需更改任何 ./gradlew 命令。

以下每个部分首先说明当前缺失的内容，然后引导你了解填补这一空白的功能。

前提条件#

在 Gradle 项目的根目录下运行 tuist init。选择 集成 Gradle 项目，然后在浏览器中完成身份验证，并选择应拥有该项目的账户。

bash

tuist init

如果你通过编码代理或脚本执行此操作，请先运行 tuist auth login（浏览器流程会等待你按 Enter 键），然后使用非交互式形式：

bash

tuist init --build-system gradle --name <project-handle> --account <account>

Tuist 会在仓库根目录写入包含项目句柄的 tuist.toml，并输出一个 plugins { ... } 块。将其粘贴到 settings.gradle.kts 的顶部：

kotlin

plugins {
    id("dev.tuist") version "0.18.1"
}

使用 ./gradlew help 进行健全性检查。Gradle 应该无错误加载。如果找不到插件，请确保该块位于 settings.gradle.kts 中，而不是 build.gradle.kts。

以下内容均为可选且相互独立。

Gradle 的本地构建缓存将任务输出存储在生成它们的机器上。同一分支上的两名开发者只会命中各自 ~/.gradle 中的缓存，而不会命中对方的缓存；CI 每次作业都会命中一个全新的空缓存。

Tuist 远程缓存扩展了 Gradle 已在跨机器使用的相同键/值协议。任务的输出会在首次执行它的机器上上传，并由其他遇到相同输入的任何机器下载。在 gradle.properties 中启用它：

plaintext

org.gradle.caching=true

然后在两个环境中构建：

bash

./gradlew clean build --build-cache --info

可缓存的任务在第二次运行时会报告 FROM-CACHE。打开仪表板上的缓存查看随时间变化的命中率。

Gradle 在构建结束时发出任务计时信息，并使用 --profile 生成每次构建的 HTML 报告。两者都不会跨运行聚合数据。在一系列提交中逐渐变慢的任务，在任何单次构建的报告中看起来都与以往一样。

一旦应用了 dev.tuist 插件，它会自动将每次构建的任务计时上传到仪表板。无需额外配置。在下一次 ./gradlew build 之后，打开仪表板上的构建查看趋势。

Gradle 的测试报告位于每次构建的 build/reports/tests/ 下。在十次 CI 运行中间歇性失败的测试，在任何给定报告中看起来都像是一个偶然失败一次的稳定测试。

测试洞察记录每次 ./gradlew test 运行中每个任务的结果和持续时间，并跨运行关联结果。不稳定测试、慢速测试和失败会显示在仪表板的测试选项卡上。当不稳定测试积累时，从仪表板隔离它们，以便它们不再阻止合并。

该插件还支持 压力测试模式，它会重新运行构建引入的测试用例，并在它们合并之前标记任何被证明不稳定的用例。将其添加到 settings.gradle.kts 中的 tuist 扩展：

kotlin

tuist {
    stressNewTests {
        mode = "report" // or "enforce"
    }
}

Android Gradle Plugin 会在构建输出中报告生成的 .aab 的大小。该数字会随着分支消失，跨版本比较大小是一项手动统计工作。Play Console 会报告相同的数字，但仅在构件上传之后。

Bundle 洞察记录每个 .aab（推荐）或 .apk 的安装和下载大小，并可以在超过每分支阈值时使 PR 检查失败。将此步骤添加到构建步骤之后的 CI 中：

bash

tuist inspect bundle App.aab

打开仪表板上的 Bundle 洞察 → Android 查看趋势并配置阈值。

Play Console 的内部测试轨道会在每次分享时增加审查和传播延迟。通过 Slack 或电子邮件发送原始 .apk 更快，但无法追踪特定消息引用的是哪个构建。

该插件可以直接构建并发布应用变体，无需单独的 CLI 上传：

bash

./gradlew :app:tuistShareDebug --track nightly

请求 tuistShare<Variant> 任务会使该次调用参与发布；普通构建从不上传预览。有关支持的 APK、签名和安装，请参阅 Gradle 预览。

缓存命中、洞察和压力测试的效果会随着连接到项目的人数增加而累积。从仪表板的账户设置邀请团队成员加入组织，并设置单点登录（Google、Okta、Microsoft），使入职只需点击一下，而不是每人执行一次 tuist auth login。

对于 CI，不要使用个人登录。使用 CI 提供商的 OIDC 身份进行身份验证，或在仪表板中使用 CI 预设创建账户令牌，并将其设置为 TUIST_TOKEN。请参阅 Gradle 插件身份验证。

此处涵盖的所有内容是在 Gradle 项目中从 Tuist 获得价值的最小要求。tuist 扩展块、stressNewTests 模式和 CI 身份验证的配置选项详见安装 Gradle 插件参考。