如何通过CLI命令构建原生Xcode DocC文档 适配Github Actions CI/CD流程

xcodebuild 从Xcode 13版本开始已经原生支持DocC文档构建，对应的docbuild子命令完全可以满足CI/CD场景下的CLI构建需求，具体实现方案如下：

1. 原生xcodebuild构建命令 #

根据你的项目目标平台选择对应命令即可：

• iOS 平台构建命令：

xcodebuild docbuild -scheme 替换为你的项目Scheme名 -destination 'generic/platform=iOS' -derivedDataPath ./DerivedData

• macOS 平台构建命令：

xcodebuild docbuild -scheme 替换为你的项目Scheme名 -destination 'generic/platform=macOS' -derivedDataPath ./DerivedData

参数说明：

• docbuild 是xcodebuild专门用于构建DocC文档的专属子命令
• -derivedDataPath 用于指定编译产物输出目录，方便CI流程中快速提取构建结果
• 构建完成后，生成的.doccarchive文档包会存储在./DerivedData/Build/Products/对应平台目录/路径下

2. Fastlane 集成方案 #

Fastlane 没有单独封装DocC构建的专属Action，但可以直接通过sh执行原生xcodebuild命令实现需求，示例lane配置：

lane :build_docc do
  # 执行DocC构建
  sh "xcodebuild docbuild -scheme 替换为你的项目Scheme名 -destination 'generic/platform=iOS' -derivedDataPath ./DerivedData"
  # 可在此处添加后续的文档移动、打包、上传等自定义逻辑
end

3. GitHub Actions 工作流配置示例 #

直接使用GitHub提供的macOS运行环境即可实现自动化构建，参考配置：

name: 构建DocC文档
on:
  push:
    branches: [ main ]

jobs:
  build-docc:
    runs-on: macos-13 # 建议使用macOS 12及以上版本，确保预装Xcode版本≥13
    steps:
      - name: 拉取项目代码
        uses: actions/checkout@v3

      - name: 指定Xcode版本
        run: sudo xcode-select -s /Applications/Xcode_14.3.app/Contents/Developer # 可根据你的项目需求调整Xcode版本

      - name: 执行DocC构建
        run: xcodebuild docbuild -scheme 替换为你的项目Scheme名 -destination 'generic/platform=iOS' -derivedDataPath ./DerivedData

      - name: 上传文档构建产物
        uses: actions/upload-artifact@v3
        with:
          name: 编译完成的DocC文档包
          path: ./DerivedData/Build/Products/Release-iphoneos/*.doccarchive

可选扩展：导出静态站点格式 #

如果需要生成可直接部署的静态HTML文档，可以在构建完成后执行以下命令处理生成的.doccarchive包：

$(xcrun --find docc) process-archive transform-for-static-hosting 替换为你的.doccarchive文件路径 --output-path ./docs_output

生成的静态文件可直接部署到任意静态站点托管服务中。

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