RoomPlan API导出CapturedRoom至USDZ时出现路径错误求助

使用RoomPlan API采集的数据存储在CapturedRoom类型的finalResult变量中，尝试将其导出为USDZ文件到本地文件管理器时，操作偶尔失败，触发以下错误：

Coding Error: in _IsValidPathForCreatingPrim at line 3338 of usd/stage.cpp -- Path must be an absolute path: <>
cannotCreateNode(path: "/9EE71ED0F8D6415496A7B9F0C3671DB0321")

当前使用的保存代码如下：

func saveFileLocal() {
      if let finalResult {
          let fm = FileManager.default
          let documentsURL = fm.urls(for: .documentDirectory, in: .userDomainMask).first!
          //let documentsURL = URL.documentsDirectory
          let fileName = "\(UUID().uuidString).usdz"
          let fileURL = documentsURL.appendingPathComponent(fileName)
          do {
              try finalResult.export(to: fileURL)
          } catch {
              print(error)
          }
      }
  }

1. 强制确保路径绝对化并优化文件名 #

虽然UUID生成的文件名通常合规，但底层偶尔会对纯哈希字符串的路径处理异常。可以给文件名加前缀，同时显式获取绝对路径：

func saveFileLocal() {
    guard let finalResult else { return }
    let fm = FileManager.default
    guard let documentsURL = fm.urls(for: .documentDirectory, in: .userDomainMask).first else {
        print("无法获取文档目录")
        return
    }
    // 给文件名添加前缀，避免纯哈希字符串开头
    let fileName = "capture_\(UUID().uuidString).usdz"
    // 显式获取绝对路径
    let fileURL = documentsURL.appendingPathComponent(fileName).absoluteURL
    do {
        try finalResult.export(to: fileURL)
    } catch {
        print(error)
    }
}

2. 提前校验并创建目录 #

偶发情况下文档目录可能因权限或系统问题未正确初始化，提前确保目录存在：

func saveFileLocal() {
    guard let finalResult else { return }
    let fm = FileManager.default
    guard let documentsURL = fm.urls(for: .documentDirectory, in: .userDomainMask).first else {
        print("无法获取文档目录")
        return
    }
    do {
        // 确保目录存在，已存在则无操作
        try fm.createDirectory(at: documentsURL, withIntermediateDirectories: true)
        let fileName = "capture_\(UUID().uuidString).usdz"
        let fileURL = documentsURL.appendingPathComponent(fileName).absoluteURL
        try finalResult.export(to: fileURL)
    } catch {
        print(error)
    }
}

3. 避免多线程并发冲突 #

如果saveFileLocal()可能在多线程被调用，用串行队列保证文件操作的原子性：

private let fileOperationQueue = DispatchQueue(label: "com.yourapp.roomplan.file")

func saveFileLocal() {
    guard let finalResult else { return }
    fileOperationQueue.async {
        let fm = FileManager.default
        guard let documentsURL = fm.urls(for: .documentDirectory, in: .userDomainMask).first else {
            print("无法获取文档目录")
            return
        }
        do {
            try fm.createDirectory(at: documentsURL, withIntermediateDirectories: true)
            let fileName = "capture_\(UUID().uuidString).usdz"
            let fileURL = documentsURL.appendingPathComponent(fileName).absoluteURL
            try finalResult.export(to: fileURL)
        } catch {
            print(error)
        }
    }
}

4. 增强错误排查信息 #

修改错误处理逻辑，打印完整错误栈，方便定位偶发问题：

catch {
    print("USDZ导出失败：\(error.localizedDescription)")
    print("错误完整信息：\(error)")
    // 打印调用栈，定位异常触发点
    Thread.callStackSymbols.forEach { print($0) }
}

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