react-native-vision-camera

react-native-vision-camera (v5)

VisionCamera v5 是 react-native-vision-camera 当前维护的最新版本。它完全基于 Nitro Modules 重写，引入了全新的 Constraints API、基于输出的架构、内存中的 Photo，并彻底脱离了 v4 的格式/属性模型。v4 中几乎所有 API 都已移除或更名——请将 v5 视为全新的 API，而非渐进式升级。

本技能用于路由。请先阅读此文件，然后加载与任务相匹配的参考文档。每份参考文档都可独立使用——只加载所需内容即可。

何时加载哪份参考文档

• 生产环境中的低延迟 GPU、ML、CV 或与帧联动的叠加层工作： 使用单独的 react-native-vision-camera-realtime 技能。只有在还需要了解设置或 API 基础知识时，才同时加载帧处理基础参考文档。
• 全新安装、在屏幕上显示 Camera、权限、最简样板代码 → references/quickstart-v5.md
• 迁移 v4 代码库、了解变更内容 → references/migration-v4-to-v5.md（当用户提到 v4、takePhoto、useCameraFormat、format 属性、照片/视频布尔属性或核心中的 CodeScanner 时，请首先加载此文档）
• 迁移整个 v4 屏幕——需要完整的迁移前后文件以便直接移植 → references/migration-templates.md（完整的可复制粘贴模板：拍照屏幕、视频屏幕、帧处理器+ML、条码扫描器、专业相机）
• 选择/附加输出、通过约束设置 fps/HDR/分辨率、会话生命周期 → references/outputs-and-constraints.md
• 帧处理器、worklet、异步帧处理、像素格式、编写原生插件 → references/frame-processors.md（当用户提到“帧处理器”、“worklet”、“对帧运行 ML”、“Nitro 插件”或“vision-camera-plugin-*”时加载）
• 拍摄照片（包括回调、RAW、HDR、预览图像）、录制视频、Recorder 生命周期、手动 AE/AF/AWB、曝光补偿、变焦、对焦 → references/capture-and-controls.md
• 深度流、多摄像头、Skia 预览、用于 ML 的 GPU 缩放器、条码扫描器包、GPS 位置元数据、自定义原生输出 → references/advanced-features.md

不确定时，请加载 references/migration-v4-to-v5.md——该文档通过与 v4 对比，介绍新 API 的整体结构，是快速了解新 API 的最佳途径。

v5 代码的硬性规则

以下规则专门提醒那些“熟悉”v4 的人。请直接遵守，无需询问：

1. 安装 Nitro peer 依赖。 react-native-nitro-modules 和 react-native-nitro-image 是必需的 peer 依赖。帧处理器还需要 react-native-vision-camera-worklets 和 react-native-worklets（Software Mansion 的版本，而不是 -core）。Worklets - https://docs.swmansion.com/react-native-worklets/docs/

2. outputs={[...]} 取代 photo / video / frameProcessor / codeScanner 属性。 使用 usePhotoOutput、useVideoOutput、useFrameOutput、useDepthOutput、useObjectOutput（或使用条码包中的 useBarcodeScannerOutput）创建输出，并将它们放入数组传入。捕获方法（capturePhoto、createRecorder）属于 Output，而不是 Camera ref。

3. 没有 format 属性，也没有 useCameraFormat。 使用 constraints={[...]}——数组顺序就是优先级，按降序排列。Camera 会自动协商最接近的受支持配置，因此 { fps: 99999 } 这样的不可能约束不会导致错误。

4. 不存在 takePhoto()。 使用 photoOutput.capturePhoto(settings, callbacks) 获取内存中的 Photo，或使用 photoOutput.capturePhotoToFile(...) 获取文件路径。默认路径是在内存中——除非明确要求，否则不要写入临时文件。

5. 帧处理器插件必须是 Nitro Modules。 v4 的 FrameProcessorPlugin 基类、VISION_EXPORT_SWIFT_FRAME_PROCESSOR 宏和 VisionCameraProxy.addFrameProcessorPlugin 已移除。v5 插件是具有类型化 Nitro 规范的 HybridObject。请参阅 references/frame-processors.md。

