XCFramework Bundle资源引用异常：图片加载失败求助

问题背景 #

开发XCFramework格式的SDK时，SDK内Assets.xcassets中的图片无法在集成的iOS应用中显示。尝试直接调用Image("neko")、指定Bundle ID、通过Dummy类获取Bundle等方式均失败；将图片复制到主应用的Asset Catalog则可正常显示。使用xcodebuild构建的XCFramework替换原生framework后问题依旧，且主应用中Bundle.allFrameworks未加载SDK的Bundle。

解决方案 #

1. 确保SDK的Asset Catalog正确配置 #

• 打开SDK Target的Build Settings，找到Asset Catalog Compiler Options -> Asset Catalogs，确认已添加Assets.xcassets（路径需准确指向资源文件）。
• 检查SDK Target的Info.plist，确保CFBundleIdentifier（如com.example.Example）已正确设置，且与代码中使用的Bundle ID完全一致。

2. 正确获取SDK的Bundle #

方式一：使用Bundle.module（推荐）

Swift Package Manager和Xcode 11+构建的XCFramework会自动生成Bundle.module属性，直接调用即可定位SDK资源：

public var body: some View {
    HStack {
        Image("neko", bundle: .module)
            .resizable()
            .frame(width: 100, height: 100)
    }
}

方式二：手动实现Bundle扩展（非SPM场景）

如果是手动构建XCFramework，需手动添加Bundle扩展来定位SDK资源：

import Foundation

// SDK内定义空公共类，用于定位Bundle
public class Dummy: NSObject {}

extension Bundle {
    public static var module: Bundle {
        let frameworkName = "Example" // SDK的framework名称（不含.framework后缀）
        let possiblePaths = [
            // 开发阶段的资源路径
            Bundle.main.resourceURL?.appendingPathComponent("\(frameworkName).framework"),
            // 集成后的资源路径
            Bundle(for: Dummy.self).resourceURL,
            // 主Bundle兜底路径
            Bundle.main.bundleURL
        ]
        
        for path in possiblePaths {
            guard let url = path, let bundle = Bundle(url: url) else { continue }
            return bundle
        }
        fatalError("无法找到SDK的Bundle资源，请检查集成配置")
    }
}

之后同样使用Image("neko", bundle: .module)调用图片。

3. XCFramework构建与集成注意事项 #

• 构建XCFramework时：使用xcodebuild命令需确保资源被完整包含，示例命令：

# 归档iOS设备版本
xcodebuild archive -scheme Example -destination "generic/platform=iOS" -archivePath "./build/Example-iOS.xcarchive" SKIP_INSTALL=NO
# 归档iOS模拟器版本
xcodebuild archive -scheme Example -destination "generic/platform=iOS Simulator" -archivePath "./build/Example-iOSSimulator.xcarchive" SKIP_INSTALL=NO
# 合并为XCFramework
xcodebuild -create-xcframework -framework "./build/Example-iOS.xcarchive/Products/Library/Frameworks/Example.framework" -framework "./build/Example-iOSSimulator.xcarchive/Products/Library/Frameworks/Example.framework" -output "./build/Example.xcframework"

• 集成XCFramework时：在主应用的Frameworks, Libraries, and Embedded Content中，将XCFramework的Embed选项设置为Embed & Sign，确保framework被正确嵌入到App包中。

4. 调试验证 #

• 在SDK代码中打印Bundle路径，确认资源加载路径正确：

print("SDK Bundle Path: \(Bundle.module.bundlePath)")

• 在主应用中打印已加载的Bundle，确认SDK的Bundle被成功加载：

let sdkBundle = Bundle.allFrameworks.first { $0.bundleIdentifier == "com.example.Example" }
print("Loaded SDK Bundle: \(sdkBundle?.bundlePath ?? "Not Found")")

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