Xcode 27 将旧部署目标变成构建错误：新的分界线在这里

打开一个已经稳定构建多年的 Mac 应用项目，切换到 Xcode 27 beta，点击构建，然后卡住：

The macOS deployment target 'MACOSX_DEPLOYMENT_TARGET' is set to 10.13, but the range of supported deployment target versions is 12.0 to 27.0.99.

在 Xcode 26 里，这句话只是一条可以直接划过去的黄色警告。在 Xcode 27 里，它变成了红色错误，构建不会继续。这就是全部改动，但它比听上去的既小又大：说小，是因为 Apple 的文档多年来一直宣称最低支持 macOS 11 和 iOS 15；说大，是因为 Xcode 从来没有真正强制执行过这条线，而大量已上架的应用其实一直悄悄依赖着这个漏洞。

本文梳理 Xcode 27 实际强制执行的范围（依据 Apple 自己的表格和发行说明）、Xcode 26 实际允许的范围（依据我们自己机器上的 SDK）、受影响的人群、能把错误重新变回警告的未记录设置，以及为什么真正要命的截止日期不是 Xcode 27 的发布，而是明年春天 App Store 的 SDK 硬性要求。

关键要点

• Xcode 27 支持的部署目标是 macOS 12–27、iOS/iPadOS/tvOS 15–27、watchOS 9–27、visionOS 1–27、DriverKit 21–27，依据 Apple 针对 beta 6 的 Xcode 支持页面。低于这些版本，构建会失败。
• Xcode 26 文档上写的下限是 macOS 11，但实际接受 10.13。 我们查看了 macOS 26.0 SDK 的设置文件：34 个合法的部署目标，起点是 10.13。Xcode 27 通过让「文档范围」等于「实际强制范围」，堵上了这个缺口。
• macOS 下限在 beta 期间发生过变动。 6 月时，Apple 的说明写的是 Universal 回退部署「一直到并包括 macOS 27」，开发者当时把它理解为 Big Sur。到了 beta 6，说明改成了「macOS 12 及以上」。请按 Monterey 来规划，而不是 Big Sur。
• 存在一个未记录的逃生舱口：__DIAGNOSE_INVALID_DEPLOYMENT_TARGET_AS_ERROR = NO，据报告可以把错误重新变回警告。它不受官方支持，随时可能消失，而且并不能改变 Apple 没有测试过这些旧目标的事实。
• 真正的截止日期是 App Store 的 SDK 要求。 Xcode 26 的 SDK 已于 2026 年 4 月 28 日起成为提交应用的强制要求。如果 Apple 延续这一惯例，Xcode 27 的 SDK 大约会在 2027 年 4 月成为强制要求，届时通过常规渠道在 App Store 应用中支持 macOS 11 或 iOS 14 将不再可能。

官方给出的数字

Apple 的 Xcode 支持页面 发布了一张表格，列出每个 Xcode 版本能构建的目标范围。真正要看的对比是这张表：

平台	Xcode 26.6	Xcode 27 beta 6
macOS	11 – 26.5	12 – 27
iOS / iPadOS	15 – 26.5	15 – 27
tvOS	15 – 26.5	15 – 27
watchOS	8 – 26.5	9 – 27
visionOS	1 – 26.5	1 – 27
DriverKit	20 – 25.5	21 – 27

请仔细看这张表，因为「Xcode 27 提高了下限」这个标题只说对了一半。对 iOS 而言，文档下限在整个 Xcode 26 周期里都是 15，到 Xcode 27 依然是 15。对 macOS 而言，下限只移动了一个版本，从 11 到 12。对 watchOS 而言，从 8 到 9。纸面上看，这只是一次温和的收紧。

纸面上没写的是：Xcode 26 的这些数字从来没有被真正强制执行过。

Xcode 26 实际允许了什么

Xcode 内的每一个 SDK 都带有一个设置文件，声明它认为哪些部署目标是合法的。在我们的机器上，安装的是 Xcode 26.0.1（17A400），该文件位于：

/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/SDKSettings.json

读取它只需要一条命令：

