基于Capacitor开发的iOS应用无法启动问题排查

问题描述 #

用Vue.js开发的Web应用，通过Capacitor移植到Android平台运行正常，但移植到iOS平台时，应用编译成功后启动即因SIGABRT终止，提示无法加载构建文件夹中的Capacitor库。

Podfile 配置 #

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

platform :ios, '13.0'
use_frameworks!

install! 'cocoapods', :disable_input_output_paths => true

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorApp', :path => '../../node_modules/@capacitor/app'
  pod 'CapacitorCamera', :path => '../../node_modules/@capacitor/camera'
  pod 'CapacitorHaptics', :path => '../../node_modules/@capacitor/haptics'
  pod 'CapacitorKeyboard', :path => '../../node_modules/@capacitor/keyboard'
  pod 'CapacitorStatusBar', :path => '../../node_modules/@capacitor/status-bar'
end

target 'App' do
  capacitor_pods
end

post_install do |installer|
  assertDeploymentTarget(installer)
end

运行错误日志 #

dyld[14090]: Library not loaded: @rpath/Capacitor.framework/Capacitor
  Referenced from: <56B96A3F-7B7F-374E-B1D5-D23A07AC84EE> /Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/App.debug.dylib
  Reason: tried: '/Users/martontoth/Library/Developer/Xcode/DerivedData/App-fswzvuauecnneohjcmrldgxdpzfz/Build/Products/Debug-iphonesimulator/Capacitor.framework/Capacitor' (no such file), '/Library/Developer/CoreSimulator/Volumes/iOS_22C150/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 18.2.simruntime/Contents/Resources/RuntimeRoot/usr/lib/swift/Capacitor.framework/Capacitor' (no such file), '/usr/lib/swift/Capacitor.framework/Capacitor' (no such file, not in dyld cache), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Capacitor.framework/Capacitor' (no such file), '/Library/Developer/CoreSimulator/Volumes/iOS_22C150/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 18.2.simruntime/Contents/Resources/RuntimeRoot/usr/lib/swift/Capacitor.framework/Capacitor' (no such file), '/usr/lib/swift/Capacitor.framework/Capacitor' (no such file, not in dyld cache), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Capacitor.framework/Capacitor' (no such file), '/Library/Developer/CoreSimulator/Volumes/iOS_22C150/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 18.2.simruntime/Contents/Resources/RuntimeRoot/usr/lib/swift/Capacitor.framework/Capacitor' (no such file), '/usr/lib/swift/Capacitor.framework/Capacitor' (no such file, not in dyld cache), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Users/martontoth/Library/Developer/CoreSimulator/Devices/2B165691-E1C2-4D0D-BAED-3022A689D026/data/Containers/Bundle/Application/7165A92D-5BDB-48A6-B46C-C783AD26D9A7/App.app/Frameworks/Capacitor.framework/Capacitor' (no such file), '/Library/Developer/CoreSimulator/Volumes/iOS_22C150/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 18.2.simruntime/Contents/Resources/RuntimeRoot/System/Library/Frameworks/Capacitor.framework/Capacitor' (no such file)

已确认Capacitor文件夹相对路径正确，且已在目标应用的Build Settings中添加@executable_path/Frameworks到Runtime Search Paths，但检查构建文件夹时发现未生成Frameworks目录，询问缺少哪些配置。

解决方案 #

1. 彻底重置Pod依赖 #

清理现有Pod缓存并重新安装，避免依赖残留问题：

# 删除Pod锁文件和Pods目录
rm -rf Podfile.lock Pods
# 清理CocoaPods全局缓存
pod cache clean --all
# 重新安装依赖
pod install

安装完成后，必须打开Xcode的.xcworkspace文件（而非.xcodeproj），确保Capacitor相关framework出现在Pods/Development Pods目录下。

2. 验证Framework嵌入配置 #

• 在Xcode中选中App target，进入General标签页
• 滚动到Frameworks, Libraries, and Embedded Content区域
• 检查所有Capacitor相关framework（如Capacitor、CapacitorApp等）的嵌入状态是否为Embed & Sign
• 若缺少对应framework，点击+按钮，从Pods/Products目录中添加，并设置嵌入方式为Embed & Sign

3. 检查Framework搜索路径 #

确保Build Settings中的搜索路径包含Pod依赖路径：

• 进入App target的Build Settings标签页
• 搜索Framework Search Paths
• 添加$(PROJECT_DIR)/Pods/Capacitor、$(PROJECT_DIR)/Pods/CapacitorApp等插件路径，设置为Recursive

4. 清理Xcode构建缓存 #

# 删除Xcode派生数据
rm -rf ~/Library/Developer/Xcode/DerivedData

之后在Xcode中执行Clean Build Folder（快捷键：Cmd + Shift + K），再重新构建运行项目。

5. 确认Capacitor版本一致性 #

检查package.json中Capacitor核心库与所有插件的版本是否一致，版本不匹配会导致构建异常。若版本不一致，更新到相同稳定版本后，执行npx cap sync ios同步iOS项目。

6. 排查静态/动态框架冲突 #

确保Podfile中的use_frameworks!未被注释，Capacitor插件均以动态框架方式集成，避免静态与动态框架混用导致的打包问题。

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