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 下方，選擇你的應用程式目標。

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 你的應用程式目標。
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 應用程式運行它。

帶團隊一起加入#

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

下一步#

如果你超越了這個階段，最大的一步是採用 Tuist 產生的專案。這是一個實質的改變（目標在 Swift 清單中描述，而非 .xcodeproj），但它能解鎖模組快取和選擇性測試。Generated Xcode project 指南涵蓋了端到端的完整流程。