Back to Details

asc-xcode-build

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xcode Build and Export

Xcode 构建与导出

Use this skill when you need to build an app from source and prepare it for upload to App Store Connect.
当你需要从源码构建应用并准备上传至App Store Connect时，使用本技能。

Preconditions

前置条件

  • Xcode installed and command line tools configured
  • Valid signing identity and provisioning profiles (or automatic signing enabled)
  • 已安装Xcode并配置好命令行工具
  • 拥有有效的签名身份和配置文件（或已启用自动签名）

Manage version and build numbers with 
asc

使用
asc
管理版本号与构建号

Before archiving, prefer 
asc xcode version ...
over manual 
pbxproj
edits when you need to inspect or bump app versions.
bash
asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version bump --type build
asc xcode version bump --type patch
Notes:
  • Use 
    --project-dir "./MyApp"
    when you are not running from the project root.
  • Use 
    --target "App"
    for deterministic reads in multi-target projects.
  • These commands support both legacy 
    agvtool
    projects and modern 
    MARKETING_VERSION
    / 
    CURRENT_PROJECT_VERSION
    setups.
在归档之前，当你需要查看或更新应用版本时，优先使用
asc xcode version ...
命令，而非手动编辑
pbxproj
文件。
bash
asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version bump --type build
asc xcode version bump --type patch
注意事项：
  • 如果不是从项目根目录运行命令，请使用
    --project-dir "./MyApp"
    参数。
  • 在多目标项目中，使用
    --target "App"
    参数以确保读取的确定性。
  • 这些命令同时支持传统
    agvtool
    项目和现代
    MARKETING_VERSION
    / 
    CURRENT_PROJECT_VERSION
    配置。

iOS Build Flow

iOS 构建流程

1. Clean and Archive

1. 清理并归档

bash
xcodebuild clean archive \
  -scheme "YourScheme" \
  -configuration Release \
  -archivePath /tmp/YourApp.xcarchive \
  -destination "generic/platform=iOS"
bash
xcodebuild clean archive \
  -scheme "YourScheme" \
  -configuration Release \
  -archivePath /tmp/YourApp.xcarchive \
  -destination "generic/platform=iOS"

2. Export IPA

2. 导出IPA文件

bash
xcodebuild -exportArchive \
  -archivePath /tmp/YourApp.xcarchive \
  -exportPath /tmp/YourAppExport \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates
A minimal 
ExportOptions.plist
for App Store distribution:
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store-connect</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
</dict>
</plist>
bash
xcodebuild -exportArchive \
  -archivePath /tmp/YourApp.xcarchive \
  -exportPath /tmp/YourAppExport \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates
用于App Store分发的极简
ExportOptions.plist
：
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store-connect</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
</dict>
</plist>

3. Upload with asc

3. 使用asc上传

bash
asc builds upload --app "APP_ID" --ipa "/tmp/YourAppExport/YourApp.ipa"
bash
asc builds upload --app "APP_ID" --ipa "/tmp/YourAppExport/YourApp.ipa"

macOS Build Flow

macOS 构建流程

1. Archive

1. 归档

bash
xcodebuild archive \
  -scheme "YourMacScheme" \
  -configuration Release \
  -archivePath /tmp/YourMacApp.xcarchive \
  -destination "generic/platform=macOS"
bash
xcodebuild archive \
  -scheme "YourMacScheme" \
  -configuration Release \
  -archivePath /tmp/YourMacApp.xcarchive \
  -destination "generic/platform=macOS"

2. Export PKG

2. 导出PKG文件

bash
xcodebuild -exportArchive \
  -archivePath /tmp/YourMacApp.xcarchive \
  -exportPath /tmp/YourMacAppExport \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates
bash
xcodebuild -exportArchive \
  -archivePath /tmp/YourMacApp.xcarchive \
  -exportPath /tmp/YourMacAppExport \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates

3. Upload PKG with asc

3. 使用asc上传PKG文件

macOS apps export as 
.pkg
files. Upload with 
asc
:
bash
asc builds upload \
  --app "APP_ID" \
  --pkg "/tmp/YourMacAppExport/YourApp.pkg" \
  --version "1.0.0" \
  --build-number "123"
Notes:
  • --pkg
    automatically sets platform to 
    MAC_OS
    .
  • For 
    .pkg
    uploads, 
    --version
    and 
    --build-number
    are required (they are not auto-extracted like IPA uploads).
  • Add 
    --wait
    if you want to wait for build processing to complete.
macOS应用会导出为
.pkg
文件，使用
asc
上传：
bash
asc builds upload \
  --app "APP_ID" \
  --pkg "/tmp/YourMacAppExport/YourApp.pkg" \
  --version "1.0.0" \
  --build-number "123"
注意事项：
  • --pkg
    参数会自动将平台设置为
    MAC_OS
    。
  • 上传
    .pkg
    文件时，
    --version
    和
    --build-number
    为必填参数（不像IPA上传那样会自动提取）。
  • 如果需要等待构建处理完成，请添加
    --wait
    参数。

Build Number Management

构建号管理

Each upload requires a unique build number higher than previously uploaded builds.
In Xcode project settings:
  • CURRENT_PROJECT_VERSION
    - build number (e.g., "316")
  • MARKETING_VERSION
    - version string (e.g., "2.2.0")
Check existing builds:
bash
asc builds list --app "APP_ID" --platform IOS --limit 5
每次上传都需要一个比之前上传版本更高的唯一构建号。
在Xcode项目设置中：
  • CURRENT_PROJECT_VERSION
    - 构建号（例如："316"）
  • MARKETING_VERSION
    - 版本字符串（例如："2.2.0"）
查看已有的构建版本：
bash
asc builds list --app "APP_ID" --platform IOS --limit 5

Troubleshooting

故障排查

"No profiles for bundle ID" during export

导出时出现“无对应Bundle ID的配置文件”错误

  • Add 
    -allowProvisioningUpdates
    flag
  • Verify your Apple ID is logged into Xcode
  • 添加
    -allowProvisioningUpdates
    参数
  • 验证你的Apple ID已登录Xcode

Build rejected for missing icon (macOS)

构建因缺少图标被拒绝（macOS）

macOS requires ICNS format icons with all sizes:
  • 16x16, 32x32, 128x128, 256x256, 512x512 (1x and 2x)
macOS要求ICNS格式的图标包含所有尺寸：
  • 16x16、32x32、128x128、256x256、512x512（1倍和2倍分辨率）

CFBundleVersion too low

CFBundleVersion过低

The build number must be higher than any previously uploaded build. Increment it with 
asc xcode version bump --type build
, or resolve a remote-safe number with 
asc builds next-build-number --app "APP_ID" --version "2.2.0" --platform IOS
and then apply it with 
asc xcode version edit --build-number "NEXT_BUILD"
before rebuilding.
构建号必须高于之前上传过的任何版本。使用
asc xcode version bump --type build
命令递增构建号，或者使用
asc builds next-build-number --app "APP_ID" --version "2.2.0" --platform IOS
获取一个安全的远程可用构建号，然后在重新构建前使用
asc xcode version edit --build-number "NEXT_BUILD"
应用该构建号。

Notes

注意事项

  • Always clean before archive for release builds
  • Use 
    xcodebuild -showBuildSettings
    to verify configuration
  • For submission issues (encryption, content rights), see 
    asc-submission-health
    skill
  • 发布版本构建前务必先执行清理操作
  • 使用
    xcodebuild -showBuildSettings
    验证配置
  • 若遇到提交问题（加密、内容权限等），请查看
    asc-submission-health
    技能