python3 -c '
import json
d = json.load(open("/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/SDKSettings.json"))
t = d["SupportedTargets"]["macosx"]
print(t["MinimumDeploymentTarget"], "->", t["MaximumDeploymentTarget"])
print(len(t["ValidDeploymentTargets"]), "valid:", t["ValidDeploymentTargets"][:6], "...")
'

在 Xcode 26.0.1 上的输出：

10.13 -> 26.0.99
34 valid: ['10.13', '10.14', '10.15', '11.0', '11.1', '11.2'] ...

也就是说，尽管 Apple 的表格写的是「macOS 11」，SDK 内部写的却是「10.13」，Xcode 允许你在部署目标字段里手动输入 10.13，弹出警告，然后照样构建。Michael Tsai 直白地描述了这种做法：开发者「一直能够手动输入更旧的目标」，而不少独立 Mac 软件正是靠这一点，让 High Sierra、Mojave 和 Catalina 用户继续用上最新的构建版本。

如果你已经安装了 Xcode 27 beta，可以对它的 SDK 运行同样的命令（把路径中的 Xcode.app 换成 Xcode-beta.app），你会看到新的下限。我们这台机器上没有装 beta，所以关于「12.0」这个数字，我们依据的是 Apple 的表格和开发者的报告，而不是自己从文件里读出来的。

从警告到错误

这条诊断信息本身并不新。Apple 的构建系统多年来一直会发出「支持的部署目标版本范围是 X 到 Y」这句话，只是作为警告出现。Xcode 27 改变的是它的严重级别。

bleepingswift.com 上的一篇文章 引用了它在 Xcode 27 中的 iOS 版本：

The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to xx.x, but the range of supported deployment targets versions is 15.0 to 27.0.x

macOS 版本的信息内容一样，只是把标识换成 MACOSX_DEPLOYMENT_TARGET，范围是 12.0 到 27.0.99。它是按目标（target）分别触发的，所以一个同时包含扩展、小组件和测试包、且都继承了旧目标的应用，会看到这条信息出现四次，只修好主应用并不能清除构建错误。

Vienna RSS 的维护者 在 6 月 10 日就遇到了这个问题，也就是 beta 发布两天之后：他们的目标是 10.13，在 Xcode 26 上无警告无错误地构建，而在 Xcode 27 上「变成了硬性要求（构建错误）」。他们后续担心的问题，也是所有处在这个位置的 Mac 开发者共同的担心：Xcode 26 预计不会支持 macOS 27，所以「留着旧版 Xcode 不动」这条退路是有保质期的。

6 月到 beta 6 之间发生了什么变化

在整个 beta 周期里，macOS 的下限并不是一成不变的，了解你读到的是哪个版本的说法很重要。

6 月份时，关于 Intel 的发行说明是这样写的，见 Apple Developer Forums 上的引用：

Xcode 27 will only install and run on Apple silicon Macs. The macOS SDK is still Universal for back deployment up to and including macOS 27. Intel development is still possible with macOS versions that support Rosetta like macOS 27. (162138432)

这段话完全没有提到具体的下限版本。Tsai 的 第一天总结 将这一表述解读为「现在能定的最低目标是 Big Sur（在 Apple Silicon Mac 上则是 Monterey）」，而 ViennaRSS 的那个 issue 则直接说是 macOS 12。目前的 beta 6 发行说明 给出了明确答案：

Xcode 27 will only install and run on Apple silicon Macs. The macOS 27 SDK supports back deploying Universal (Intel and Apple Silicon) apps to macOS 12 and later. Intel development is still possible with macOS versions that support Rosetta like macOS 27. (162138432)

同一个问题编号，措辞改了，明确点出了 macOS 12。Tsai 在 9 月的更新里也提到了同一件事：「Xcode 27 Beta 6 现在把 macOS 12.0 记录为最低部署目标。」如果你的迁移计划是按 Big Sur 制定的，请改成按 Monterey 重新规划。

这次改动实际影响了谁

按受影响程度从重到轻，分三类。

仍在支持 High Sierra 到 Big Sur 的 Mac 应用

这正是 Tsai 那篇文章所讨论的群体，也是在这次改动中获得同情最少的群体。Eternal Storms 的 Matthias Gansrigler-Hrad 在 Mastodon 上直言：

I don't appreciate being forced by Xcode 27 to drop support for macOS 10.13-11.0. It's my decision

