Sherpa-onnx iOS动态库打包问题及解决方案

问题背景

在使用Sherpa-onnx的Dart/Flutter版本开发iOS应用时，开发者遇到了一个关键问题：当应用提交到App Store进行审核时，会被苹果拒绝。表面错误提示是"Invalid Swift Support - The SwiftSupport folder is missing"，但经过深入分析，实际原因是Sherpa-onnx的动态库(libsherpa-onnx-c-api.dylib)被直接放置在Frameworks目录的根目录下，这违反了苹果的应用打包规范。

技术分析

苹果对于iOS应用的动态库使用有严格规定：

1. 动态库不能直接以.dylib文件形式存在
2. 必须打包成.framework格式
3. .framework需要包含正确的目录结构和Info.plist文件

Sherpa-onnx原始构建系统生成的动态库直接以dylib形式存在，这会导致以下问题：

• 应用提交验证失败
• TestFlight部署后应用崩溃
• 动态链接符号无法正确解析

解决方案

完整修复步骤

1. 构建动态库 首先使用项目提供的构建脚本生成动态库文件：

   git clone https://github.com/k2-fsa/sherpa-onnx.git
   cd sherpa-onnx
   sh build-ios-shared.sh
   cd build-ios-shared
   

2. 合并模拟器架构 为支持不同模拟器架构，需要合并arm64和x86_64版本的动态库：

   mkdir ios-arm64_x86_64-simulator
   lipo -create ios-arm64-simulator/libsherpa-onnx-c-api.dylib \
        ios-x86_64-simulator/libsherpa-onnx-c-api.dylib \
        -output ios-arm64_x86_64-simulator/libsherpa-onnx-c-api.dylib
   

3. 转换为Framework格式(真机版)

   cd ios-arm64
   mkdir libsherpa-onnx-c-api.framework
   lipo -create libsherpa-onnx-c-api.dylib -output libsherpa-onnx-c-api
   mv libsherpa-onnx-c-api libsherpa-onnx-c-api.framework/
   rm -rf libsherpa-onnx-c-api.dylib
   cd libsherpa-onnx-c-api.framework
   install_name_tool -change @rpath/libsherpa-onnx-c-api.dylib \
        @rpath/libsherpa-onnx-c-api.framework/libsherpa-onnx-c-api libsherpa-onnx-c-api
   install_name_tool -id "@rpath/libsherpa-onnx-c-api.framework/libsherpa-onnx-c-api" \
        libsherpa-onnx-c-api
   chmod +x libsherpa-onnx-c-api
   cd ../..
   

4. 转换为Framework格式(模拟器版) 对模拟器版本执行类似操作：

   cd ios-arm64_x86_64-simulator
   mkdir libsherpa-onnx-c-api.framework
   lipo -create libsherpa-onnx-c-api.dylib -output libsherpa-onnx-c-api
   mv libsherpa-onnx-c-api libsherpa-onnx-c-api.framework/
   rm -rf libsherpa-onnx-c-api.dylib
   cd libsherpa-onnx-c-api.framework
   install_name_tool -change @rpath/libsherpa-onnx-c-api.dylib \
        @rpath/libsherpa-onnx-c-api.framework/libsherpa-onnx-c-api libsherpa-onnx-c-api
   install_name_tool -id "@rpath/libsherpa-onnx-c-api.framework/libsherpa-onnx-c-api" \
        libsherpa-onnx-c-api
   chmod +x libsherpa-onnx-c-api
   cd ../..
   

5. 添加Info.plist文件 在每个.framework目录中创建Info.plist文件，内容模板如下：

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>CFBundleDevelopmentRegion</key>
       <string>en</string>
       <key>CFBundleExecutable</key>
       <string>libsherpa-onnx-c-api</string>
       <key>CFBundleIdentifier</key>
       <string>your.bundle.identifier</string>
       <key>CFBundleInfoDictionaryVersion</key>
       <string>6.0</string>
       <key>CFBundleName</key>
       <string>libsherpa-onnx-c-api</string>
       <key>CFBundlePackageType</key>
       <string>FMWK</string>
       <key>CFBundleShortVersionString</key>
       <string>1.0.0</string>
       <key>CFBundleSupportedPlatforms</key>
       <array>
           <string>iPhoneOS</string>
       </array>
       <key>CFBundleVersion</key>
       <string>1</string>
       <key>MinimumOSVersion</key>
       <string>11.0</string>
   </dict>
   </plist>
   

6. 创建XCFramework 使用xcodebuild命令将两个架构的framework合并为XCFramework：

   xcodebuild -create-xcframework \
        -framework ios-arm64/libsherpa-onnx-c-api.framework \
        -framework ios-arm64_x86_64-simulator/libsherpa-onnx-c-api.framework \
        -output sherpa_onnx.xcframework
   

7. 集成到Flutter项目 将生成的sherpa_onnx.xcframework复制到iOS项目的Frameworks目录，并在Xcode中添加引用。

8. 修改Dart代码 更新动态库加载方式：

   void initBindings() {
     SherpaOnnxBindings.init(Platform.isAndroid
         ? DynamicLibrary.open('libsherpa-onnx-c-api.so')
         : DynamicLibrary.open(
             'libsherpa-onnx-c-api.framework/libsherpa-onnx-c-api'));
   }
   

官方更新

Sherpa-onnx团队在v1.10.31版本中已经集成了这个修复方案，开发者现在可以直接使用最新版本而无需手动执行上述步骤。这个更新解决了：

• 动态库打包规范问题
• App Store提交验证失败问题
• 运行时符号解析问题

总结

iOS应用对于动态库的使用有严格的规范要求，特别是提交到App Store时。Sherpa-onnx最初版本的动态库打包方式不符合苹果的要求，导致应用无法通过审核。通过将动态库转换为标准的Framework格式，并正确设置安装路径和标识符，可以解决这个问题。现在官方已经集成了这个修复方案，建议开发者升级到最新版本以获得最佳体验。