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 也會回報相同數值，但僅在構件上傳之後。

套件洞察會記錄每個 .aab（建議）或 .apk 的安裝與下載大小，並在超過每分支閾值時讓 PR 檢查失敗。在建置步驟之後立即將此行加入你的 CI：

bash

tuist inspect bundle App.aab

開啟儀表板上的 套件洞察 → Android 以查看趨勢並設定閾值。

Play Console 的內部測試軌道在每次分享時都會增加審查與傳播延遲。透過 Slack 或電子郵件傳送原始 .apk 較快，但會失去追蹤特定訊息所指涉的建置。

此外掛程式可直接建置並發布應用程式變體，無需額外的 CLI 上傳：

bash

./gradlew :app:tuistShareDebug --track nightly

請求 tuistShare<Variant> 任務會讓該次呼叫納入發布；一般建置絕不會上傳預覽。參閱 Gradle 預覽以了解支援的 APK、簽署與安裝。

快取命中、洞察與壓力測試的效果會隨著連接至專案的人數增加而累積。從儀表板的帳號設定邀請隊友加入組織，並設定單一登入（Google、Okta、Microsoft），讓入職只需點擊一下，而非每人執行一次 tuist auth login。

CI 請勿使用個人登入。使用 CI 供應商的 OIDC 身分進行驗證，或在儀表板中以 CI 預設建立帳號權杖，並將其設為 TUIST_TOKEN。參閱 Gradle 外掛程式驗證。

此處涵蓋的內容是在 Gradle 專案上從 Tuist 獲得價值的最小必要設定。tuist 擴充區塊、stressNewTests 模式與 CI 驗證的設定選項詳見安裝 Gradle 外掛程式參考文件。