从 Xcode 设置到发布构建的排查清单
升级了 Xcode，为什么上传仍提示 SDK 不符合要求？把 SDK 升到 26，是不是用户也必须升级到 iOS 26？这两个问题经常被混为一谈。
先给结论：构建 SDK、应用最低系统版本和实际打包机器的工具链，要分别检查。不要只看开发电脑安装了哪个 Xcode，也不要为了满足 SDK 要求，把最低系统版本直接改成同一个数字。本文只讨论 iOS／iPadOS 构建兼容性，不涉及 Google Play 的 target API，也不替代签名、隐私和审核资料检查。
一 先把三个版本分开记录
1. Xcode 版本：完成编译和归档的工具版本。开发电脑、CI 和第三方云打包平台可能各不相同。
2. Base SDK：编译使用的系统头文件和库，对应构建设置 SDKROOT。它决定编译时可以使用哪些系统接口。[3]
3. Minimum Deployment Target：应用声明支持的最低系统版本。iOS 对应 IPHONEOS_DEPLOYMENT_TARGET。使用较新的 SDK，并不意味着最低系统版本必须与 SDK 相同；新接口仍需要适当的可用性判断和旧系统替代逻辑。[5]
例如，“使用 iOS 26 SDK 构建、最低支持 iOS 15”是两个不同维度的描述，不自相矛盾。它也不是对你项目的推荐配置：最终选择还要看工具链支持范围、依赖要求和测试结果。
二 先判断正在满足哪一个日期的要求
以下是 Apple 官方页面截至核验日列出的要求，适用对象是上传至 App Store Connect 的构建，不应推断成所有已上线应用会在当天自动下架。
• 已生效：2026 年 4 月 28 日起，上传 iOS／iPadOS 应用需使用 Xcode 26 或更高版本及相应的 26 系列 SDK。[1]
• 已生效：2026 年 9 月 9 日起，iOS／iPadOS 应用上传时最低目标系统须为 iOS 13 或更高。[1]
• 后续要求：提交页面写明，从 2027 年 4 月起，iOS／iPadOS 应用需使用 27 SDK 或更高版本，并以 iOS 15 或更高版本为最低目标。该页没有给出具体日，不能自行写成 4 月 1 日或沿用上一年的 4 月 28 日。[2]
这里有一个容易漏掉的限制：商店政策的下限，不等于某个 Xcode 版本所支持的部署下限。Apple 的 Xcode 系统要求表把 Xcode 26 的 iOS Deployment Targets 列为 iOS 15–26。[4] 因此不能看到商店页面的“13”，就认为当前工具链一定支持你把项目设成 13。
实际决策要同时满足：商店上传政策、所选 Xcode 支持范围、依赖最低要求，以及你的兼容性测试。发布前重新打开官方页面核对日期，尤其不要把未来要求误当成今天的拒收原因。
三 在真正打包的机器上核对工具链
下面是提供给开发人员的 macOS 终端诊断示例，不需要提供账号、密码或签名私钥。先在本机执行，再在 CI 或云打包任务的日志里取得相同信息。命令是检查模板，本文没有替你的项目实际执行。
xcode-select --print-path xcodebuild -version xcodebuild -showsdks
第一项查看命令行工具指向的位置，第二项记录 Xcode 版本和 build version，第三项查看可用 SDK。路径检查的依据见 Apple 命令行文档；具体选项也可在相应机器运行 xcodebuild -help 核对。[7]
检查结果时，按下面顺序处理：
• 路径指向旧 Xcode：确认发布任务选择的是预期安装，而不是只在图形界面打开了新版本。
• 路径是 /Library/Developer/CommandLineTools：不要把独立命令行工具包当成完整 iOS 打包环境，核对完整 Xcode 安装及其选择。[7]
• 本机合格，云端仍报旧 SDK：要求打包平台提供“本次任务”的版本和日志，不接受“平台已支持最新 Xcode”作为本次产物的证明。
• CI 设置了 DEVELOPER_DIR 或显式指定构建环境：将该配置与实际版本输出一起检查，避免只看系统默认路径。
编辑建议：每次发布保留一份环境记录，写明提交版本、构建号、代码提交标识、打包任务编号及上述输出。之后排查时，先定位具体产物，不在不同机器之间反复猜测。
四 查发布配置的最终值 不只查项目默认值
在 Xcode 选择项目，再选择对应 target，进入 Build Settings，搜索 IPHONEOS_DEPLOYMENT_TARGET 和 SDKROOT。若当前显示人类可读标题，可通过 Editor → Show Setting Names 切换设置名称；Levels 视图中的 Resolved 列有助于查最终生效值。[6]
重点检查实际归档使用的配置。很多项目使用 Release，但自定义 scheme 可能使用其他配置。不要仅确认 Debug，也不要只改 Project 层而漏掉 target 或 xcconfig 覆盖。
需要把结果交给同事时，可以用下面的模板导出设置。先替换项目路径、scheme 和实际归档配置；只有 .xcodeproj 的项目，将 -workspace 参数改为 -project，并使用项目文件名。
xcodebuild -list -workspace "YourApp.xcworkspace" xcodebuild -showBuildSettings \ -workspace "YourApp.xcworkspace" \ -scheme "YourApp" \ -configuration "Release" \ -destination "generic/platform=iOS" \ > build-settings.txt
在输出中逐个检查主 App、随包扩展及相关依赖 target 的 SDKROOT 和 IPHONEOS_DEPLOYMENT_TARGET。这里是在读取构建设置，不是证明已经成功归档；查询过程中也可能触发项目依赖解析，应在正常开发环境执行。[6][7][8]
如果输出与界面不一致，先核对 workspace、scheme、configuration、destination 是否相同，再查 xcconfig 和 CI 命令行覆盖。Apple 文档明确指出，命令行传入的构建设置具有最高优先级。[6] 不建议为了消掉警告，直接把所有依赖的 deployment target 批量强改成同一个数字。
五 依赖要求更高时 不要只改声明
假设你的应用计划支持 iOS 15，但某个 SDK 新版要求 iOS 16。此时仅把应用或依赖配置文件里的数字改成 15，并不能让该 SDK 自动兼容旧系统。
先建一个最小依赖核对表：依赖名称、锁定版本、供应商文档链接、最低系统要求、是否包含二进制框架、升级后受影响的业务流程。Swift Package Manager 会检查依赖与顶层包的部署版本兼容性；依赖所需最低版本不能高于顶层包的最低版本。[9]
可讨论的方案有三类，均需开发评估：
• 采用仍受维护、满足合规与安全要求的兼容版本，而不是无限期锁死旧库。
• 升级应用最低系统版本，同时评估受影响用户，安排产品说明和测试。
• 移除或替换该依赖，重新验证相应业务流程。
自己的代码调用新系统 API 时，可通过 #available 等方式分支处理，但必须实现可用的旧系统路径。[5] 这不等于能绕过一个二进制 SDK 自身的最低系统要求。尤其要验证广告、登录、支付、推送等启动或关键流程中的依赖，不只看首页能否打开。
六 用最终归档和安装测试完成闭环
设置检查通过后，用实际发布 scheme 和配置重新归档。不要继续上传升级工具链前留下的旧 IPA。
最终归档中的应用 Info.plist 可用于核对 MinimumOSVersion。Apple 说明该键由 Xcode 根据部署目标写入，不应通过手工修改它伪装兼容性。[10] 记录时同时保存该归档对应的构建日志、版本号和构建号；单独一张设置截图无法证明上传的是这个包。
下面是编辑建议的发布验收清单，不是 Apple 官方规定的固定测试数量：
• 环境：归档任务的 Xcode／SDK 输出符合当前上传要求，且没有误用旧缓存产物。
• 配置：主 App 与扩展的最终设置经过核对，依赖版本与锁文件对应。
• 产物：归档中 MinimumOSVersion 与发布计划一致；上传文件可追溯到本次归档。
• 最低支持系统：在可获得的对应真机或合适测试环境完成首次安装、冷启动、登录和核心功能；缺少真机覆盖要明确记录，不能填“已通过”。
• 当前系统：检查权限弹窗、页面布局、后台返回，以及实际使用的支付／广告／推送等链路。
• 升级安装：从上一公开版本升级到候选版本，核对本地数据、登录态与数据库迁移。
• 上传结果：保存 App Store Connect 的处理结果及具体错误；本地能编译，不代表构建已被接收，更不代表审核已通过。
如果出现问题，区分三种情况再整改：旧 SDK 提示先查实际构建环境；依赖最低版本冲突先查依赖兼容性；仅旧系统崩溃则结合日志查 API 可用性、依赖和运行时行为。不要把三种问题都归为“苹果审核严格”。
七 可以直接复用的内部交接模板
应用名称与 Bundle ID： 版本号／构建号： 代码提交标识与打包任务编号： 实际 Xcode 版本及 build version： 实际 SDK 与环境日志位置： 归档 scheme／configuration： 计划最低系统版本： 归档 MinimumOSVersion： 有最低系统限制的第三方依赖与版本： 最低系统测试设备／系统／结果： 当前系统及升级安装测试结果： App Store Connect 处理结果与错误原文： 尚未验证的项目、负责人及处理计划：
问题找早鸟出海，早鸟出海（NBOVERSEA）深耕出海近十年。专业提供谷歌、苹果APP代上架服务，支持PWA/W2A/H5/APP广告代投，提供Google/Facebook/Tiktok广告账户，谷歌/苹果开发者账户，一站式解决您的后顾之忧。如有任何疑问，请点击服务流程或咨询飞机：@nboversea