身為 iOS 開發者，你是否也曾為重複的 App 打包與分發流程感到厭煩？這篇文章將帶你從零開始，運用強大的 Fastlane 工具，實現自動化打包（Archive）並將 .ipa 檔案上傳至 Firebase App Distribution。我將詳細記錄每一步安裝過程，並在文末分享我如何解決那些惱人的權限與環境配置問題。
- 第一步：安裝 Fastlane 與 Firebase CLI
Fastlane 是基於 Ruby 的工具。最推薦且最穩定的安裝方式是透過 Homebrew，它可以為我們建立一個獨立的開發環境，避免與 macOS 系統的 Ruby 產生衝突。
安裝 Homebrew
首先，在終端機中執行以下指令來安裝 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安裝 Fastlane
Homebrew 安裝完成後，直接使用它來安裝 Fastlane。這種方式會自動處理好 Ruby 和環境變數（PATH）的問題。
brew install fastlane安裝完成後，你可以用以下指令來確認 Fastlane 是否成功安裝：
which fastlane
fastlane --version
安裝 Firebase CLI
Fastlane 需要 Firebase CLI 來執行上傳。雖然有多種安裝方式，但我們同樣推薦使用 Homebrew。
官方安裝文件
這裡我們使用 Homebrew安裝 Firebase CLI。
brew install firebase-cli
安裝好後，接著要登入你的 Google 帳號。在終端機執行 firebase login，它會自動開啟瀏覽器，引導你完成登入。
- 第二步：初始化 Firebase CLI & 連結Firebase專案
登入成功後，接著要在專案內建立Firebas的檔案連結，先將終端機路徑移動到專案目錄底下
cd /path/to/your/project
執行firebase init
firebase會跳出一些選項，要設定一些firebase的服務，這裡我們選擇 Extensions: Set up an empty Extensions manifest 即可，按下空白鍵選取，Enter確認。
之後他會問使用哪一個專案，選擇要使用的專案即可。
以上都完成之後執行指令
firebase use就會看見已經選擇連結的專資訊，到這裡我們的第二步也完成了。
- 第三步: Fastlane初始化
在前面我們已經把 Fastlane 成功安裝，再來需要在 iOS 專案中進行Fastlane初始化設定。 在我們的專案目錄底下執行
fastlane init選擇設定方式：Fastlane 會給出四個選項，我們選擇 4. Manual setup。
初始化完成後：
- 驗證專案 Gem 環境
- 進入你的專案目錄，執行
bundle check。 - 如果一切設定正確，這個指令會顯示
The Gemfile's dependencies are satisfied。這表示 bundle 已經成功安裝了 Gemfile 裡所定義的所有 Gem。
- 進入你的專案目錄，執行
- 驗證 Fastlane 檔案
- 檢查你的專案目錄中，是否多了一個名為 fastlane 的資料夾。
- 這個資料夾內應該包含 Appfile 和 Fastfile 這兩個檔案。
如果以上所有驗證都成功，恭喜你，你的專案現在已經可以開始使用 Fastlane 了。至於初始化過程中遇到的問題與修復，我將在文章的結尾補充說明。
- 第四部: 撰寫自動化腳本
在你的專案目錄下，找到 fastlane/Fastfile 並用你慣用的文字編輯器打開它。接著，寫下我們自動化部署的腳本。
以下是一個完整的範例，你可以直接參考並根據你的專案來修改：
# Uncomment the line if you want fastlane to automatically update itself
# update_fastlane
default_platform(:ios)
platform :ios do
desc "Deploys a new version to Firebase App Distribution"
lane :beta do
# 1. 編譯你的 app
#
# 請根據你的專案設定修改這些參數
build_app(
workspace: "my_project.xcworkspace", # 如果你使用 Cocoapods，就用 .xcworkspace
scheme: "my_project", # 你的 Xcode Scheme 名稱
configuration: "Release",
clean: true, # 在執行 build_app 指令時，它會先執行一個 xcodebuild clean 的操作
export_method: "ad-hoc"
)
# 2. 上傳到 Firebase App Distribution
#
# 請將以下參數替換成你的實際資訊
firebase_app_distribution(
app: "1:953554247597:ios:...", # 你的 Firebase App ID
firebase_cli_path: "/opt/homebrew/bin/firebase", # Firebase CLI 的安裝路徑
release_notes: "新增自動化部署功能。",
groups: "testers" # 你的測試群組名稱
)
end
end
當你完成 Fastfile 的設定後，你只需要在終端機中，執行這行簡單的指令：
bundle exec fastlane betaFastlane 就會自動幫你完成 App 打包、簽名、並上傳到 Firebase App Distribution！恭喜你，你的自動化部署流程已經大功告成！
結語：那些惱人的問題與我的突破
老實說，這次 Fastlane 的安裝和設定，一路上真的踩了不少雷。本來以為用 Homebrew 這種自動化工具會很順，結果還是遇到一堆奇奇怪怪的問題。不過沒關係，我把這些搞死人的問題和最後怎麼解決的都整理出來了，希望對你也有幫助！
問題一：fastlane init 時的權限地獄
- 問題描述：當我執行
fastlane init時，卻收到 Something went wrong when running 'bundle update' for you 的錯誤。Fastlane 嘗試在我的使用者目錄~/.local/share/建立 Gem 環境，但就是沒權限寫入。 - 根本原因：原來，即使 Fastlane 本身透過 Homebrew 安裝成功，但它在初始化專案時，會呼叫 Bundler。而 Bundler 預設會嘗試在
~/.local/share/下建立一個專案獨立的 Gem 環境，這個路徑可能沒有寫入權限。 - 我的解決方案： 我發現可以在
fastlane init之前，先手動為 Fastlane 建立所需的目錄並賦予我完整的權限。這兩行指令最終解決了這個權限問題：sudo mkdir -p /Users/letao/.local/share/fastlane/3.4.0
接著，為了徹底根除 Bundler 的權限問題，我還設定了 Bundler 的全域安裝路徑，讓它將所有 Gem 都安裝到我完全掌控的
sudo chown -R $USER /Users/letao/.local/share/fastlane~/.bundle目中：bundle config set --global path '~/.bundle'
最後，我執行bundle install，確保所有 Gem 依賴都正確安裝。
問題二：fastlane 執行時的 Ruby 版本警告
- 問題描述：當我執行
bundle exec fastlane beta時，看到了 abbrev was loaded from the standard library, but is not part of the default gems starting from Ruby 3.4.0 的警告，以及 bundler: failed to load command: fastlane 的錯誤。 - 根本原因：這是 Ruby 3.4.0 版本的一個變化，abbrev 不再是預設 Gem。bundler 無法載入 fastlane 指令，通常是因為它找不到 Fastlane 執行所需的 Ruby 程式碼。
- 我的解決方案：在 Gemfile 中明確加入
gem "abbrev"，然後重新執行bundle install，確保所有 Gem 依賴都已正確設定。
問題三：Xcode 找不到路徑
- 問題描述：在
build_app階段，Fastlane 報錯說 Unable to locate Xcode。但我明明安裝了 Xcode。 - 根本原因：此錯誤的原因是 Xcode 的檔名不同我的Xcode檔名是Xcode_16.2.app，Fastlane 無法在預設路徑找到它。
- 我的解決方案：我需要明確地告訴系統我的 Xcode 在哪裡，將路徑指向實際的檔名即可。
sudo xcode-select --switch /Applications/Xcode_16.2.app
問題四：firebase_app_distribution 動作找不到
- 問題描述：
build_app成功了，但 Fastlane 卻說 Could not find action, lane or variable 'firebase_app_distribution'。 - 根本原因：firebase_app_distribution 是一個 Fastlane 的外掛 (plugin)，而不是內建動作。它需要被額外安裝，Fastlane 才能辨識並使用它。
- 我的解決方案：透過
fastlane add_plugin指令來安裝這個外掛。bundle exec fastlane add_plugin firebase_app_distribution
```add_plugin` 這個指令會自動幫我下載並安裝外掛，並將它加入到我的 `Gemfile` 和 `Gemfile.lock` 中。
雖然 Fastlane 這次設定真的是環境問題一推，但每解決一個問題，都讓我對 Ruby 環境和這些工具的原理更了解了一點。最後看到 App 順利自動打包上傳到 Firebase，那感覺真是太爽了！希望這篇文能幫你少走點彎路，讓你的自動化部署之路更順暢！
