如何将DocC生成的文档与XCFramework一同分发并让Xcode识别？

核心问题原因 #

XCFramework默认不会自动将DocC生成的文档索引整合到Xcode的符号体系中，即便.swiftdoc文件存在于XCFramework内部，Xcode也无法直接关联到对应符号上。

实现步骤 #

1. 生成独立的DocC归档文件 #

先为框架生成.doccarchive格式的文档归档，执行以下命令：

xcodebuild docbuild -scheme YourFrameworkScheme -destination 'generic/platform=iOS' -derivedDataPath ./build

归档文件会生成在./build/Build/Products/Debug-iphoneos/YourFramework.doccarchive路径下。

2. 将DocC归档嵌入XCFramework打包流程 #

修改打包脚本，在生成XCFramework前，把.doccarchive复制到各架构归档的对应目录中：

# 先归档不同架构的framework
xcodebuild archive -scheme YourFrameworkScheme -destination 'generic/platform=iOS' -archivePath ./build/ios-arm64 SKIP_INSTALL=NO BUILD_LIBRARY_FOR_DISTRIBUTION=YES
xcodebuild archive -scheme YourFrameworkScheme -destination 'generic/platform=iOS Simulator' -archivePath ./build/ios-x86_64 SKIP_INSTALL=NO BUILD_LIBRARY_FOR_DISTRIBUTION=YES

# 复制doccarchive到每个归档的framework目录下
cp -r ./build/Build/Products/Debug-iphoneos/YourFramework.doccarchive ./build/ios-arm64.xcarchive/Products/Library/Frameworks/
cp -r ./build/Build/Products/Debug-iphonesimulator/YourFramework.doccarchive ./build/ios-x86_64.xcarchive/Products/Library/Frameworks/

# 生成包含文档的XCFramework
xcodebuild -create-xcframework -framework ./build/ios-arm64.xcarchive/Products/Library/Frameworks/YourFramework.framework -framework ./build/ios-x86_64.xcarchive/Products/Library/Frameworks/YourFramework.framework -output ./YourFramework.xcframework

3. 验证XCFramework结构 #

最终生成的XCFramework每个架构子目录下，需同时存在YourFramework.framework和YourFramework.doccarchive。Xcode集成后会自动识别归档，此时按住Option点击符号即可正常查看文档。

4. SPM分发的额外配置（若适用） #

如果通过Swift Package Manager分发XCFramework，需在Package.swift中指定文档资源：

let package = Package(
    name: "YourFramework",
    products: [
        .library(name: "YourFramework", targets: ["YourFramework"]),
    ],
    targets: [
        .binaryTarget(
            name: "YourFramework",
            path: "./YourFramework.xcframework",
            resources: [
                .process("YourFramework.doccarchive")
            ]
        ),
    ]
)

关键注意事项 #

• 必须开启BUILD_LIBRARY_FOR_DISTRIBUTION=YES，确保框架符号与文档的分发兼容性。
• 清理Xcode缓存（Cmd+Shift+K）并重启Xcode后再测试，避免旧缓存干扰结果。

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