对这些开发者来说，Xcode 27 意味着一个被迫的选择：要么提高下限，放弃 2017–2020 年那批系统上的用户，要么留在 Xcode 26，放弃 macOS 27 SDK 以及依赖它的一切新特性。

iOS 应用，尤其是低于 15 的 iOS 库

自 Xcode 26 起，Apple 对 iOS 的下限就一直是 15，所以已经定在 15 的应用不会受到影响。但生态系统里到处都是把最低版本声明得更低的库，每一个这样的库现在都会在引用它的项目中触发这条诊断。6 月第一周，GitHub 的 issue 追踪器就被大量近乎一模一样、标题为「支持 Xcode 27：将 iOS 最低部署目标提高到 15」的请求刷屏——目标包括 Facebook iOS SDK（其 Package.swift 中声明的是 .iOS(.v12)）、Adjust、DataDog、SDWebImage 等等。如果你依赖的某个包的维护者还没有回应，你就只能等待，或者自己 fork。

依赖链深处埋着旧目标的情况

这是最隐蔽的一种。你的应用目标是 15。一个传递依赖的 Swift package 目标是 13。Xcode 27 用你的工具链构建这个 package，看到 13，让你的构建失败。Swift Package Manager 没有提供消费端的覆盖选项：bleepingswift 的结论和我们的判断一致——「在 platforms 声明中写着更低最低版本的包，要么升级到已经提高该声明的新版本，要么自己 fork 并修改这个要求。」

隐藏的逃生舱口

确实存在一个，你应该知道它，但也要谨慎对待它。

Ighor July 在 7 月 24 日的一篇文章中（Tsai 引用了这篇文章）报告说，在 Xcode 27 beta 中，「一个隐藏的设置把这些错误重新变回了警告，编译器依然产出了我测试过的那些旧目标的构建结果。」他把这个设置描述为「未记录，在正常的 Xcode 界面里找不到，目前只是处于测试阶段」的一个 beta 工具链特性。Tsai 那篇文章下的一位读者 Harald Striepe 给出了它的名字：

__DIAGNOSE_INVALID_DEPLOYMENT_TARGET_AS_ERROR = NO

这是一个构建设置，因此它该放在构建设置该放的地方：附加到配置上的 .xcconfig 文件，或者添加到目标 Build Settings 面板底部的一个 User-Defined 设置。设置好之后，部署目标检查就会恢复成 Xcode 26 时代的行为。

接下来是几条提醒，而且分量都不轻。

它不受官方支持。 双下划线前缀是 Apple 内部设置的命名惯例。它可能在任何一个 beta 版本中被重命名或移除，包括你开始依赖它之后的下一个 beta。

它恢复的是警告，而不是测试保证。 Tsai 对这整件事的评价值得完整引用，因为这是最诚实的看待方式：

I'm frustrated, too, but it's more honest than the recent releases that claimed to support deployment on older macOS versions when Apple clearly hadn't tested that it actually worked.

关掉这个错误，只是让你回到「为一个 Apple 之前就没有测试过、现在明确不再支持的目标构建」的状态。凡是在 Xcode 26 上就在 Catalina 上出问题的地方，现在依然会出问题。

它无法解决 App Store 的问题。 这就引出了真正要命的截止日期。

真正的截止日期是 2027 年 4 月

Xcode 27 发布本身不会强迫任何人使用它。真正强制的是 App Store 的 SDK 要求。

Apple 的 即将生效的要求页面 显示，自 2026 年 4 月 28 日 起，上传到 App Store Connect 的应用必须使用 Xcode 26 及其 26 系列 SDK 构建。多年来，Apple 对每一代新 SDK 都沿用了同样的规律：新 SDK 发布大约七个月后的次年春天（也就是 4 月），它就会成为强制要求。

如果这一规律延续下去——需要说明的是，Apple 尚未公布 2027 年的具体日期，这只是基于历史规律的推测，而非既定事实——那么从大约 2027 年 4 月起，每一次 App Store 提交都必须使用 Xcode 27 的 SDK 构建。届时：

