fastlane deliver 上傳 App Store：API Key 還是 Apple ID？2026

fastlane deliver 可用於 App Store Connect 的應用程式發布工作；fastlane 文件亦列出 API Key 在相關工具中的支援情況。不過，API Key 尚未覆蓋所有 fastlane 工具。請以你實際呼叫的 action 為單位查核，不要只確認 deliver 的一項操作，就推論同一套認證可完成所有發布工作。fastlane 的 App Store Connect API 支援清單與 deliver action 文件應一起檢視。

先把工作流拆開，再做選擇：

• 上傳建置檔：確認目前執行的 fastlane action，以及實際使用的上傳路徑；API Key 支援與二進位檔傳輸是兩個需要分別驗證的環節。
• 更新商店資料：列出要修改的文字、媒體與應用程式資訊，再確認 deliver 使用的認證方式和所需權限。
• TestFlight 或其他發布工作：不要假設另一個 action 會自動繼承 deliver 的 API Key 支援。逐項對照 fastlane 文件與 action 參數。
• 其他管理操作：若流程涉及隱私資料等不同功能，應核對該 action 自己的支援說明，例如 fastlane 隱私詳情 action 文件。

Apple 說明 App Store Connect API 透過 JWT 授權；其 token 的有效時間上限為 20 分鐘，要以 exp 設定實際期限。Apple 的 JWT 產生說明提供了必要欄位與有效期規則。這是 API 請求授權的期限，不代表建置檔只需傳輸這段時間，也不代表 App 已完成處理或審核。

API Key 與 Apple ID 不只是兩種登入寫法；它們的授權方式、權限界線及保管責任不同。選擇前，先確認是哪個 Key、哪個角色，以及流程會接觸哪些 App。

• Team Key：依指派角色取得 Team 層級的存取範圍。不要將它視為可按單一 App 隔離的金鑰。
• Individual Key：與建立該 Key 的使用者及其存取權限相關。核對使用者的角色和目標 App，避免人員離職或權限變更後，發布任務才失去存取能力。
• 角色要求：權限應符合實際工作，不要為了排除錯誤而不加判斷地提高整組憑證權限。Apple 列出的建置上傳角色包括 Account Holder、Admin、App Manager 與 Developer；這是上傳建置的要求，不能推論成所有 App Store Connect 操作都使用相同角色。Apple 建立 API Key 的說明及上傳建置的角色要求可供逐項核對。

管理 API Key 時，.p8 是私鑰材料；Key ID 用來識別金鑰，Issuer ID 則用於產生 API 請求所需的授權資訊。Apple 說明私鑰只可下載一次，因此下載後要立即存入受控位置，並安排備份與輪替流程。Apple API Key 建立文件

Apple ID 認證材料則有不同的管理責任。不要把帳號密碼、驗證流程或應用專用密碼寫進程式碼庫，也不要將 .p8、Key ID、Issuer ID 或 Apple ID 秘密值提交到版本控制。把秘密資料設為 CI 秘密變數或受控的憑證項目，限制可讀取的人員；日誌只保留 action、錯誤類型和必要的追蹤資訊，避免輸出認證內容。

注意：範例設定應使用佔位符，例如 ASC_KEY_ID、ASC_ISSUER_ID、ASC_PRIVATE_KEY。不要把可用的私鑰或密碼貼進 Fastfile、專案設定或除錯輸出。

fastlane deliver 可以用 App Store Connect API Key 嗎？可以用於 fastlane 已支援 API Key 的操作；仍須確認你使用的 action 與參數。若同一條 lane 還呼叫其他工具，要逐項確認，不要把其中一個步驟成功當成全流程通過。

fastlane 上傳 App Store 時，哪些操作還可能需要 Apple ID？當你要執行的 fastlane 工具或 action 尚未支援 API Key 時，才針對該工作評估 Apple ID。先查 action 文件及認證說明，不要直接假設上傳二進位檔、修改商店資料和管理其他發布功能使用同一種認證。

遠端 Mac 自動發布應該用哪一種？若所有必要 action 都支援 API Key，優先設定 API Key，並在實際執行環境驗證私鑰讀取與所需角色。若某個必要功能不支援，再為該步驟保留 Apple ID 認證；遠端連線本身不會改變 action 的支援範圍。

API Key 權限不足時先查什麼？依序核對 Team Key 或 Individual Key、指派角色、目標 App 存取範圍，以及失敗的 action 是否支援 API Key。不要先擴大權限；若仍無法判斷，回查 Apple 對該操作的角色要求和 fastlane 對該 action 的認證說明。

API Key 適合用於已支援的自動化操作，因為流程可按金鑰及權限授權，不必把互動式登入當作每次執行的前提。但它並不是所有 fastlane 功能的通用替代品。Apple ID、雙重認證與應用專用密碼各有適用邊界，應按實際 action 的文件核實。fastlane iOS 認證文件說明了 Apple ID 認證及應用專用密碼的相關用法；不能據此把應用專用密碼當成商店資料管理等所有工作的替代認證。

遇到認證錯誤時，先分清是哪一層失敗：

• API Key 無法授權：檢查 Key ID、Issuer ID、私鑰內容、token 設定及角色。
• Apple ID 流程要求互動驗證：確認這個 action 是否支援非互動式認證，以及目前認證材料是否符合文件要求。
• 某 action 不接受 API Key：保留該步驟所需的認證方式，並將其與其餘可使用 API Key 的工作分開。
• 本機可跑、CI 失敗：比較兩邊載入的秘密變數、權限與執行設定，不要先假定是 Apple 端狀態不同。

上傳驗收要把「認證成功」、「二進位檔傳輸完成」、「App Store Connect 已處理建置」及「TestFlight 或審核狀態」分開。Apple 的建置上傳說明涵蓋上傳要求與角色；若使用 Transporter 等路徑，仍要獨立確認傳輸結果，不能把 API Key 授權通過當成建置已處理。Apple 上傳建置說明

部署前，逐項完成以下檢查：

• [ ] 列出 lane 會執行的每一個 fastlane action，為各項記錄認證方式與官方支援依據。
• [ ] 確認 API Key 類型、角色及目標 App 存取範圍符合實際任務；Team Key 不當作單一 App 隔離金鑰。
• [ ] 將 .p8 私鑰、Key ID、Issuer ID 或 Apple ID 認證材料存於受控的秘密儲存位置，並確認程式碼庫與日誌沒有秘密值。
• [ ] 使用脫敏專案執行非正式發布任務，確認遠端 Mac 或 CI 可以讀取所需憑證、呼叫目標 action，且不依賴未預期的互動式登入。
• [ ] 在 App Store Connect 確認對應建置已出現，再查看其處理、TestFlight 或後續審核狀態；記錄每個階段的結果，方便失敗時定位。

如果你目前依賴人工登入，常見代價是執行需要人守候、帳號認證材料集中在個人手上，而且 CI 的可重現性容易受憑證交接影響。自購 Mac 可提供固定的本機環境，但你要自行維護硬體與系統；遠端 Mac 則適合需要持續使用 macOS、又不想為發布任務購買設備的情況，但仍須自行驗證 action 支援與憑證讀取邊界。若要評估發布工作所需的 macOS 環境，可先查看 CALMVPS 的方案資訊，再按你的工作流確認是否適用；若只是偶爾發布或已有可靠的自有 Mac，租用未必是必要選擇。了解方案時，也可參閱 CALMVPS 的使用選項。