Xcode 專案

若你想保留現有的 .xcodeproj 或 .xcworkspace 不變，並在不採用專案生成的情況下引入 Tuist 的功能，請遵循此路徑。以下每個章節都會先說明目前缺少的功能，再逐步引導你使用能填補該空缺的功能。

必要條件#

• macOS 搭配 Xcode 26 或更新版本（編譯快取與現代化洞察功能皆依賴此版本）。
• Tuist 命令列介面。

連接專案#

在儲存庫根目錄執行 tuist init。當 Tuist 偵測到你的工作區時，選擇 整合 <YourApp>，接著在瀏覽器中進行驗證，並選擇應擁有該專案的帳號。Tuist 會在根目錄寫入一個 Tuist.swift，將專案控制代碼固定下來，讓你的團隊成員與 CI 共用相同的連線。請提交此檔案。

若你是透過程式碼代理程式或腳本來執行，請先執行 tuist auth login（瀏覽器流程會等待你按下 Enter），然後使用非互動式形式：

以下內容均為可選且彼此獨立。

Xcode 編譯快取#

Xcode 26 內建了以檔案為單位的編譯快取，但其儲存位置位於機器的 DerivedData 內。全新建置會在本地填充該快取；但團隊成員與 CI 執行器因為看不到該儲存區，所以會從頭重新建置。

tuist setup cache 會將 Xcode 的編譯快取指向共用的 Tuist 快取網路。任何開發者機器或 CI 執行中的快取命中，都能讓其他建置相同修訂版本的機器受益。

此指令會印出 Xcode 使用共用快取所需的建置設定。它不會編輯你的專案，因此請將這些設定加入專案的建置設定或 .xcconfig 檔案中，詳情請參閱 設定 Xcode 建置設定。

在 Xcode 中建置，然後在第二台機器或 CI 執行器上建置相同的修訂版本。第二次建置只需極短時間即可完成，且 Xcode 的建置報告會顯示編譯快取的命中情況。

建置洞察#

Xcode 會在記錄檔與建置報告中記錄每個目標的建置持續時間。但這些數據並未跨執行或跨機器進行彙總。導致建置時間回歸的問題若出現在某個 PR 中，通常只會體現為整體 CI 變慢，而沒有明顯訊號指出是哪個目標造成問題或發生時間。

建置洞察會記錄每次建置的持續時間與階段耗時，讓趨勢能在儀表板上清晰可見。這只需在你的 Scheme 中加入一行後置動作：

1. 在 Xcode 中：Product → Scheme → Edit Scheme…

2. 展開 Build → Post-actions，點擊 +，選擇 New Run Script Action。

3. 在 Provide build settings from 下方，選擇你的 App 目標。

4. 貼上符合你安裝 Tuist 方式的指令行： ::: code-group

   bash

   $HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build
   bash

   tuist inspect build

   :::

   Xcode 的 Scheme 腳本不會繼承你 Shell 的 PATH，因此無法自動找到 mise 的 shim。上述 Mise 指令行透過絕對路徑呼叫 mise，並要求它從 $SRCROOT 載入設定，以便選用你專案中固定的版本。

5. 執行一次建置。該建置會在幾秒內出現在儀表板的 Builds 分頁中。

測試洞察#

Xcode 的測試記錄會逐次列出每次執行的個別測試結果。它並未彙總你真正需要的跨執行訊號：測試失敗的頻率、上週變慢了多少、是否僅在特定模擬器上失敗。一個在十次 CI 執行中從穩定逐漸變成不穩定的測試，看起來與单次運氣不好的執行並無二致。

測試洞察會記錄每次測試的結果與持續時間，並跨執行關聯結果。緩慢的測試、失敗與不穩定情況會顯示在儀表板的 Tests 分頁中。

1. Product → Scheme → Edit Scheme…
2. Test → Post-actions → + → New Run Script Action。
3. Provide build settings from 選擇你的 App 目標。
4. 貼上： ::: code-group
   bash

   $HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect test
   bash

   tuist inspect test
   :::
5. 執行一次測試動作。結果會出現在儀表板的 Tests 分頁中。

套件洞察#

IPA 的安裝與下載大小會隨著每次加入的資源與連結的符號而變化。Xcode 僅在 Product → Show Archive 中按需報告大小，而非作為一系列數據呈現。在合併佇列中，加入大型資源的 PR 與其他 PR 並無區別。

套件洞察會記錄每次分析建置的安裝與下載大小，並在超過每分支閾值時使 PR 檢查失敗。請在建置步驟之後立即將此指令加入你的 CI：

在儀表板上開啟 Bundle insights 以查看趨勢並設定閾值。

預覽#

TestFlight 在每次分享時都會增加建置與審查的往返流程。直接傳送簽名的 .ipa 則需要在佈建設定檔中包含接收者的 UDID。對於只想嘗試當前分支的設計人員或 QA 來說，這兩種方式都不夠方便。

Previews 能將建置轉換為可分享的連結，只需一個指令即可在模擬器或裝置上執行：

傳送該連結。接收者可透過 tuist run <url> 或 Tuist macOS App 執行它。

邀請團隊成員加入#

快取與洞察的效益會隨著連接至專案的人數增加而累積。從儀表板的帳戶設定中邀請隊友加入組織，並設定 Single Sign-On（Google、Okta、Microsoft），讓入職流程只需點擊一下，而非每人執行一次 tuist auth login。

下一步#

若你發現此路徑已不足以應付需求，最大的進展是採用 Tuist 產生的專案。這是一項實質的變更（目標改由 Swift 清單描述，而非 .xcodeproj），但正是它解鎖了模組快取與選擇性測試。Generated Xcode project 指南提供了端到端的完整說明。