在 iOS 上用 RealityKit/ARKit 构建…

适用于 iOS SwiftUI 项目中基于 RealityKit 和 ARKit 开发 AR/3D 场景，并需要处理实体加载、锚定放置、射线检测、手势交互、相机权限与能力检查时。

适用场景

解决思路

1. 在 Info.plist 中添加 `NSCameraUsageDescription`。
2. 在 iOS 上使用 `RealityViewCameraContent` 默认显示 AR 相机视图（iOS 18+、macOS 15+）；需要显式非 AR 回退时设置 `content.camera = .virtual`。
3. 基础 AR 不需要 entitlement；如果 AR 是应用核心功能，添加 `arkit` required-device capability；否则用 `isSupported` 门控 AR UI。
4. 在展示 AR UI 前检查具体 AR 配置的 `isSupported`，例如 `guard ARWorldTrackingConfiguration.isSupported else { showUnsupportedDeviceMessage(); return }`。
5. 使用关键类型：`RealityView` 是 SwiftUI 托管 RealityKit 内容的入口；`RealityViewCameraContent` 在 iOS 作为 AR 相机内容、在 macOS 为非 AR；`Entity` 是所有场景对象基类；`ModelEntity` 是带可见 3D 模型的实体；`AnchorEntity` 将实体绑定到真实世界锚点。
6. 使用 `RealityView` 作为 RealityKit 的 SwiftUI 入口，并在 `make` 闭包中创建初始场景内容。
7. 在 `make` 闭包中创建 `ModelEntity`，例如 `ModelEntity(mesh: .generateSphere(radius: 0.05), materials: [SimpleMaterial(color: .blue, isMetallic: true)])`，设置 `position = [0, 0, -0.5]`，再 `content.add(...)`。
8. 如果 `ARWorldTrackingConfiguration.isSupported` 为 false，在 `RealityView` 的 make 中将 `content.camera = .virtual`。
9. 使用 `update` 闭包响应 SwiftUI 状态变化；不要用它创建实体，而是在 make 中创建并命名实体，在 update 中按 `name` 查找并修改已有实体。
10. `update` 示例：在 make 中创建名为 `colorBox` 的 `ModelEntity`，在 update 中用 `content.entities.first(where: { $0.name == "colorBox" })` 找到后替换 `model?.materials`。
11. 加载 USDZ 模型时使用异步加载，例如 `if let robot = try? await ModelEntity(named: "robot") { ... }`，并设置 `position`、`scale` 后 `content.add(robot)`，避免阻塞主线程。
12. 用 ECS 给实体添加组件；需要物理时设置 `PhysicsBodyComponent(massProperties: .default, material: .default, mode: .dynamic)`。
13. 需要碰撞或交互时设置 `CollisionComponent(shapes: [.generateBox(size: [0.1, 0.1, 0.1])])`。
14. 需要手势输入时设置 `InputTargetComponent()`。
15. 使用 `AnchorEntity` 把内容锚定到检测到的表面或世界位置；例如 `AnchorEntity(.plane(.horizontal, classification: .floor, minimumBounds: [0.2, 0.2]))`，将模型作为 child 加入 anchor，再将 anchor 加入 content。
16. 根据用例选择锚点目标：`.plane(.horizontal, ...)` 用于水平面（地面、桌面），`.plane(.vertical, ...)` 用于垂直面（墙），`.plane(.any, ...)` 用于任意检测平面，`.world(transform:)` 用于固定世界空间位置。
17. 区分 RealityKit 场景查询与 ARKit 真实世界射线检测：`RealityViewCameraContent.ray(through:in:to:)` 返回 RealityKit 坐标系中的相机射线，只把屏幕点投影到虚拟场景，不证明检测到物理表面。
18. `RealityViewCameraContent.hitTest(point:in:query:mask:)` 命中由 `CollisionComponent` 形状变为可命中的虚拟实体；用于实体拾取和定向手势，不用于 ARKit 平面检测。
19. 简单放置到检测平面时使用 `AnchorEntity(.plane(...))`。
20. 需要一次性与真实世界表面相交时，使用 ARKit `ARRaycastQuery` 加 `ARSession.raycast(_:)`，然后用 `AnchorEntity(raycastResult:)` 锚定，例如 `let results = session.raycast(query); if let result = results.first { let anchor = AnchorEntity(raycastResult: result); anchor.addChild(model); content.add(anchor) }`。
21. 不要把实体 hit test 当作 ARKit 表面 raycast 的替代品。
22. 手势交互实体同时添加 `CollisionComponent` 和 `InputTargetComponent`。
23. 实现拖拽：给实体命名并添加组件后，使用 `.gesture(DragGesture().targetedToAnyEntity().onChanged { value in ... })`，在 onChanged 中取 `value.entity`，若有 `parent`，用 `entity.position = value.convert(value.location3D, from: .local, to: parent)` 更新位置。
24. 连续每帧逻辑使用 `SceneEvents.Update` 订阅，而不是 SwiftUI timer；保持订阅存活并使用 `event.deltaTime`。
25. 在 visionOS 上使用不同的 ARKit API 面：`ARKitSession`、`WorldTrackingProvider`、`PlaneDetectionProvider`；这些类型在 iOS 不可用。
26. iOS 上 RealityKit 通过 `RealityViewCameraContent` 自动处理 world tracking；iOS 架构或迁移时用 `ARWorldTrackingConfiguration.isSupported` 门控 AR，用 `RealityViewCameraContent` 承载内容，用 `Entity`/`ModelEntity` 构建场景并用 `AnchorEntity` 放置。
27. 交互交接：`CollisionComponent` + `InputTargetComponent` 处理 RealityKit 交互；`AccessibilityComponent` 处理实体无障碍元数据；详细 SwiftUI 手势和 VoiceOver/Switch Control 策略交给兄弟模块。
28. 将现有 `SCNView`/`SCNNode` 工作视为独立 SceneKit 路径或显式迁移到 RealityKit，不要混合场景图。
29. 不跳过 AR 能力检查：展示 AR 前做配置特定 support 检查，失败时显示非 AR 内容或明确不可用状态。
30. 不同步加载重型模型：不要在 `RealityView` make 中用 `try! Entity.load(named: "large-scene")`；改用 `try? await ModelEntity(named: "large-scene")`。
31. 不忘记交互实体的 collision 和 input target 组件；缺少时点击或拖拽会穿透。
32. 不在 `update` 闭包中创建新实体；因为 update 每次 SwiftUI 状态变化都运行，会重复添加；正确做法是在 `make` 中创建，在 `update` 中修改。
33. 不忽略相机权限：用 `AVCaptureDevice.authorizationStatus(for: .video)` 检查，未决定时 `await AVCaptureDevice.requestAccess(for: .video)`，授权后显示 RealityView，否则显示 `ContentUnavailableView` 等回退 UI。
34. 提交前核对：`NSCameraUsageDescription` 已设置；AR 设备能力已在展示 AR 视图前检查；相机权限已请求且拒绝有回退 UI；AR 为核心用途时已添加 `arkit` required-device capability；3D 模型在 make 闭包中异步加载；实体在 make 创建、在 update 修改而非创建；交互前提和兄弟交接遵循 Gestures 节；实体 hit test、相机射线和 ARKit 表面 raycast 遵循 Raycasting 区分；每帧逻辑使用 `SceneEvents.Update` 而非 SwiftUI timer；大场景用 `ModelEntity(named:)` 异步加载而非 `Entity.load(named:)`；锚实体按用例选择合适表面类型；为实体设置名称以便在 update 闭包查找。
35. 需要物理、动画、光照、ECS、无障碍和性能模式时，阅读 `references/realitykit-patterns.md`；其余 API 参考 RealityKit、RealityView、RealityViewCameraContent、RealityViewCamera、Entity、ModelEntity、AnchorEntity、ARKit、ARWorldTrackingConfiguration、ARRaycastQuery、ARSession.raycast(_:) 与 Loading entities from a file 的文档。

适用边界 · 注意事项

• 不适用于 Android、Web 或其他非 Apple 平台，也不适用于未使用 RealityKit/ARKit 的项目。
• 不要把 visionOS 特有的 `ARKitSession`、`WorldTrackingProvider`、`PlaneDetectionProvider` 直接套用到 iOS；iOS 用 `RealityViewCameraContent`。
• 项目仍以 `SCNView`/`SCNNode` 为独立 SceneKit 路径且未计划迁移时，不要混合 RealityKit 场景图。