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并配置好命令行工具
  • 拥有有效的签名身份和配置文件（或已启用自动签名）

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

3. 上传PKG

macOS apps export as 
.pkg
files. Use 
xcrun altool
:
bash
xcrun altool --upload-app \
  -f "/tmp/YourMacAppExport/YourApp.pkg" \
  --type macos \
  --apiKey "$ASC_KEY_ID" \
  --apiIssuer "$ASC_ISSUER_ID"
Note: The API key file must be in 
~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8
macOS应用导出为
.pkg
文件。使用
xcrun altool
：
bash
xcrun altool --upload-app \
  -f "/tmp/YourMacAppExport/YourApp.pkg" \
  --type macos \
  --apiKey "$ASC_KEY_ID" \
  --apiIssuer "$ASC_ISSUER_ID"
注意：API密钥文件必须放在
~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8
路径下

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

导出时出现“No profiles for bundle ID”（无对应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（1x和2x分辨率）

CFBundleVersion too low

CFBundleVersion版本过低

The build number must be higher than any previously uploaded build. Increment 
CURRENT_PROJECT_VERSION
and rebuild.
构建版本号必须高于之前所有已上传的版本。请递增
CURRENT_PROJECT_VERSION
并重新构建。

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
    技能