Swift嵌套Framework真机运行错误：未找到合适镜像

我之前也碰到过一模一样的坑！模拟器跑起来毫无问题，一到真机就弹出这个dyld加载失败的错误，折腾了好一阵才把所有可能的问题排查完，给你整理几个最有效的解决步骤：

1. 优先检查子Framework的「Embed & Sign」配置 #

这是最常见的原因——真机上没有把依赖的子Framework打包进App bundle里，而模拟器因为有系统缓存或者共享机制能找到它。

• 打开主App的Target，切换到General标签页，找到「Frameworks, Libraries, and Embedded Content」区域
• 找到你的子Framework（xxx.framework），确保它的Embed选项设置为Embed & Sign
• 主Framework（custom.framework）同样要设为Embed & Sign（如果它是动态Framework的话；静态Framework不需要Embed）

2. 验证Build Phases的依赖与拷贝配置 #

• 检查主Framework的Build Phases -> Link Binary With Libraries：确认已经添加了xxx.framework，并且状态是「Required」（除非是可选依赖）
• 主App的Build Phases -> Copy Files：如果之前没配置过，点击「+」添加两个Framework，Destination选择「Frameworks」，Subpath留空（不过正常来说「Embed & Sign」会自动处理这一步，但手动补一下更保险）

3. 核对Build Settings的关键配置 #

• 子Framework的Mach-O类型：打开子Framework的Build Settings，搜索Mach-O Type，必须设置为Dynamic Library（静态Framework不需要rpath，不会触发这个错误）
• Installation Directory：主Framework和子Framework的INSTALL_PATH都要设为@rpath（这是Xcode默认值，但如果被修改过要改回来）
• 主App的Runpath搜索路径：搜索LD_RUNPATH_SEARCH_PATHS，确保包含@executable_path/Frameworks和@loader_path/Frameworks，这两个路径是dyld在真机上查找内嵌Framework的关键

4. 清理缓存并彻底重构 #

缓存问题有时候会让配置修改不生效，必须彻底清理：

• 按下Cmd+Shift+K清理项目，再按Cmd+Option+Shift+K清理整个构建文件夹
• 删除真机和模拟器上已安装的App
• 重启Xcode（甚至重启电脑，遇到过缓存特别顽固的情况）
• 重新构建并运行到真机

5. 检查签名与架构匹配 #

真机对签名和架构的要求比模拟器严格得多：

• 签名一致性：确保子Framework、主Framework和主App使用同一个开发者团队/账号签名，Build Settings里的Code Signing Identity和Provisioning Profile配置正确
• 架构兼容性：用终端命令检查子Framework的架构是否包含真机的arm64：

  lipo -info /path/to/xxx.framework/xxx
  

  如果输出里没有arm64，需要在子Framework的Build Settings里设置Valid Architectures包含arm64，并且把Build Active Architecture Only在Release模式下设为No

你遇到的具体错误信息：

dyld: Library not loaded: @rpath/xxx.framework/xxx
Referenced from: /private/var/containers/Bundle/Application/81D1C716-915E-4DCA-893D-F934D56C8BAD/customDemo.app/Frameworks/custom.framework/custom
Reason: no suitable image found.

本质就是dyld在真机上找不到xxx.framework的可执行镜像，按照上面的步骤逐一排查，应该能解决问题。

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