Xcode 27 移除 ld64，并要求模块名称唯一

苹果用一句话让一个链接器退场：“ld64 链接器已被移除，-ld_classic 选项不再受支持。”¹ 而这个如今消失的标志，正是苹果当年要求开发者添加的。Xcode 15 自己的发行说明就把 -Wl,-ld_classic 作为两个链接器缺陷的绕行方案。³

摘要

• Xcode 27 移除了 ld64，也不再接受 -ld_classic。¹ 苹果在 Xcode 15 的说明中曾为弱符号崩溃和 LTO 导入缺陷开出这个标志，Xcode 16 将其标记为弃用，Xcode 26 则只字未提。³⁴¹⁰
• 第二处断裂位于 Swift 编译器。苹果把依赖扫描合并成一次共享操作，因此“单次 Swift 依赖扫描操作可触及的每个 Clang 模块都必须拥有唯一的模块名称”。² 苹果两次留了余地：扫描“可能会报错”，而此前扫描器“可能容忍了重名”。²
• 两者都在升级工具链时触发，与部署目标或 SDK 的选择无关，也都不涉及运行时。真正暴露在风险中的是这样一批项目：随源码附带第三方二进制、使用 CocoaPods，或拥有规模较大的 Swift/Objective-C/C++ 混合代码库。
• 苹果的“可能”并不是行文上的谨慎。在 Xcode 26.6 下，我把两份声明了同一名称的模块映射放在同一条搜索路径上，运行扫描器 20 次：9 次以 SIGSEGV 崩溃，5 次中止，6 次顺利完成。⁸
• 随源码附带的模块映射重复声明 SDK 模块——正是苹果点名的那种情形——在今天会静默通过编译，并把真正的模块遮蔽掉。我那份随源码附带的 SQLite3 垫片以退出码 0 通过了类型检查，而 sqlite3_open 就此不复存在。⁸
• 七个受审计项目的结果：-ld_classic 出现 0 次，OTHER_LDFLAGS 处处未设置，391 份模块映射中重名 0 例——因为没有任何一个仓库存放手写的模块映射。⁹

两条说明都出自 Xcode 27 beta 4 的发行说明，与 Swift 6.4 及 27 系列 SDK 一同发布。¹¹ 阅读时请把它们当作 beta 阶段的文本。

苹果当年让你加上的那个标志

故事要从一次链接器重写说起。Xcode 15 宣布了新链接器，让它成为“所有 macOS、iOS、tvOS 和 visionOS 二进制文件”的默认选择，并用一个从句写定了退役条件：“仍可使用 -ld64 显式请求经典链接器，该选项将在未来版本中移除。”³

新链接器带着缺陷登场，苹果在同一个页面上两次写下了应急出口。第一条已知问题：“使用弱定义符号的二进制文件在 iOS 14/macOS 12 及更早版本上运行时崩溃。由于 C++ 项目大量使用弱符号，受影响最大的是它们。”苹果给出的绕行方案是提高部署目标，“或在 OTHER_LDFLAGS 构建设置中加入 -Wl,-ld_classic”。³ 第二条针对 LTO 目标文件把弱符号导入按非弱方式链接的问题，在同一项设置中给出了“-Wl,-weak_reference_mismatches,weak 或 -Wl,-ld_classic”。³

两个缺陷都对 C++ 项目打击最重，这也解释了今天还带着这个标志的是谁。没有人会回头去动一项已经止住崩溃的设置。

Xcode 16 用一句话发出了通知：“-ld_classic 链接器选项已弃用，将在未来版本中移除。”⁴ 此后便是沉默。我在 Xcode 26 的发行说明里检索 ld_classic、ld64 和经典链接器，一无所获。¹⁰

当前的工具链仍然接受这个标志，也仍然会抱怨。在 Xcode 26.6 上，我用它链接了一个极简的 C 程序：⁷

xcrun clang hello.c -o hello -Wl,-ld_classic

ld: warning: -ld_classic is deprecated and will be removed in a future release

退出状态为 0。二进制文件链接成功。换成 -Wl,-ld64 会产生完全相同的、同样点名 -ld_classic 的警告，可见苹果用过的两种写法今天都走向同一条代码路径。⁷ 苹果在 Xcode 27 的说明中只提到了 -ld_classic，我无法测试 -ld64 是否以同样的方式失败。

有一个细节让“移除”这个词变得没那么简单。用 xcrun ld -v 让 Xcode 26.6 的链接器自报家门时，它会说明自己把哪些架构转交了出去：⁷

