如何让XCFramework文档在Developer Documentation中完整可用？

这个问题是框架的DocC完整文档归档没有随集成流程被Xcode识别导致的：Quick Help展示docstring只需要读取源码/二进制旁的.swiftdoc轻量文件，但可跳转的完整文档、「Open in Developer Documentation」入口必须依赖完整构建的DocC资源，缺了就会跳「Page not available」，也不会出现在宿主项目的文档构建列表里。

框架端配置（必做） #

先把框架本身的文档构建配置改对，不管用什么渠道分发都要先做这步：

• 打开框架工程对应Target的Build Settings，搜索Generate Documentation，将Debug、Release模式下的配置都设为Yes（对应配置项为GENERATE_DOCUMENTATION = YES），不要只在Debug模式开启，否则打分发包时不会生成文档产物
• 如果用了DocC Catalog做扩展文档（包含教程、自定义文档页的场景），确认.docc目录已经勾选了对应框架Target的Membership，被加入到Compile Sources构建阶段，不是只放在工程目录里没关联Target
• 构建分发版本时，不要只编二进制，要执行文档构建流程，最终产物要包含和框架匹配的.doccarchive、.swiftdoc、.swiftsourceinfo三类文件。

SPM分发特殊配置 #

• 检查Package.swift的exclude配置，不要把.docc目录、文档相关路径误加进排除列表
• Swift Tools版本最低设为5.6，低于5.6的SPM版本不支持自动传递包的DocC文档
• 发二进制SPM包（xcframework格式）时，不要只传二进制，要把前面说的三类文档文件和二进制放在同一路径，手动绑定为Target资源。

CocoaPods分发特殊配置 #

CocoaPods默认不会自动处理DocC资源，必须在podspec里加对应配置：

# 保留DocC目录不被pod安装流程清理
spec.preserve_paths = '**/*.docc'
# 让pod target编译时自动生成文档
spec.pod_target_xcconfig = {
  'GENERATE_DOCUMENTATION' => 'YES'
}
# 预编译二进制场景下，把构建好的doccarchive绑定为资源
spec.resource_bundles = {
  'YourFrameworkName_Docs' => ['path/to/YourFrameworkName.doccarchive']
}

如果用vendored_frameworks引入预编译二进制，必须把.swiftdoc、.swiftsourceinfo文件和二进制framework放在同一目录下，不要只拷.framework文件夹里的二进制文件。

宿主项目验证 #

框架配置完重新集成后，按以下步骤操作验证：

1. 清Xcode构建缓存：按command + shift + k执行Clean，再手动删除DerivedData目录，重新完整Build一次项目
2. 不要只用快捷键构建文档，选Xcode菜单栏Product > Build Documentation，等构建完成后打开Developer Documentation窗口，在侧边栏Frameworks分类下找到你的框架，能找到就说明配置生效
3. 检查宿主项目Target的Build Settings，确认Other Swift Flags里没有手动添加-no-docc参数，有就删掉
4. 如果是闭源二进制集成，直接检查框架所在目录，确认三类文档文件和二进制同路径，缺文件就重新从框架构建产物里补全。

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