Nokogiri 在 Darwin 上的符号解析策略：Ruby 3.2 预编译原生 gem 的 `-flat_namespace` 与 `-load_hidden` 链接方案

• 后端

本文依据仓库 adr/2022-12-darwin-symbol-resolution.md 这一架构决策记录（ADR）展开，系统讲解 Nokogiri v1.14.0 在 macOS（Darwin）上为 Ruby 3.2 发布预编译原生 gem 时所面临的动态符号解析问题，以及最终采用的-flat_namespace+-load_hidden链接策略。读完本文，你将理解 Ruby 3.2 的-bundle_loader链接行为为何会破坏 C 扩展的符号解析、为什么-flat_namespace会引发与系统 libxml2 的符号冲突，以及 Nokogiri 如何在 extconf.rb 中精准地只在受影响的交叉编译场景下应用这些链接器标志，同时权衡对下游集成方（如 nokogumbo、nokogiri-xmlsec）造成的影响。

背景：Ruby 3.2 在 Darwin 上引入了新的符号解析方式

在 Nokogiri v1.14.0 发布预编译原生 gem（支持 Ruby 3.2）的最后阶段，维护团队遇到了一组与 Darwin 平台符号解析（symbol resolution）相关的棘手问题。

问题的根源在于 Ruby 3.2 的构建工具链变化：Ruby 3.2 在 Darwin（macOS）上编译扩展时，会在链接行中使用-bundle_loader标志，将符号解析指向 Ruby 可执行文件（就好像它是一个共享库一样）。这意味着，当运行在--enable-shared编译的 Ruby 之上时，扩展将无法解析rb_cObject之类的 Ruby 符号——因为符号解析方向被固定到了 Ruby 二进制本身，而--enable-shared的 Ruby 运行时并不以该二进制作为符号来源。

用一句话概括：-bundle_loader让同一个编译产物难以同时兼容--enable-shared与--disable-shared两种 Ruby 构建。

第一次缓解：-flat_namespace

为了绕开上述问题，Nokogiri 采用了-flat_namespace链接器标志。该标志模拟了 Linux 平台上已有的行为：符号不再强制绑定到某个特定的装载单元，而是允许在运行时按扁平命名空间进行解析。这样，扩展既可以服务于--enable-shared的 Ruby，也能服务于--disable-shared的 Ruby。

第二次冲突：-flat_namespace引发的“错误 libxml2”

-flat_namespace带来了一组新的副作用。如 extconf.rb 中的注释所描述的：

The-flat_namespaceline introduces its own behavior change, which is that (similar to on Linux), any symbols in the extension that are exported may now be resolved by shared libraries loaded by the Ruby process.

即：与 Linux 平台类似，扩展中被导出的任何符号都可能被 Ruby 进程中已加载的共享库在运行时解析。具体到 Nokogiri：

• libxml2 和 libxslt 是以静态链接的方式编入 Nokogiri 扩展 bundle 的；
• 但在 Darwin 上，很多 Ruby 发行版会加载 Xcode 命令行工具（Command Line Tools，简称 CLT）自带的 libxml2 / libxslt dylib；
• 于是在运行时，libxml2 的每一个符号都发生了冲突，并解析到了错误的 libxml2——不是 Nokogiri 打过补丁并静态链接进去的那个版本。

这会破坏 Nokogiri 对“当前运行的究竟是打补丁后的 libxml2 还是系统原版 libxml2”这一基本假设，可能引入行为差异与安全问题。

决策：v1.14.0 Darwin 原生 gem 的链接标志组合

面对上述问题，Nokogiri 在 ADR 中做出了明确的架构决策：

Nokogiri v1.14.0 针对 Darwin（macOS）Ruby 3.2 的预编译原生 gem，将采用以下链接策略：

1. -flat_namespace：确保扩展同时可用于--enable-shared与--disable-shared两种 Ruby 构建；
2. -load_hidden（应用于 libxml2 与 libxslt 两个静态库）：避免意外解析到非 vendored（非内置）版本的这两个库。

简单理解这个组合：-flat_namespace负责“让扩展能在两种 Ruby 下运行”，而-load_hidden负责“让扩展内部的静态 libxml2/libxslt 不被外部符号劫持”。正如 extconf.rb 注释中那句精炼的总结：

when we useload_hidden, what happens in the extension stays in the extension.

源码级实现：extconf.rb 中的 Darwin 链接器 hack

这一决策在 Nokogiri 的扩展构建脚本 ext/nokogiri/extconf.rb 中落地为两段代码，非常值得细读。

触发条件：needs_darwin_linker_hack

def needs_darwin_linker_hack config_cross_build? && darwin? && RbConfig::MAKEFILE_CONFIG["EXTDLDFLAGS"].include?("-bundle_loader") end

（见 extconf.rb）

这段代码精确刻划了该 hack 的适用范围，三个条件缺一不可：

换句话说，这个 hack 是“按需触发”的：它不是对所有构建一律生效，而是精确命中“Ruby 3.2 交叉编译 Darwin 原生 gem”这一场景，避免影响其他平台与其他 Ruby 版本的常规构建路径。

注入-load_hidden：静态库链接行改写

if static_p static_archive_ld_flag = needs_darwin_linker_hack ? ["-load_hidden"] : [] $libs = $libs.shellsplit.map do |arg| case arg when "-lxml2" static_archive_ld_flag + [File.join(libxml2_recipe.path, "lib", libflag_to_filename(arg))] when "-lxslt", "-lexslt" static_archive_ld_flag + [File.join(libxslt_recipe.path, "lib", libflag_to_filename(arg))] else arg end end.flatten.shelljoin end

（见 extconf.rb）

这段代码的要点：

