iOS项目集成.dylib真机崩溃：Library not loaded: @rpath/somelib.dylib

问题场景 #

要在Swift项目中调用第三方.dylib的C方法，因苹果禁止直接嵌入.dylib，尝试了两种封装方案：

• 封装包含.dylib和头文件的.xcframework
• 通过lipo合并多架构二进制后封装成.framework

两种方案编译都能通过，但真机运行时直接崩溃，报错如下：

dyld[38413]: Library not loaded: @rpath/somelib.dylib
  Referenced from: <6519D385-F3EB-3454-8CA0-02BF7E536629> /private/var/containers/Bundle/Application/D1A6139C-EC53-46DA-A647-4A520E4F112C/TestApp.app/TestApp
  Reason: tried: '/usr/lib/system/introspection/somelib.dylib' (errno=2, not in dyld cache), '/private/var/containers/Bundle/Application/D1A6139C-EC53-46DA-A647-4A520E4F112C/TestApp.app/Frameworks/somelib.dylib' (errno=2), '/private/var/containers/Bundle/Application/D1A6139C-EC53-46DA-A647-4A520E4F112C/TestApp.app/Frameworks/somelib.dylib' (errno=2), '/private/preboot/Cryptexes/OS@rpath/somelib.dylib' (errno=2), '/private/var/containers/Bundle/Application/D1A6139C-EC53-46DA-A647-4A520E4F112C/TestApp.app/Frameworks/somelib.dylib' (errno=2), '/private/var/containers/Bundle/Application/D1A6139C-EC53-46DA-A647-4A520E4F112C/TestApp.app/Frameworks/somelib.dylib' (errno=2), '/usr/local/lib/somelib.dylib' (errno=2), '/usr/lib/somelib.dylib' (errno=2, not in dyld cache)

用到的.h头文件内容：

#ifdef __cplusplus
extern "C" {
#endif

void ms_init(int width, int height);
void ms_draw();

#ifdef __cplusplus
}
#endif

修复步骤 #

1. 确认封装库的嵌入配置 #

• 检查封装的framework/xcframework内部结构：确保.dylib被放在正确的子目录（framework中是YourFramework.framework/Versions/A/Frameworks/，xcframework对应架构目录下的Frameworks）
• 打开主App的Build Phases → Embed Frameworks，确认已添加你的封装库，且Code Sign on Copy选项已勾选

2. 修正动态库的安装路径（Install Name） #

用otool查看原.dylib的当前安装路径：

otool -L somelib.dylib

如果输出中somelib.dylib的路径是@rpath/somelib.dylib，需要修改为适配封装库的路径。比如封装成MyWrapper.framework的话，路径应为：

@rpath/MyWrapper.framework/Frameworks/somelib.dylib

执行以下命令修改安装路径：

install_name_tool -id "@rpath/MyWrapper.framework/Frameworks/somelib.dylib" somelib.dylib

修改完成后重新封装framework/xcframework

3. 配置主App的运行路径 #

• 进入主App的Build Settings → Runpath Search Paths，确保包含@executable_path/Frameworks和@loader_path/Frameworks（默认配置一般已有，需确认未被删除）
• 检查Framework Search Paths是否添加了封装库所在的目录路径

4. Swift调用的桥接配置 #

• 创建Objective-C桥接头文件（比如BridgeHeader.h），导入你的.h文件：

#import "somelib.h"

• 在主App的Build Settings → Objective-C Bridging Header中设置该文件的相对路径（例如TestApp/BridgeHeader.h）
• 之后即可在Swift中直接调用方法：

ms_init(100, 100)
ms_draw()

内容的提问来源于stack exchange，提问作者Eduard