@(#)PROGRAM:ld PROJECT:ld-1267
BUILD 16:38:58 Jun  8 2026
configured to support archs: armv6 armv7 armv7s arm64 arm64e arm64_32 i386 x86_64 x86_64h armv6m armv7k armv7m armv7em armv8m.main armv8.1m.main
will use ld-classic for: armv6 armv7 armv7s i386 armv6m armv7k armv7m armv7em

ld-classic 作为一个真实的二进制文件存在于工具链中，还带着自己的 man 手册页，链接器至今仍把八种架构路由给它。⁷ 这些架构没有一个还活在当前的应用 SDK 里：iPhoneOS 26.5 只声明了 arm64e 和 arm64，watchOS SDK 另加一个 arm64_32。⁷ 那份清单是 32 位 ARM、i386 和 Cortex-M 嵌入式目标。把它们在 SDK 中的缺席解读为“这次移除对应用开发者是安全的”的理由，是我的推断，而非苹果的说法。

不轻信 grep，也能找出这个标志

-ld_classic 存在于 OTHER_LDFLAGS 中，所以与其在文件里搜索文本，不如直接问构建系统它最终解析成了什么：

xcodebuild -showBuildSettings \
  -project YourApp.xcodeproj \
  -configuration Release -sdk iphoneos 2>/dev/null \
  | grep -E "OTHER_LDFLAGS|SUPPORTED_PLATFORMS"

对 Reps 项目执行，只回来一行：⁹

    SUPPORTED_PLATFORMS = appletvos appletvsimulator iphoneos iphonesimulator macosx

OTHER_LDFLAGS 根本没有出现，这本身就是答案：该设置未被赋值，因此不会有任何链接器标志由它进入链接步骤。在已解析的构建设置中缺席，所携带的信息量是文本搜索的缺席所没有的。判断平台同样要看 SUPPORTED_PLATFORMS，绝不要看 *_DEPLOYMENT_TARGET——无论目标平台是否真实存在，Xcode 都会把它写进去。

审计过程中有三个陷阱制造出了虚假的“干净”结果，三者都是什么也不打印、并以成功状态退出。原生 macOS 上并没有 timeout，用它包住 xcodebuild 会得到退出码 127 和空输出，看上去就像一个没有任何链接器标志的项目。在 zsh 下，未加引号的 --include=*.pbxproj 会在 grep 看到它之前被通配符展开，于是命令以“no matches found”告终，而不是报告零命中。还有，find 不会跟随作为起点给出的符号链接，这一点很关键，因为 xcrun --sdk iphoneos --show-sdk-path 返回的正是一个符号链接：find "$SDK" -name '*.modulemap' 什么也找不到，而 find -H "$SDK" 能找到 266 个文件。⁹ 给模式加上引号，传入 -H，并且在相信任何一个零之前，先确认命令能匹配到你明知存在的东西。

手工维护的目标会把这个标志放在 project.pbxproj 或某个 .xcconfig 里；CocoaPods 项目还可能从 post_install 钩子里拿到它，而那条路径不会体现在任何开发者手改过的文件中。我审计的这批项目两者都没有，因此最后这条路径未经验证。⁹

模块名称规则，以及苹果的两处含糊措辞

第二处断裂伪装成一项性能改进登场，被归入“新特性”而不是“弃用”。苹果关于 Swift 编译器的这条说明，全文如下：

Swift 依赖扫描器已经过优化，避免在单次依赖扫描操作中查找 Clang 模块时重复进行准备工作和头文件搜索，扫描性能因此大幅提升。作为这一改动的后果，单次 Swift 依赖扫描操作可触及的每个 Clang 模块都必须拥有唯一的模块名称。如果同一次扫描可见的两份模块映射声明了同名的 Clang 模块，扫描可能会报错。此前，扫描器可能容忍了重名。最常见的情形是：项目或 SDK 在头文件搜索路径的多个位置提供同一个 Clang 模块名称，以及随源码附带的第三方代码中带有重复声明 SDK 模块的 module.modulemap。²

这里有四件事值得分开来看。苹果把这项要求限定在一次扫描所能触及的范围内，而不是整块磁盘。苹果把后果表述为“可能会报错”，并用同样的措辞给旧行为留了余地。苹果点名了两种触发形态：同一个模块名称从头文件搜索路径的两个位置被提供；以及随源码附带的 module.modulemap 重复声明了 SDK 模块。还有，触发条件是工具链本身，因为整段文字没有提到任何部署目标或 SDK 版本。

这条规则比这次优化更早。Clang 的模块映射语言把它讲得很直白：“每个模块应当只有一个定义。”⁶ 文档从未说明的，是违反这条规则的后果，而这份沉默事出有因：工具链给出的答案不是一种行为，而是好几种。

一次重名冲突究竟会发生什么

苹果的含糊措辞让我想亲眼看看这个故障，于是我搭出了最小的版本：两个目录，各有一份声明同一模块的 module.modulemap。⁸

A/module.modulemap    B/module.modulemap
module Widget {       module Widget {
    header "widget.h"     header "widget.h"
    export *              export *
}                     }

当两个目录都在搜索路径上时，一次普通的类型检查每次都以相同方式失败，20 次运行 20 次如此：⁸

B/module.modulemap:1:8: error: redefinition of module 'Widget'
1 | module Widget {
  |        `- error: redefinition of module 'Widget'
A/module.modulemap:1:8: note: previously defined here

redefinition of module 就是应当在构建日志里检索的字符串，而 Xcode 26.6 的 clang 已经会输出它。去掉其中一条搜索路径，同样的编译就能成功，这证实触发条件是对同一次编译可见，而不是文件存在于磁盘上。⁸

依赖扫描器的表现则不同，而这个差别正是苹果写下“可能”的全部原因。把同样两份模块映射交给 swiftc -scan-dependencies 跑 20 次，出现了三种结果：9 次以 SIGSEGV 崩溃，5 次中止，6 次干净地成功。⁸ 崩溃那几次的调用栈都经过 performParallelClangModuleLookup，这与苹果所说被替换掉的并行查找中存在竞态相吻合。把这种不确定性归因于该竞态，是我对调用栈的解读，不是苹果的表述。

苹果点名的第二种情形是安静的那一种。我写了一份随源码附带的模块映射，声明 SQLite3——iPhoneOS SDK 中真实存在的模块——把它放到搜索路径上，然后据此编译：⁸

Vendor/module.modulemap
module SQLite3 {
    header "shim.h"
    export *
}

编译成功了。退出码 0，没有警告，没有提示，没有任何形式的诊断信息。接着我在同一配置下请求 sqlite3_open：⁸

error: cannot find 'sqlite3_open' in scope

只要搜索路径上没有那个附带目录，同一个文件就能编译通过。随源码附带的模块映射把 SDK 的 SQLite3 完全遮蔽掉了，而工具链一言不发。所以在今天，“重复声明”这种情形不会大声失败；它表现为你以为已经导入的模块里缺了一个 API。苹果的说明称，Xcode 27 的扫描在这里“可能会报错”，那将把一次静默的遮蔽变成一次构建失败。

我的构建环境是 Xcode 26.6（版本号 17F113），因此上面每一条诊断信息都来自上一代工具链。⁷⁸ 我无法给出 Xcode 27 的报错文本，也没有编造任何一条。诊断机制、值得检索的字符串，以及苹果所说即将取消的那份容忍，今天都已存在。

审计重复的模块名称

枚举已声明的模块名称看起来只需一行 grep，但模块映射语言中有两种结构会给出错误答案。

extern module Foo "Foo.modulemap" 是前向引用，不是定义，而苹果的 SDK 在一份模块映射里就用了 79 处。⁷ 粗糙的扫描会把这个引用和真正的定义当成 Foo 的两次声明。其次，module Darwin.C { ... } 用带点的 module-id 扩展在别处声明的模块；SDK 中有 13 份模块映射以 module Darwin.something 开头，若把第一段读成顶层声明，就会把这 13 份连同真正的 Darwin 声明凑成一次涉及 14 个文件的“冲突”。⁷ 这两种误报都出现在我的初稿里。

最终留下来的版本会处理注释、跟踪花括号深度以排除嵌套的 explicit module 子模块，并能应对含空格的路径：

find -H "${1:-.}" \( -name '*.modulemap' -o -name 'module.map' \) \
  -not -path '*/build/*' -not -path '*/.build/*' \
  -not -path '*/DerivedData*/*' -print0 |
while IFS= read -r -d '' map; do
  awk -v f="$map" '
    { line = $0; sub(/\/\/.*/, "", line)
      if (depth == 0 && line !~ /extern[[:space:]]+module/ &&
          match(line, /(^|[[:space:]])module[[:space:]]+[A-Za-z_][A-Za-z0-9_.]*/)) {
        n = substr(line, RSTART, RLENGTH); sub(/.*module[[:space:]]+/, "", n)
        if (n !~ /\./) print n "\t" f
      }
      for (i = 1; i <= length(line); i++) {
        c = substr(line, i, 1)
        if (c == "{") depth++; else if (c == "}") depth--
      }
    }' "$map"
done | sort -u > /tmp/modnames.txt

cut -f1 /tmp/modnames.txt | uniq -d | while read -r n; do
  echo "duplicate: $n"
  awk -F'\t' -v n="$n" '$1==n {print "  " $2}' /tmp/modnames.txt
done

能拿到的最强阴性对照是苹果自己的 SDK——它必须满足这条规则，工具链才能正常工作。把命令指向 iPhoneOS 26.5 SDK，可以在 usr/include 下找到 1,099 处顶层声明，在各框架的模块映射中找到 205 处，两边的重名数都是 0。⁷ 指向刻意构造出冲突的测试样例时，它会指出重名以及涉及的两个文件。⁸

那些排除项分量不轻。-not -path '*/build/*' 并不能排除 .build/，因为该模式需要字面上的目录名，而 SwiftPM 会成打地把生成的模块映射写进 .build。把 .build 留在结果里，制造了七个项目中唯一的一批“重名”：GrappleCore 出现在 6 个文件中，GrappleRender 出现在 3 个文件中，全部是 SwiftPM 的产物，横跨两个 Swift 目标、位于不同的构建根目录下。⁹ 这 9 个文件甚至不是逐字节相同的，原因很有启发性：每一份都把同一个模块名称包在指向各自构建根目录下生成头文件的绝对路径外面，因此它们只在一个字符串上不同，其余毫无差别。一份把它们称作冲突的审计，还没碰到真正的问题，就已经耗尽了自己的可信度。

Xcode 制造的是同一种误报，只是更没有歧义。在单个 DerivedData 目录树内，它会把每个 Swift 包生成的模块映射写两遍，一次写进 GeneratedModuleMaps-iphonesimulator/，一次写进目标自身的中间产物目录，两次都使用相对头文件路径。在某个项目的目录树中，有 15 个名称各出现两次，15 对全部逐字节相同。⁹ 把审计范围限定在源码，而不是构建产物。

七个项目里到底有什么

我在 Xcode 26.6 上对七个 Xcode 项目跑了这两项审计。诚实的结果是一个干干净净的零。⁹

七个项目中 OTHER_LDFLAGS 全部未设置，整批项目里找不到任何 .xcconfig 文件，没有 CocoaPods，没有 Carthage，也没有随源码附带的 .framework 或 .xcframework。⁹ 模块名称审计检查了 391 份模块映射，其中 204 份位于项目目录内，187 份位于 Xcode 图形界面构建产物所在的共享 DerivedData 中，而它们无一例外都是构建产物。⁹ 没有任何一个仓库存放着手写的模块映射。

两个零出自同一个原因，而这正是值得带走的结论：真正暴露的是混合语言项目，而这些项目不是。在 463 个 Swift 文件之外，这批项目里 Objective-C 为零、C++ 为零、C 源文件为零，唯一的非 Swift 编译代码是 Water 中的两个 Metal 着色器。⁹ 一个从未处于风险中的代码库给出的零结果，对于危险本身是弱证据，对于“谁才需要审计”却是强证据。

有两个细节比这些零更重要。已解析的依赖包中唯一手写的模块映射属于 swift-crypto，它提供了四个 C 垫片，名为 CCryptoBoringSSL、CCryptoBoringSSLShims、CXKCP 和 CXKCPShims，彼此各不相同。⁹ 另外，这批项目声明的名称，没有一个出现在 SDK 的 Clang 模块命名空间里——对照的是命令在 iPhoneOS 26.5 SDK 中找到的全部 1,318 个顶层名称。⁹ 连通过 Supabase 引入的那些通用名称也没有撞上：SDK 声明了名为 Foundation、UIKit 和 SQLite3 的 Clang 模块，却没有任何名为 Crypto、Storage 或 Auth 的模块。

脚下正在抬高的 C++ 部署下限

有一项相邻的改动，打中的正是那些还带着 -ld_classic 的 C++ 项目。苹果抬高了一条下限，并且只点了 macOS，没有提到其他平台：“C++ 标准库在 macOS 上支持的最低部署目标已提高到 11.0。”⁵

同一条说明给出了一个应急出口，又在下一句里给它定下了移除的时间。对于不构成严格弱序的比较器，libc++ 改变了 std::map 和 std::set 上 lower_bound 与 upper_bound 的结果，而定义 _LIBCPP_ENABLE_LEGACY_TREE_LOWER_UPPER_BOUND “将恢复这些操作的历史实现”。紧接着：“该应急出口将在后续版本中移除（很可能就是下一个版本）。”⁵ 一项相关改动让 multimap::find 和 multiset::find 不再必然返回第一个相等的元素——苹果指出这种行为“从未被标准所保证”，尽管 libc++ 一直提供它——而且这项改动没有提供任何退出选项。⁵ 请把那个宏当作一张迁移工单，而不是一个修复。

常见问题

我的项目里为什么会有 -ld_classic？

几乎可以肯定是因为苹果的 Xcode 15 发行说明开出了这个方子。那里有两条已知问题建议把 -Wl,-ld_classic 加入 OTHER_LDFLAGS：一条是使用弱定义符号的二进制文件在 iOS 14 和 macOS 12 及更早版本上运行时崩溃，苹果指出它“受影响最大的是 C++ 项目”；另一条是 LTO 目标文件把弱符号导入按非弱方式链接。³ 苹果在 Xcode 16 中弃用了该选项，并在 Xcode 27 中移除了它背后的链接器。¹⁴ 如果这个标志还在，先确认当初那个缺陷是否仍能复现，再去寻找替代方案。

如何在项目中找出重复的 Clang 模块名称？

把每一份模块映射中的顶层模块声明枚举出来，找出出现在两个文件里的名称，并把构建目录从结果中剔除。有三件事让这项工作不止于一次 grep：extern module Foo "path" 是引用而不是定义；module Foo.Bar 扩展的是在别处声明的模块，而不是在声明 Foo；嵌套的 explicit module 子模块不会与顶层名称发生冲突。⁶ 要显式排除 .build、build 和 DerivedData，因为 -not -path '*/build/*' 漏掉了 .build，而 SwiftPM 和 Xcode 都会例行地重复生成模块映射。⁹

在 Xcode 27 下报错是什么样子？

我说不了，任何在 Xcode 26 上构建的人也说不了。我的机器运行的是 Xcode 26.6（版本号 17F113），因此本文完全不报告任何 Xcode 27 的输出。⁷⁸ 对于两份声明同一名称的模块映射，Xcode 26.6 给出的是 error: redefinition of module 'Widget' 以及一条 note: previously defined here，普通类型检查每次运行都是如此。⁸ 苹果对 Xcode 27 的措辞是扫描“可能会报错”，因此请在日志里检索 redefinition of module，而不是某个人猜出来的字符串。

模块名称唯一性导致的失败与部署目标有关吗？

无关。苹果把这项要求限定在单次 Swift 依赖扫描操作上，整条说明没有提到任何操作系统版本、SDK 或部署目标。² 链接器的改动读起来也一样，是从工具链中移除。¹ 两者都会在 Xcode 27 的第一次构建时落地，与 @State 宏同类，而不是与本轮由 SDK 触发的那些要求同类。

关键要点

给 iOS 开发者： - 用 xcodebuild -showBuildSettings -configuration Release -sdk iphoneos 查询 OTHER_LDFLAGS，而不是用 grep 搜索 -ld_classic。在已解析的设置中缺席意味着未设置；在文本搜索中缺席什么也说明不了。⁹ - 在构建日志里检索 redefinition of module——这是 Xcode 26.6 已经会输出的诊断信息——而不是凭空编造的 Xcode 27 报错文本。⁸

给带有随源码附带的 C 或 C++ 依赖的团队： - 先把随源码附带的 module.modulemap 文件与 SDK 的命名空间比对审计：苹果点名的正是这种情形，而它今天是静默失败的。我那份随源码附带的 SQLite3 垫片以退出码 0 通过编译，并让 sqlite3_open 凭空消失。⁸ - 把审计范围限定在源码，并排除 .build、build 和 DerivedData。391 份模块映射中每一处看似重复的名称，都是同一个 Swift 目标的构建产物。⁹

给发布管理者： - 把这两项改动都视为由工具链触发，并安排在 Xcode 27 的第一次构建时处理，而不是放进 SDK 迁移。两者都不涉及部署目标，也都没有运行时成分。¹² - 把苹果的含糊措辞写进工单。扫描“可能会报错”，而同一处冲突跑 20 次给出了三种不同结果，所以构建通过一次并不能证明什么。²⁸

27 这一轮的故障不断出现在不同的位置：启动屏幕键会拦下一次提交，场景生命周期强制要求会拦下一次启动，@State 宏则在源码层面拦下一次构建。链接器的移除和模块名称规则把它拦在更低的一层——在那些没人会刻意去配置的工具链部件里。整个系列的入口是苹果生态系列。

参考资料