使用jazzy构建Xcode项目文档时遇iOS模拟器设备匹配失败问题

以下是几个快速排查解决的方案：

• 指定具体模拟器设备
  先执行命令列出所有可用模拟器：

  xcrun simctl list devices
  

  从输出里找状态为Booted或Available的iOS模拟器，记下它的UDID或完整名称。然后在jazzy命令中添加目标参数，比如用UDID：

  jazzy --xcodebuild-arguments "-destination 'id=你的模拟器UDID'"
  

  或者用名称指定（注意名称要和列表里完全一致）：

  jazzy --xcodebuild-arguments "-destination 'platform=iOS Simulator,name=iPhone 15,OS=17.2'"
  

• 重置模拟器服务
  模拟器状态异常可能导致识别失败：

  1. 关闭Xcode和所有模拟器窗口
  2. 执行命令重置模拟器环境：

     xcrun simctl shutdown all && xcrun simctl erase all && killall Simulator && killall Xcode
     

  3. 重新打开Xcode，手动启动一次模拟器，再运行jazzy命令

• 更新jazzy并校验Xcode路径
  旧版本jazzy可能与新Xcode不兼容：

  gem update jazzy
  

  同时确认Xcode命令行工具路径正确：

  xcode-select -p
  

  如果输出不是/Applications/Xcode.app/Contents/Developer，手动设置路径：

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  

• 直接指定SDK版本构建
  跳过设备匹配环节，直接指定模拟器SDK版本：

  jazzy --xcodebuild-arguments "-sdk iphonesimulator17.2"
  

验证步骤 #

先单独用xcodebuild测试目标是否能正常构建（替换成你的项目Scheme名称）：

xcodebuild -scheme YourProjectScheme -destination 'platform=iOS Simulator,name=iPhone 15' build

如果这个命令能成功，把相同的-destination参数加到jazzy命令中即可。

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