• 仅当静态链接（static_p）成立时才做改写；
• 只有在needs_darwin_linker_hack返回真时，才会在-lxml2、-lxslt、-lexslt对应的静态归档文件之前插入-load_hidden；
• 该标志只应用于 libxml2 / libxslt（以及 exslt），libgumbo 等其他静态组件不在此列——这也与 ADR 中“对两个库使用-load_hidden”的决策完全一致；
• 其他库参数原样保留，不影响原有链接顺序。

这里的-lxml2会被替换为指向libxml2_recipe.path下实际静态归档的路径（libflag_to_filename负责把-lxml2之类的链接标志换算成libxml2.a这样的文件名），确保链接的是 Nokogiri 自己打补丁构建的静态库，而不是系统库。

-flat_namespace的作用位点

-flat_namespace由 Ruby 3.2 的 mkmf 工具链行为触发，Nokogiri 的 extconf.rb 中同样保留了详尽的注释来解释它与-bundle_loader的关系（extconf.rb），并将“何时需要启用这些补救措施”的逻辑统一收敛到needs_darwin_linker_hack这一个判定函数中，方便后续维护与排查。

后果：收益与代价

收益：消除符号冲突，锁定 vendored 库版本

该策略带来的直接收益是：

• 防止意外的符号冲突：ADR 中提到的 Linux 平台上的同类问题即是前车之鉴（可类比于仓库 CHANGELOG.md 中记录的历史符号冲突问题，对应的 GitHub PR #2106），-load_hidden从机制上杜绝了这类问题在 Darwin 上重演；
• 始终使用期望的 libxml2：确保 Nokogiri 运行时加载的是经过补丁处理的、静态链接的 libxml2，而不是系统 dylib，从而避免 Ruby 3.2 场景下“错误 libxml2 被解析进来”的问题；
• 保持对--enable-shared/--disable-shared两种 Ruby 的兼容性：-flat_namespace保证了单一构建产物可用两种 Ruby 运行。

代价：收紧了对下游 C API 集成者的开放度

ADR 明确指出了反向代价：这一策略会阻止一小部分（但并非为零的）下游 gem 集成 Nokogiri 的 C API，以及 libxml2、libxslt、libgumbo 的 C API。ADR 中点名的典型例子包括：

• nokogumbo（现已被并入 Nokogiri 本体）——一个历史上直接使用 Nokogiri 底层 C API 的知名 gem；
• nokogiri-xmlsec及其各类 fork（如 instructure 维护的 fork）——一个利用 libxml2 C API 做 XML 签名/加密的集成方案。

因此，该决策可能在一定程度上抑制基于底层 C API 的实验与创新（如当年的 Nokogumbo），也会给 xmlsec 这类实用集成增加障碍。这是维护团队在“运行时正确性”与“C API 开放性”之间做出的明确取舍。

备选方案与未来展望

ADR 中记录了几个被认真评估过、但最终未被采纳的方案：

1. 从链接行移除-bundle_loader：技术上可行，但本质上是在与工具链和 Ruby 核心团队的行为“较劲”，方案更复杂、更难推演，且不能排除后续冒出未知副作用的风险，因此被否决。

2. 全面隐藏所有符号（fully hide all symbols everywhere）：这是当前方案的极端形态——对所有平台、所有库都不导出符号。ADR 指出这可能是未来的方向（仓库中亦有关于符号导出策略的 RFC 讨论 #2746 作为背景），但 v1.14.0 阶段不希望一次性彻底破坏兼容性。只在对的地方做最小干预，可以让团队有机会观察 C API 的真实使用方式，为后续决策收集反馈。

3. 停止预编译（stop precompiling）或停止 vendoring（stop vendoring libraries）：始终应被纳入选项清单，因为提供原生 gem 与内置（vendoring）库本身就会引入复杂度。但 ADR 强调，Nokogiri 之所以坚持这条路线，核心原因在于可以对 libxml2 打补丁——无论是为了性能（对应性能类 PR）、功能性（对应功能类 PR）还是安全性（对应安全类 PR），这些理由至今依然成立。

参考与延伸阅读

• 本决策的完整记录见 adr/2022-12-darwin-symbol-resolution.md；
• 实现代码见 ext/nokogiri/extconf.rb 与 extconf.rb；
• 仓库中另有一份姊妹 ADR adr/2023-04-libxml-memory-management.md，记录了 Nokogiri 在 libxml2 内存管理上的另一项长期架构决策（ruby_xmalloc与可选的系统 malloc），同属“C 扩展与运行时集成”主题，可对照阅读；
• 当前 misc/native.yml 中 Ruby 3.2 仍处于预编译支持列表内，说明该链接策略所服务的场景至今仍在持续；
• 更宏观的符号导出策略讨论（RFC #2746）表明，Nokogiri 未来可能走向“全面隐藏符号”的方向，本文介绍的-load_hidden方案可视作该方向的局部先行实践。

小结

Nokogiri 在 Darwin 平台上的符号解析问题，本质是“Ruby 3.2 工具链行为变化（-bundle_loader）→ 缓解手段（-flat_namespace）→ 新引入的系统库符号冲突 → 最终补救（-load_hidden）”这条因果链的层层收敛。最终决策通过三个条件的精确判定（交叉编译 + Darwin + 携带-bundle_loader）实现了最小化干预：只在 Ruby 3.2 交叉编译预编译 gem 时启用补救，既保障了运行时始终使用正确的、打过补丁的 libxml2/libxslt，又为未来更激进的符号导出策略保留了探索空间。对于所有在 Darwin 上发布预编译 Ruby 原生 gem 的维护者而言，这份 ADR 及其在 extconf.rb 中的实现，是一份难得的实战参考。

• 后端