重點整理：

這篇文章介紹了如何將 Turborepo 部署到 Vercel，並使用 Vercel Remote Caching 來加快 CI/CD 工作流。Turborepo 是一個高效能的建構系統，特別適合管理 monorepo。文章提供了有關環境變數的處理、如何導入到 Vercel、設定遠端快取等相關細節。

1. Turborepo 的優點

• 增量構建：只重新構建變更的文件，節省時間。
• 內容感知快取：根據文件內容生成快取，只要內容相同就不重新構建。
• 遠端快取：團隊共享快取，加快 CI/CD 管道。

2. 環境變數的處理

• 在 turbo.json 中定義環境變數，避免在不同環境中使用錯誤的快取。
• 使用 env 和 globalEnv 支援環境變數，確保構建過程依賴於正確的環境變數。

範例：

{
  "pipeline": {
    "build": {
      "env": ["SOME_ENV_VAR"],
      "outputs": ["dist/**"]
    },
    "web#build": {
      "env": ["SOME_OTHER_ENV_VAR"],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  },
  "globalEnv": ["GITHUB_TOKEN"]
}

3. 導入到 Vercel

• 在 Vercel 上創建新專案並導入 Turborepo。
• Vercel 自動處理 monorepo 的構建命令、輸出目錄等設定。

預設命令：

Build Command: turbo run build
Output Directory: Framework default

4. 忽略未變更的構建

• 使用 npx turbo-ignore --fallback=HEAD^1 在忽略構建步驟中確保只構建有變更的應用程式。

5. 設定遠端快取

• 遠端快取允許共享構建結果並加速工作流。
• 使用 npx turbo login 和 npx turbo link 連接到 Vercel 的遠端快取，並在所有專案中啟用遠端快取。

範例：

npx turbo login
npx turbo link

6. 測試遠端快取

• 透過執行 turbo run build 來測試遠端快取功能。快取會儲存在本地和遠端，並加速構建過程。

7. 處理快取未命中的問題

• 確保 turbo.json 中的輸出目錄設定正確，並符合框架預設的輸出目錄。

範例：

{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

範例程式碼

1. 設定 turbo.json 處理環境變數

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["SOME_ENV_VAR"],
      "outputs": ["dist/**"]
    },
    "web#build": {
      "env": ["SOME_OTHER_ENV_VAR"],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  },
  "globalEnv": ["GITHUB_TOKEN"],
  "globalDependencies": ["tsconfig.json"]
}

2. 忽略無變更的構建

npx turbo-ignore --fallback=HEAD^1

3. 連結 Vercel 遠端快取

npx turbo login
npx turbo link

8. 在 Vercel 中使用遠端快取

Vercel 提供了 Remote Caching 功能，它可以自動在整個團隊中共享構建結果，並應用於 CI/CD 管道。當團隊成員在相同的分支上工作時，遠端快取會識別構建結果並在不同的機器上重複使用這些結果，避免不必要的重複構建和測試。

9. 遠端快取的啟用與測試

當 Vercel 專案與 Turborepo 相連後，遠端快取 將自動啟用，無需額外配置。當你在 Vercel 架設的構建過程中使用 turbo 指令時，構建結果將會儲存在遠端，並在其他相同條件下的構建過程中被重複使用。這不僅加速了整個構建過程，還可以節省時間和資源。

範例：

turbo run build

此指令將構建你的專案，同時本地和遠端都會存儲構建結果。當你再次進行變更並執行同一命令時，Turborepo 只會重新構建有變更的部分，大大提高了效率。

10. 將遠端快取應用於外部 CI/CD 系統

如果你想在外部 CI/CD 系統（如 Jenkins、GitHub Actions 等）中使用 Vercel Remote Caching，你可以透過設置環境變數來啟用這個功能：

• TURBO_TOKEN：Vercel 的訪問令牌。
• TURBO_TEAM：共享快取的 Vercel 團隊名稱。

一旦這些環境變數在你的 CI/CD 系統中設置完成，Turborepo 會自動使用 Vercel 的遠端快取來存儲任務結果。

11. 移除遠端快取的連結

如果某個開發者想要停止使用 Vercel 的遠端快取功能，可以在本地運行以下指令來解除遠端快取的連結：

npx turbo unlink

這是針對每位開發者執行的動作，因此每個想要取消遠端快取的成員都必須手動執行該指令。

12. 本地開發與環境變數

在開發過程中，Vercel 的 .env.local 文件用來管理本地環境變數，這些變數只會在開發過程中使用，並不會提交到版本控制中。你可以使用 vercel env pull 指令，從 Vercel 的專案中自動下載並創建 .env 文件。

範例：

vercel env pull

這個指令會自動將 Vercel 專案中的環境變數下載到本地，並創建一個 .env 文件。

13. 處理構建輸出問題

當你遇到構建快取命中，但輸出文件找不到的情況時，請檢查以下內容：

• 確保你的輸出目錄與框架預設的輸出路徑相符。
• 在 turbo.json 中正確設定 outputs 鍵，並確保輸出目錄與構建任務相符。

範例：

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "outputs": [
        // Next.js
        ".next/**", "!.next/cache/**",
        // SvelteKit
        ".svelte-kit/**", ".vercel/**",
        // Build Output API
        ".vercel/output/**",
        // 其他框架
        ".nuxt/**", "dist/**", "other-output-directory/**"
      ]
    }
  }
}

這樣可以避免因為快取命中但輸出文件不存在而導致的構建失敗。

14. 快取命中問題的調試

如果你在 Vercel 中使用 Turborepo 時，發現快取命中問題，Turborepo 會自動收集所有相關的構建信息來幫助你調試快取未命中的原因。在 Turborepo Run Summary 中，你可以看到每個任務的執行時間、快取狀態以及任務哈希（task hash）生成的所有數據，幫助你了解哪些變更導致了快取未命中。

你可以在 Vercel 的部署頁面中查看這些摘要，幫助快速定位問題。

15. 遠端快取的使用

Vercel 的 Remote Caching 是一項強大功能，可以幫助團隊共享構建結果，避免重複執行相同任務。它可應用於所有團隊成員和 CI/CD 管道，並且可以加速整個工作流程，節省大量時間。

總結

Turborepo 與 Vercel 的結合為 monorepo 提供了高效的構建解決方案，通過使用遠端快取、增量構建和內容感知快取來提升構建速度。在 Vercel 上使用 Turborepo 不僅能自動優化工作流，還能在團隊中共享快取結果，減少重複構建，提升團隊協作效率。