Flutter集成Unity+WebRTC iOS端库加载失败问题求助

错误含义解释 #

dyld[2229]: Library not loaded: @rpath/webrtc.framework/webrtc
Referenced from: <8ECDDAEB-2E45-3DF8-A9EC-E9381CE0298B> /private/var/containers/Bundle/Application/73D4E57A-0A29-4364-A56C-F1D14D69DDAA/Runner.app/Frameworks/UnityFramework.framework/UnityFramework
Reason: tried: '/private/var/containers/Bundle/Application/73D4E57A-0A29-4364-A56C-F1D14D69DDAA/Runner.app/Frameworks/webrtc.framework/webrtc' (errno=2), '/usr/lib/swift/webrtc.framework/webrtc' (errno=2, not in dyld cache), '/private/preboot/Cryptexes/OS/usr/lib/swift/webrtc.framework/webrtc' (errno=2), '/usr/lib/swift/webrtc.framework/webrtc' (errno=2, not in dyld cache), '/private/preboot/Cryptexes/OS/usr/lib/swift/webrtc.framework/webrtc' (errno=2),...etc

错误里的Reason: tried: 指iOS动态链接器dyld启动APP时，找不到UnityFramework依赖的webrtc.framework，它按系统默认搜索路径依次尝试加载，但所有路径下都找不到该框架，最终抛出加载失败错误，导致APP卡在白屏无法启动。

问题背景 #

基于flutter_unity_widget: ^2022.2.0和flutter_webrtc: 0.9.23构建的Flutter应用，Android端运行正常，但iOS端启动时白屏并触发上述动态库加载错误。

Flutter环境信息：

[!] Flutter (Channel unknown, 3.7.10, on macOS 13.5 22G74 darwin-x64, locale en-GB)
[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 14.3.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2022.2)
[✓] VS Code (version 1.79.2)
[✓] Connected device (3 available)
[✓] HTTP Host Availability

解决步骤 #

• 检查WebRTC框架嵌入配置
  打开iOS项目的Xcode工程，进入Runner target的General标签页，查看Frameworks, Libraries, and Embedded Content列表：

  • 确认webrtc.framework存在，若缺失则点击+添加（通常来自flutter_webrtc的iOS依赖）；
  • 将webrtc.framework的Embed选项设置为Embed & Sign，确保框架被正确打包进APP。

• 验证UnityFramework的依赖路径
  找到UnityFramework.framework的Info.plist文件，检查LC_RPATH相关配置，确保包含@executable_path/Frameworks路径；
  在Xcode中进入UnityFramework target的Build Settings，搜索Runpath Search Paths，确认添加了@executable_path/Frameworks和@loader_path/Frameworks，并设置$(inherited)优先。

• 清理缓存并重新构建
  执行Flutter缓存清理命令：

  flutter clean
  flutter pub get
  

  进入iOS目录执行Pod清理与安装：

  cd ios
  pod deintegrate
  pod install
  

  在Xcode中执行Product > Clean Build Folder清理构建缓存，之后重新编译运行。

• 检查框架版本兼容性
  确认flutter_webrtc: 0.9.23的iOS版webrtc.framework与flutter_unity_widget: ^2022.2.0依赖的Unity版本是否存在兼容性冲突，尝试升级或降级其中一个库到适配版本。

• 确认Unity导出配置
  检查Unity导出iOS项目时的框架依赖设置，避免重复引入或错误配置WebRTC相关框架，防止与flutter_webrtc的依赖产生冲突。

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