• Mac App Store 应用如果部署目标低于 12.0，将无法更新，因为商店唯一接受的工具链会拒绝构建它。
• iOS App Store 应用如果目标低于 15.0，出于同样的原因也无法更新。
• 那个逃生舱口设置能不能通过 App Store 的验证，目前还不确定。没有人报告过用它来测试提交流程，我们也不会把业务押在它上面。

在 App Store 之外——也就是使用 Developer ID 直接分发——上述这些都不适用。只要你手上的 Mac 还能运行 Xcode 26，就可以一直用 Xcode 26 构建。而这又引出了下一个问题。

留着 Xcode 26 不动，以及这条路为什么会失效

最直观的应对办法是两个版本都装。像 xcodes 这样的工具能让你轻松地把 Xcode 26.6 和 27 beta 装在一起，用 xcode-select 来回切换。对于一个部署目标是 10.13、今年还必须发布的项目，这确实是正确的选择。

但它有失效期。Apple 的支持表格写明 Xcode 26.6 需要「macOS Tahoe 26.2 – macOS Tahoe 26.x」。没有任何说明表示它能在 macOS 27 上运行，Tsai 的判断是「使用旧版本 Xcode 不是一个好办法，因为它们在 Golden Gate 上不受支持」。它也许能启动；如果启动不了，Apple 也不会去修。他还补充了一个更微妙的代价：

Swift also makes it more difficult to call newer APIs when using an older SDK.

留在 Xcode 26 就意味着留在 macOS 26 SDK 上，也就意味着 macOS 27 的新 API 只能通过动态查找访问，甚至完全无法访问。对于一个只做维护、不再迭代的应用，这没问题。但对于任何还在积极开发的项目，这是一种缓慢的扼杀。

Xcode 27 本身只支持 Apple Silicon

这是另一项独立的改动，恰好和部署目标的问题在同一版本中一起出现，容易被混为一谈，这里特意说清楚区别。

发行说明写得毫不含糊：「Xcode 27 will only install and run on Apple silicon Macs.」它的二进制文件是纯 arm64 的，一位 Intel MacBook Pro 用户 在论坛上证实了这一点——他原本因为说明里「需要 macOS Tahoe 26.4 或更高版本」这句话，以为自己的机器能装，因为 Tahoe 确实能在少数几款 Intel Mac 上运行，但 Xcode 27 不行。

SDK 本身依然是 Universal 的。你可以从 Xcode 27 构建 x86_64 架构切片和 Universal 二进制文件，只是必须在 Apple Silicon 机器上进行这个构建过程。这是对开发者硬件的要求，不是对应用分发范围的限制。

另一项 Intel 相关改动：27.0 起 Universal 不再是默认选项

beta 6 说明中「Intel Deprecation（Intel 弃用）」条目下，还有一项和 Intel 相关的改动，大多数报道都没有提到：

Build targets with a min deployment target set to macOS 27.0 or DriverKit 27.0 will not build Universal by default. The ARCHS_STANDARD build setting will no longer include x86_64 when MACOSX_DEPLOYMENT_TARGET or DRIVERKIT_DEPLOYMENT_TARGET >= 27.0. The x86_64 architecture can be added to the ARCHS build setting if this is needed. (161837535)

这个逻辑是说得通的——macOS 27 不会在任何 Intel Mac 上运行，所以一个只面向 27.0 的目标本来就没有 Intel 机器可以运行——但它有一个副作用。Rosetta 依然存在于 macOS 27 中，Apple 9 月 1 日的开发者说明 也重申了 27 是它的最后一个版本。一个默认丢弃 x86_64 的 27.0-only 应用，在 Apple Silicon 上也无法通过 Rosetta 运行了，这只在你还在提供纯 Intel 的插件宿主之类场景时才有影响。如果需要，请显式地把 x86_64 加入 ARCHS。

一个几乎没人提到的第三条下限：libc++ 定在 11.0

同一份弃用清单里还藏着这样一句：「The minimum supported deployment target on macOS for the C++ standard library has been increased to 11.0.」这是一条不同的、比 12.0 这条构建系统下限更低的门槛，它针对的是你链接的 C++ 运行时，而不是你声明的部署目标。实际中，只有当你绕开了构建系统的检查——比如用了那个隐藏设置——并且仍然用 C++ 代码面向 10.15 或更早的系统时，这条限制才会显现出来。到那时，挡住你的就变成了 libc++ 本身。

