PAYATHON 2026

如何让 iOS SDK 的 xcframework 依赖仅在使用时加载?

数据小许

结论

没有通用的 Xcode build setting,能让任意 Swift framework 保留直接 import 和原有调用方式,同时自动满足这三个条件。

如果需要允许外部依赖缺失,可以尝试 weak linking。不过,它既不保证依赖等到首次调用时才加载,也不保证任意 Swift SDK 在依赖缺失时都能正常启动。

如果需要控制加载时机,可以把依赖相关代码放进独立的功能 framework,由核心 SDK 在方法调用时通过 dlopen 加载,再通过明确的 C ABI 或 Objective-C 接口调用。缺少依赖时,在该方法中显式执行 fatalError,就能实现题目要求的调用时崩溃。

为什么 dynamic linking 仍会在启动时加载依赖

xcframework 是分发容器。构建 app 时,Xcode 会选择匹配平台和架构的库;运行时,dyld 加载的是其中的 Mach-O 动态库。

当 MyProprietarySDK.framework 强链接某个动态 framework 时,相应依赖会记录在它的 Mach-O 中,通常使用 LC_LOAD_DYLIB。dyld 加载 SDK 时就需要找到该依赖,因此即使相关方法从未执行,缺少 framework 也可能导致启动失败。

加载过程中有两个不同的动作:

  • 加载动态库及其依赖。
  • 将函数调用绑定到具体符号地址。

lazy binding 可以推迟部分符号绑定,但启动阶段仍需要找到强链接的库。

Do Not Embed 控制复制和嵌入行为,不会把强链接改成可选链接。即使 SDK target 不嵌入依赖,最终 app 仍可能需要嵌入它。

只要求依赖可以缺失:尝试 weak linking

在生成 MyProprietarySDK.framework 的 target 中,可以将外部动态 framework 改为 weak linking。在 Link Binary With Libraries 中将对应项从 Required 改为 Optional,或在 Other Linker Flags 中配置:

$(inherited) -weak_framework SomeDependency

将 SomeDependency 替换为实际的 framework 名称。如果产物叫 ExternalDependency.framework,就使用 ExternalDependency,不要填写 xcframework 的目录名。

核心 SDK 构建时仍需要找到该依赖,才能解析 import SomeDependency 并编译相关调用。weak linking 用于处理运行时依赖缺失,不能消除编译时依赖。

重新生成 SDK 后,可以检查最终二进制:

otool -l MyProprietarySDK.framework/MyProprietarySDK

找到该依赖对应的 load command,确认它是 LC_LOAD_WEAK_DYLIB。还要检查 app 和其他 framework 是否通过另一条依赖路径强链接了同一个库。只修改 app target,无法重写已经编译进 SDK 的依赖关系。

weak linking 有两个限制:

  1. framework 存在时,dyld 仍可能在启动阶段加载它,不能保证等到首次使用时才加载。
  2. 缺失的符号不会自动变成安全的 Swift Optional。如果 SDK 的初始化代码、类型元数据或其他提前执行的路径需要这些符号,仍可能在目标方法调用之前失败。

因此,不能仅凭增加 -weak_framework 就承诺题目中的三种行为,也不要把调用未经检查的缺失符号当作稳定的崩溃机制。如果需要明确控制失败位置,应在方法入口检查可用性并主动报错。

#if canImport(SomeDependency) 也无法解决这个运行时问题:它判断的是编译环境中是否存在模块,二进制 SDK 编译完成后,条件分支就已经确定。

按需加载:拆出功能 framework

可以将产物拆为:

MyProprietarySDK.framework
    核心功能,以及按需加载入口

OptionalFeature.framework
    使用 SomeDependency 的功能实现
    强链接 SomeDependency.framework

核心 SDK 不再直接 import SomeDependency,也不强链接 OptionalFeature.framework。相关方法仍然保留,实现改为加载功能模块。

需要该功能的接入方,将 OptionalFeature.framework、SomeDependency.framework 及其他所需动态依赖嵌入最终 app。不需要该功能的接入方可以省略它们。

功能模块应提供稳定的调用入口。例如,功能模块可以实现并导出以下 C ABI 函数:

void OptionalFeatureRun(void);

该函数内部再调用实际的外部依赖 API。这个声明只定义接口形状,具体实现取决于依赖提供的 API。如果用 C++ 实现,需要使用 extern "C" 保持符号名,并确保该入口在最终动态库中可见。

核心 SDK 的加载代码可以这样写:

import Foundation
import Darwin

public final class SomeSDKComponent {
    private var featureHandle: UnsafeMutableRawPointer?

    public init() {}

    public func thisMethodUsesTheExternalDependencies() {
        if featureHandle == nil {
            guard let frameworksURL = Bundle.main.privateFrameworksURL else {
                fatalError("Frameworks directory is unavailable")
            }

            let executableURL = frameworksURL
                .appendingPathComponent("OptionalFeature.framework")
                .appendingPathComponent("OptionalFeature")

            guard let handle = dlopen(
                executableURL.path,
                RTLD_NOW | RTLD_LOCAL
            ) else {
                let message = dlerror().map { String(cString: $0) }
                    ?? "Unknown loading error"
                fatalError("Cannot load OptionalFeature: \(message)")
            }

            featureHandle = handle
        }

        guard let handle = featureHandle,
              let symbol = dlsym(handle, "OptionalFeatureRun") else {
            fatalError("OptionalFeatureRun is unavailable")
        }

        typealias EntryPoint = @convention(c) () -> Void
        let run = unsafeBitCast(symbol, to: EntryPoint.self)
        run()
    }
}

这个示例假设功能模块的可执行文件名为 OptionalFeature,入口签名严格为 void OptionalFeatureRun(void),并且方法串行调用。实际使用时,需要按产物名称调整路径;如果方法可能被并发调用,还应同步加载和缓存过程。

第一次调用时,dlopen 会加载功能模块及其动态依赖。如果模块或依赖不存在,加载失败后会在当前方法中执行 fatalError。代码保留 handle,不执行 dlclose,以免后续调用使用已经卸载的代码。

不要通过猜测 Swift mangled name,直接把任意 Swift 方法转换成 C 函数指针。dlsym 只返回符号地址,无法检查签名是否匹配;示例中的转换依赖于事先约定好的 C ABI。

集成时需要检查什么

要实现延迟加载,从 app 启动时加载的二进制出发,不能存在通向可选功能模块或其外部依赖的强链接路径。否则,dyld 仍会提前处理这些依赖。

最终 app 还必须正确嵌入并签名所需 framework,并配置可解析其传递依赖的 @rpath。这里加载的是随 app 分发的代码,不需要在运行时下载 framework。

xcframework 内也可能装的是静态库。静态库的代码在链接阶段合入其他二进制,不能直接通过 dlopen 加载;需要先把相关代码构建进可加载的动态 framework。

验证时应覆盖题目中的三种组合:省略依赖且不调用、包含依赖并调用、省略依赖后调用。还应确认核心 SDK 的初始化过程不会提前触发可选功能。

如果只希望取消两套条件编译版本,不要求推迟实际加载时间,也可以让接入方显式注入功能实现:核心 SDK 定义协议,可选适配模块导入外部依赖并实现协议。这样无需手动处理 C ABI,未提供实现时同样可以在方法入口执行 fatalError。

备注:内容仅供参考。