# Gradle 預覽

直接從 Gradle 建置並分享 Android 應用程式與原生命令列工具。請先參閱<.localized_link href="/guides/get-started/gradle-project">Gradle 專案指南</.localized_link>，以連接專案並完成驗證。

## Android 應用程式

```bash
./gradlew :app:tuistShareDebug
```

`dev.tuist` 設定外掛程式會為 Android Gradle Plugin（8.8.2 或更新版本）中的每個應用程式變體註冊一個`tuistShare<Variant>`工作。將`app`與`Debug`替換為你的應用程式模組與變體，例如產品風味可使用`:app:tuistShareDemoDebug`。此工作會在發布前透過 Gradle 宣告的構件相依性來建置 APK。當建置輸出已是最新狀態或從建置快取還原時，此工作也能正常運作。

僅支援單一、已簽署且通用的應用程式 APK。Android 的 debug 變體通常使用除錯簽署金鑰；release 變體則需要你自己的簽署設定。此工作會在驗證或上傳前檢查 APK 簽章。未簽署、無效、檢測用以及分割的 APK 都會被拒絕。程式庫模組、測試 APK 與 Android App Bundle（`.aab`）並非發布目標。

## 原生命令列工具

使用 Gradle `cpp-application`或`swift-application`外掛程式的專案，會為每個原生二進位檔取得一個分享工作：

```bash
./gradlew :app:tuistShareMainDebug
```

此工作會建置並封裝已安裝的發行版，包含其啟動器與執行時期函式庫。若要處理 release 二進位檔，請使用`tuistShareMainRelease`。針對多部機器的專案，每個二進位檔都有一個對應工作；請執行`./gradlew :app:tasks --all`以查詢它們的名稱。

支援 arm64 或 x86_64 的原生 macOS 與 Linux 可執行檔。請在目標平台上，使用 Gradle 外掛程式所需的工具鏈進行建置。JVM 應用程式及其產生的啟動器指令碼不受此整合支援。

## 發布行為

分享工作會使用外掛程式現有的 Tuist 憑證進行發布，無需叫用 Tuist CLI。一般的`assemble`、`build`與測試工作絕不會發布預覽。

分享後，請在專案中開啟**預覽**以複製連結。重複分享相同的建置與軌道會複用其發布內容，即使在快取命中後亦然。上傳失敗或未確認的上傳會導致分享工作失敗；這些情況不會被回報為成功的預覽。

## CI 與軌道

使用與外掛程式其他需驗證功能相同的憑證來設定<.localized_link href="/guides/integrations/continuous-integration">CI 驗證</.localized_link>，然後明確要求發布：

```bash
./gradlew :app:tuistShareDebug --track nightly
```

以相同方式將`--track nightly`加入原生分享工作。工作會使用已設定的 Tuist 專案、伺服器 URL 與代理設定。預覽發布一律需要驗證。Git 修訂元資料、版本說明與自動拉取請求註解不會由這些工作附加。

在託管式 Tuist 上，構件發布會在 30 天後過期。自託管實例使用`TUIST_APP_PREVIEW_RETENTION_DAYS`；若未設定，則為此系列停用過期。已過期的發布無法透過重複相同意圖來恢復。

## 分享現有 APK

若 APK 是在此工作流程之外建置，或希望在舊版上傳流程中加入版本說明，仍可使用 CLI：

```bash
tuist share app/build/outputs/apk/debug/app-debug.apk \
  --track nightly --release-notes "Improve checkout"
```

請參閱<.localized_link href="/guides/features/previews#run-a-preview">執行預覽</.localized_link>，了解如何執行已發布的建置、存取權限、軌道與 README 徽章。

## 使用 tuist share 追蹤版本 {#share-tracks}

若工作流程使用 `tuist share` 發布，請使用 `--track` 選擇追蹤版本：

```bash
tuist share App --track beta
tuist share App --track nightly
```

## 發行說明 {#release-notes}

使用追蹤版本區分環境群組，並為個別建置提供發行說明：

```bash
tuist share App --track QA --release-notes "Fix sign-in and improve the checkout flow"
```

將 `App` 替換為你的應用程式名稱、應用程式檔案路徑或可執行檔散發套件及其 `--executable` 選項。發行說明為選填的純文字，最多 10,000 個字元。第一行非空白內容會在預覽清單中以單行摘要顯示，讓建置編號與其他識別資訊一目了然。過長的行會被截斷；完整說明會顯示在詳細頁面。搜尋結果會比對顯示名稱與完整發行說明，包含未在摘要中顯示的行。支援多行說明，例如 `--release-notes "$(< release-notes.txt)"`。這不會改變應用程式的顯示名稱或其追蹤版本。

### 相容性 {#preview-metadata-compatibility}

發行說明不會改變建置所屬的預覽。預覽接收的第一筆說明會被保留：後續上傳可以為尚未有說明的預覽新增說明，但無法覆寫或清除既有說明。在發行說明功能推出前上傳的預覽仍然有效，不需補充說明。

自行託管的部署需要支援發行說明與追蹤版本篩選的伺服器版本，以及更新後的用戶端。較舊的伺服器會忽略這些說明。關於清單端點的追蹤版本與搜尋篩選器，請參閱 [API 參考文件](https://tuist.dev/api/docs)。

## Pull/Merge Request 留言 {#pullmerge-request-comments}

> [!WARNING]
> **需要整合 Git 平台**
>
> 若要自動在 Pull/Merge Request 中留下留言，請將你的 <.localized_link href="/guides/server/accounts-and-projects">遠端專案</.localized_link> 與 Git 平台整合：<.localized_link href="/guides/integrations/gitforge/github">GitHub</.localized_link>、<.localized_link href="/guides/integrations/gitforge/origin">Cursor Origin</.localized_link> 或 <.localized_link href="/guides/integrations/gitforge/entire">Entire</.localized_link>。

當你的 Tuist 專案與 Git 平台連接後，在 CI 成功建置應用程式後加入 <.localized_link href="/cli/share">`tuist share`</.localized_link>。Tuist 會直接在 Pull/Merge Request 中張貼預覽連結，讓審查者無需在本機建置即可測試：

![包含 Tuist Preview 連結的 GitHub App 留言](/images/guides/features/github-app-with-preview.png)

## 自動化 {#automations}

使用 `--json` 從 `tuist share` 取得 JSON 輸出：

```bash
tuist share --json
```

將結果用於自訂自動化流程，例如從 CI 發送 Slack 訊息。`url` 鍵包含完整的預覽連結；`qrCodeURL` 指向 QR Code 圖片，可在裝置上開啟預覽：

```json
{
  "id": 1234567890,
  "url": "https://tuist.dev/preview/1234567890",
  "qrCodeURL": "https://tuist.dev/preview/1234567890/qr-code.svg"
}
```