修复：依赖项

对你自己的目标，修复方式就是文本框里改一个数字。对依赖项：

CocoaPods。 添加一个 post_install 钩子，把每一个 pod 目标的部署目标都改写成你的下限，然后运行 pod install 并清理构建目录。bleepingswift 给出的钩子写法是标准形态；重点是它要作用于所有的 pod 目标，而不只是今天正在报错的那几个。

Swift Package Manager。 没有覆盖机制。你的选择只有：更新到已经提高 platforms 声明的新版本；提交或点赞相应的 issue；或者自己 fork、修改 Package.swift，让项目指向这个 fork，直到上游跟上。先去 issue 追踪器看看——对于主流的 SDK，通常 6 月第一周就有人提交了请求，而且往往已经挂了一个 pull request。

Vendored 框架和 XCFramework。 它们在自己的 Info.plist 和 Mach-O 加载命令中携带各自的最低版本要求。Xcode 27 并不会拒绝链接一个旧的二进制框架，但链接器会对版本不匹配发出警告，而它在旧目标上的实际表现完全取决于是否测试过——也就是说，没有测试过。

「诚实」在这里意味着什么

值得花点时间体会一下 Tsai 的这个框架，因为它会改变你到底应该为哪件事感到不满。

Xcode 26 从来没有真正支持过 macOS 10.13。它只是允许你输入 10.13，然后生成代码，Apple 并没有测试过 26 系列 SDK 中的框架在一个 2017 年的操作系统上是否表现正确。发布了这类构建版本的开发者，实际上是在自己对一个 Apple 已经放弃的系统做 QA，而且大多数时候确实能用，因为这些框架在设计上就是向后兼容的。但那句话里的「大多数时候」承担了不小的风险，而且 SDK 和目标之间的差距每年都在拉大。

Xcode 27 所做的，是让文档上的范围变成真实的范围。这对老 Mac 的用户以及曾经服务这些用户的开发者来说，是一种损失。但这不是 Apple 曾经承诺过、如今又收回的东西。

监管层面的一个插曲

还有一条线索。8 月 26 日，Tsai 汇总了 关于欧盟《网络韧性法案》（Cyber Resilience Act）的一些评论，该法案的主要义务将于 2027 年 12 月 11 日生效，要求提供至少五年的安全更新。一位化名 Frederik 的读者指出了它和 App Store 之间的互动关系：