6. 每个 Frame（和 Depth）都必须调用 .dispose()。 缓冲池容量有限；泄漏帧会导致管线停滞。请用 try { ... } finally { frame.dispose() } 包裹处理逻辑。通过 asyncRunner.runAsync(...) 转交任务时，如果返回 true，请在异步回调中释放；如果返回 false，则在 else 分支中立即释放。

7. CodeScanner 不属于核心包。 react-native-vision-camera-barcode-scanner 是独立包，在两个平台上都基于 MLKit。对于仅限 iOS 的物体检测（通过原生 AVFoundation 元数据检测二维码、人脸、人体，不依赖 ML），请使用核心包中的 useObjectOutput。

8. 保持 Camera 挂载；通过 isActive 切换状态。 重新挂载会拆除会话。请与 react-navigation 中的 useIsFocused() 集成，以便在屏幕不可见时让会话从 Idle 进入 Ready，并保留偏好设置，以便快速恢复。

9. 帧输出的 pixelFormat 默认值为 'native'（零拷贝），而不是 'yuv'。 'native' 会以会话协商出的 nativePixelFormat 进行流式传输，不执行格式转换（可能会解析为 YUV、RGB、RAW 或 'private' 格式；请通过 frame.pixelFormat 确认实际格式）。'yuv' 会选择最接近 native 格式的 YUV 格式，是通用场景下最适合 CPU 访问的选项（MLKit/OpenCV/Skia）；'rgb' 会强制执行 YUV 到 RGB 的转换，带宽约增加 2.6 倍，因此只有在使用方明确要求 RGB 时才使用它。useDepthOutput 没有 pixelFormat 选项。对于要求 CPU 可见 RGB 或张量输入的 ML 使用方，建议使用 react-native-vision-camera-resizer，而不是在 Camera 管线中承担逐帧 RGB 转换的开销。

10. 不要用 Math.min/Math.max 手动限制 FPS/分辨率。 这是 v4 的权宜之计。v5 的 Constraints API 会在内部进行协商——表达你的意图，然后让 Camera 选择。

11. v5 中，Worklets 会直接修改 Reanimated SharedValues。 这适用于常规异步 UI 或动画状态。对于与帧同步的叠加层，请使用单独的实时技能，并使用 Skia 或 WebGPU 绘制同一帧。

此技能的操作规则

• 切勿臆造 v4→v5 API 形式。如果参考资料中没有记录某个 v4 API 对应的 v5 API，请明确说明，并链接到 v5 文档——不要猜测。

• 除非用户提出要求，否则不要添加文档文件（README、CHANGELOG）。

• 除非用户展示 v4 代码，否则假定用户使用的是 v5。如果用户展示了 v4 代码，请先加载 references/migration-v4-to-v5.md，再开始编写。

• 编写新的 Camera 示例时，默认使用基于 Hook 的声明式形式（useCameraPermission + useCameraDevice + usePhotoOutput + <Camera />）。只有当用户要求多摄像头或完全通过代码控制时，才使用命令式的 VisionCamera.createCameraSession(...) API。

• 对于需要消费者获取 CPU 可见输入的基础 ML 路径，建议使用 react-native-vision-camera-resizer，而非 v4 时代的 vision-camera-resize-plugin。对于对延迟敏感的 ML、GPU 推理和实时叠加，则使用 react-native-vision-camera-realtime，不要一概推荐 Resizer。

• 验证对等依赖项是否已安装。用户报告安装后发生原生崩溃时，95% 的情况下是遗漏了 react-native-nitro-modules、react-native-nitro-image，或（用于帧处理器的）react-native-worklets + react-native-vision-camera-worklets。

权威链接

• 文档：https://visioncamera.margelo.com
• llms.txt 索引：https://visioncamera.margelo.com/llms.txt
• V5 发行说明（包含迁移代码片段）：gh api repos/mrousavy/react-native-vision-camera/releases/tags/v5.0.0
• 博客公告：https://blog.margelo.com/whats-new-in-visioncamera-v5
• 主仓库：https://github.com/mrousavy/react-native-vision-camera
• V4 快照（已存档的文档）：https://visioncamera4.margelo.com