asc-xcode-build

Xcode 建置與匯出

當你需要從原始碼建置 App 並準備上傳至 App Store Connect 時，使用此技能。當 asc xcode archive 和 asc xcode export 適用於專案時，優先使用它們，而非原始的 xcodebuild 指令。

前置條件

• 已安裝 Xcode 和命令列工具。
• 簽署身份和描述檔可用，或已啟用自動簽署。
• 當需要上傳或查詢建置編號時，已設定 App Store Connect 驗證。

管理版本與建置編號

asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version edit --next-build-number --app "APP_ID" --platform IOS
asc xcode version bump --type build
asc xcode version bump --type patch
asc xcode version bump --type build --next-build-number --app "APP_ID" --platform IOS

當不在專案根目錄執行時，使用 --project-dir "./MyApp"。當目錄包含多個專案時，使用 --project "./MyApp/App.xcodeproj"。在多目標或多組態專案中，使用 --target "App" 和 --configuration "Release" 以確保讀寫的確定性。

為避免因建置編號過低而被拒絕，請在一個指令中解析並套用遠端安全的建置編號：

asc xcode version edit --next-build-number --app "APP_ID" --platform IOS --output json

版本修改會在寫入前驗證完整變更，並傳回結構化輸出，標示出哪些組態和檔案已變更。編輯器會遞迴處理 xcconfig 包含，並保留不相關的專案和 xcconfig 內容。若只想查看遠端安全值而不修改專案，請單獨使用 asc builds next-build-number。

建議的 iOS/tvOS/visionOS 建置流程

1. 使用 asc 封存

asc xcode archive \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=iOS \
  --output json

對於僅有專案的 App，請使用 --project "App.xcodeproj" 取代 --workspace。

2. 使用 asc 匯出

預設情況下，asc xcode export 會產生 App Store Connect 匯出選項並使用自動簽署。它使用本機匯出目的地，除非設定了 --wait，此時會使用直接上傳：

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --output json

當需要審查、重複使用或手動簽署時，請單獨產生 plist：

asc xcode export-options generate \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --output-path ".asc/ExportOptions.plist" \
  --output json

對於手動簽署，請加上 --signing-style manual 並選擇性加上 --team-id "TEAM_ID"。現有檔案需要 --overwrite。

若要透過 Xcode 直接上傳並等待 App Store Connect 處理，請省略 --export-options 並加上 --wait：

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --wait \
  --output json

3. 上傳或發布

上傳已匯出的 IPA：

asc builds upload --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --wait

發佈到 TestFlight：

asc publish testflight --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --group "GROUP_ID" --wait

發佈到 App Store：

asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait
asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait --submit --confirm

macOS App Store 流程

使用輔助工具封存：

asc xcode archive \
  --project "MacApp.xcodeproj" \
  --scheme "MacApp" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/MacApp.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=macOS \
  --output json

如果你的 macOS 匯出產生 .pkg，請使用 Xcode 匯出搭配你的 ExportOptions.plist，然後上傳套件：

xcodebuild -exportArchive \
  -archivePath ".asc/artifacts/MacApp.xcarchive" \
  -exportPath ".asc/artifacts/MacAppExport" \
  -exportOptionsPlist "ExportOptions.plist" \
  -allowProvisioningUpdates

asc builds upload \
  --app "APP_ID" \
  --pkg ".asc/artifacts/MacAppExport/MacApp.pkg" \
  --version "1.0.0" \
  --build-number "123" \
  --wait

對於 .pkg 上傳，--version 和 --build-number 是必要的，因為它們不像 IPA 中繼資料那樣自動擷取。

原始 xcodebuild 備用方案

僅在 asc xcode archive --help 或 asc xcode export --help 無法涵蓋專案特定選項時，才使用原始 xcodebuild。優先透過 --xcodebuild-flag 傳遞額外引數。

xcodebuild -showBuildSettings -scheme "App"

疑難排解

匯出時找不到對應 Bundle ID 的描述檔

• 在 asc xcode export 中加入 --xcodebuild-flag=-allowProvisioningUpdates。
• 確認 Apple ID 已登入 Xcode。
• 使用 asc-signing-setup 技能驗證描述檔。

CFBundleVersion 過低

asc xcode version edit --next-build-number --app "APP_ID" --platform IOS

然後重新建置並上傳。

因缺少 macOS 圖示而被拒絕

macOS 需要包含所有必要尺寸的 ICNS 圖示。修正素材目錄，重新建置，然後再次匯出/上傳。

備註

• 優先使用 asc xcode archive 和 asc xcode export 以取得確定性的本機成品。
• 僅在有意取代現有本機成品時使用 --overwrite。
• 當下一步驟依賴已處理的建置時，在上傳/發布路徑上使用 --wait。
• 關於提交準備狀態，請使用 asc-submission-health。