Xcode避坑指南

Signing Issues

• - "Automatic" signing still needs team selected — set in Signing & Capabilities
• Provisioning profile mismatch — bundle ID must match exactly, including case
• "No signing certificate" — open Keychain, check certificate is valid and not expired
• Device not registered — add UDID in developer portal, regenerate profile
• CI/CD needs manual signing — automatic doesn't work in headless builds

Derived Data Corruption

• - Random build failures after Xcode update — delete INLINECODE0
• "Module not found" but it exists — clean Derived Data, restart Xcode
• Stale cache symptoms — builds work, then fail, then work again
• INLINECODE1 not enough — sometimes must delete DerivedData manually

Build Settings Hierarchy

• - Project → Target → xcconfig → command line — later overrides earlier
• INLINECODE2 to append not replace — forgetting it removes parent settings
• INLINECODE3 for Swift flags — not INLINECODE4
• INLINECODE5 for Obj-C — add to existing, don't replace

Archive vs Build

• - Archive uses Release config by default — build uses Debug
• "Works in simulator, fails in archive" — check Release build settings
• Archive requires valid signing — build doesn't for simulator
• INLINECODE6 for frameworks — or archive includes them incorrectly

Capabilities and Entitlements

• - Capability in Xcode must match entitlements file — out of sync causes crashes
• Push notifications need both — App ID capability AND provisioning profile
• Associated domains needs apple-app-site-association file — hosted on your server
• Keychain sharing needs explicit group — default is just your app

Dependencies

• - SPM and CocoaPods can conflict — watch for duplicate symbols
• Pod update vs install — install uses Podfile.lock, update ignores it
• "Framework not found" — check Framework Search Paths, embed vs link
• SPM package resolution fails — delete Package.resolved, reset package caches

Common Fixes

• - Build fails with no clear error — check Report Navigator for details
• Simulator stuck — xcrun simctl shutdown all, then INLINECODE10
• Indexing stuck — delete Index folder in DerivedData
• Autocomplete broken — restart Xcode, if persists delete DerivedData

CLI Builds

• - xcodebuild -showBuildSettings to debug — see resolved values
• INLINECODE12 for CI with auto-signing — needs keychain access
• INLINECODE13 must be exact — INLINECODE14
• INLINECODE15 deprecated — use xcrun notarytool for notarization