Once you update the minimum supported OS version of your app (which you might be forced to by newer Xcode versions… you can no longer provide updates for your older app versions on the App Store.

这正是本文所描述的机制。App Store 对每个应用只保留一个当前版本。如果 Xcode 27 的 SDK 成为强制要求，你的下限提高到 macOS 12，那么 macOS 11 上的用户将永远停留在他们收到的最后一个构建版本上，得不到任何安全更新。至于 CRA（网络韧性法案）会把这算作开发者的责任、Apple 的责任，还是谁的责任都不是，那是律师该回答的问题；技术层面的事实是，Apple 的分发模式没有分支机制，而 Xcode 27 正让这一点在更多开发者面前变得清晰可见。

迁移检查清单

对于一个部署目标较旧的 Mac 应用，按顺序：

1. 盘点你真实的用户群体。 如果你的统计数据显示没有人还在 macOS 12 以下，那这只是一行代码的改动加一条发行说明。大多数应用属于这一类。
2. 把每一个目标的部署目标都设为 12.0（macOS）或 15.0（iOS），包括扩展、辅助工具和测试目标。用 Xcode 27 beta 构建，清除每一处这条诊断信息。
3. 审查依赖项，检查低于该下限的 platforms 声明和 podspec。该 fork 的就 fork。
4. 决定如何处理留守用户。 如果你确实需要继续为 10.13–11.0 的用户发布更新，就在 2027 年 4 月之前用 Xcode 26 打出最后一个构建版本，通过 App Store 之外的渠道分发，或作为一个冻结的旧版本发布，并公开说明这一点。
5. 不要把这个隐藏设置带进生产环境，除非你已经亲自在旧系统上测试过结果，并且接受它可能在下一个 beta 中消失。
6. 如果你只面向 27.0，检查一下 ARCHS。 你可能在不知不觉中丢掉了 x86_64。

常见问题排查

我提高了应用的目标之后，错误依然存在

项目里的另一个目标仍然是旧值。在导航器中选中项目本身（而不是某个 target），检查项目级别的部署目标，然后逐一检查每个 target 和每个测试包。小组件和应用扩展是最常见的漏网之鱼。

错误指向一个我没有直接依赖的包

这是一个传递依赖。使用 swift package show-dependencies（或 Xcode 的包依赖关系图）找出是谁引入了它，然后更新那个中间包，或者直接 fork 最底层的那个包。

命令行的 xcodebuild 构建失败，但 Xcode 图形界面能构建成功

检查命令行实际使用的是哪个工具链：运行 xcode-select -p。你可能是图形界面用的 26，命令行用的是 27，反过来也一样。

我设置了隐藏标志，但没有任何效果

这个标志需要在检查生效的那个层级对构建系统可见——项目级别的 xcconfig 是最保险的位置。如果只在某一个 target 上设置了，其他 target 依然会报错。如果仍然没有效果，可能是你所在的这个 beta 版本已经把它移除了。

我的 CI 运行器是 Intel 机器

Xcode 27 无法在它们上面安装。这是一个硬件迁移问题，而不是配置问题。托管型 CI 服务商早就已经切换到 Apple Silicon 运行器；自托管的 Intel Mac mini，对于当前工具链的构建来说，已经走到了生命周期的尽头。

常见问答

Xcode 27 提高了 iOS 的最低版本要求吗？

纸面上没有——Apple 的表格从 Xcode 26 起就一直写的是 iOS 15。真正变化的是执行力度：在 Xcode 26 中只触发警告、能正常构建的低于 15 的目标，在 Xcode 27 中会构建失败。

Xcode 27 中 macOS 的最低版本是多少？

macOS 12 Monterey，依据 Apple 的 Xcode 支持页面和 beta 6 的发行说明。在 beta 周期早期，这条说明曾被理解为 Big Sur，那个理解已经过时了。

我还能构建 Universal（Intel + Apple Silicon）应用吗？

可以，但要在 Apple Silicon Mac 上进行。macOS 27 SDK 支持将 Universal 应用回退部署到 macOS 12 及以上版本。唯一会默认丢弃 x86_64 的情况，是目标设为 27.0 或更高版本。

我什么时候必须迁移到 Xcode 27？

如果是直接分发，理论上永远不必——只要你手头还有一台能运行 Xcode 26 的 Mac。如果是走 App Store，那就是当 Apple 把 27 系列 SDK 定为强制要求的那一刻，按照以往的惯例，大约会在 2027 年 4 月。Apple 尚未公布这个日期。

那个隐藏设置对 App Store 构建来说安全吗？

不确定。没有人报告过用它构建并成功提交的案例，而且它是一个未记录的内部标志。请把它当作本地构建和旧版本分支专用的工具，不要用在你的正式发布流程里。

结语

Xcode 27 在部署目标上的这次改动，是一个很小的修改，却拖着一条很长的尾巴。Apple 并没有把下限提高多少——macOS 只动了一个版本，iOS 完全没动——但它不再假装这条下限是可选的，而过去十年里，大量独立 Mac 软件正是建立在这种假装之上的。如果你的用户都在现代系统上，今天遇到的这个构建错误很容易修；但如果他们不在，这个问题就没有真正干净的解决办法。

先弄清楚自己属于哪一种情况。如果你仍然在为 macOS 11 或更早版本发布应用，剩下的窗口期就是「一台还能运行 Xcode 26 的 Mac」，而这扇窗口对 App Store 应用来说，大约还有七个月就会关闭。如果不属于这种情况，那就提高版本号、修好依赖项，如果你只面向 27，再检查一下 ARCHS，然后继续前进——Apple 终于把它一直打算做的事情正式写进了文档。

延伸阅读：在 Rosetta 终结前审查你的 Intel 应用、macOS 27 的 Intel 兼容性终止节点、修复 macOS Tahoe 开发环境配置，以及今年最好用的 Mac 开发者工具。