企业官网建设流程全解析

1. 项目概述：为什么二维码扫描在 React Native 里不是“装个包就能用”的事

最近帮某高校实验室做一款校园服务类 App 的跨平台版本，核心功能之一是让学生用手机扫课表二维码快速跳转选课页，同时支持从相册里挑一张带二维码的截图识别——听起来就是调个react-native-camera或react-native-qrcode-scanner就完事？我最初也这么想。结果从环境初始化到真机调试，前后踩了整整 11 个坑，光是 iOS 的Info.plist权限配置就改了 5 轮，安卓端更是在build.gradle里反复注释/反注释android.useAndroidX=true和android.enableJetifier=true这两行，折腾了两天才跑通第一帧预览画面。这不是个别现象，而是 React Native 生态里一个典型的“表面简单、底层复杂”的高频场景：二维码扫描不是纯 JS 功能，它强依赖原生摄像头模块、图像处理管线、权限生命周期管理、以及不同 Android 版本对 Camera2 API 的兼容策略。你写的 JS 代码只占整个链路的 30%，剩下 70% 是桥接层、原生模块、系统级配置和运行时状态同步。所以这篇日记不叫“React Native 二维码集成指南”，而叫“踩坑日记”——因为所有能搜到的教程都默认你已搞定 Xcode 工程配置、Gradle 插件版本对齐、NDK 构建缓存清理这些“前置隐形门槛”。而现实是，90% 的失败案例，根本没走到“写 JS 逻辑”这一步，卡死在npm run ios报RCTCameraManager not found或者安卓模拟器直接黑屏无预览。本文记录的是从零开始、不跳过任何环节、逐个击破的真实路径，所有命令、配置、参数值均来自实测（iOS 17.5 + Xcode 15.4，Android 13 + Pixel 4a 真机），不假设你有原生开发经验，但要求你愿意打开终端、编辑.plist文件、看懂 Gradle 错误堆栈。适合正在被扫码功能卡住进度的中初级 RN 开发者，也适合想搞清“JS 桥接原生到底发生了什么”的进阶同学。

2. 整体设计思路与方案选型：为什么放弃“一键式”库，坚持手搭双模块架构

2.1 三种主流方案的硬伤对比

刚接手时，我快速扫了一遍社区方案，发现主流就三类：

• 纯 JS 解码库（如jsqr）：优点是零原生依赖，npm install后直接import；缺点是必须先拿到图片数据（base64 或 Uint8Array），意味着你要自己实现拍照/选图 → 裁剪 → 传给 JS → 解码的全链路，且jsqr对模糊、倾斜、低对比度二维码识别率极低，实测 10 张相册截图仅识别出 3 张，完全不可商用。

• 封装完善的“全家桶”库（如react-native-qrcode-scanner）：优点是 API 简洁，<QRCodeScanner onRead={...} />一行搞定；缺点是过度封装导致定制性为零——比如你想在扫描框上加个“点击放大镜图标切换闪光灯”，它不提供torchMode控制接口；再比如你想限制只扫 QR Code 不扫条形码，它底层用的AVCaptureMetadataOutput默认开启全部类型，关掉就得改原生代码。

• 分层解耦的手动集成（本方案采用）：即用react-native-vision-camera（替代已废弃的react-native-camera）负责摄像头预览与帧捕获，用react-native-vision-camera-code-scanner作为其插件处理实时解码，相册识别则用react-native-image-picker拿到图片后，通过@react-native-community/blur做轻量级预处理，再交由react-native-vision-camera-code-scanner的静态解码 API 处理。这个方案工作量最大，但换来的是：① 预览性能可控（VisionCamera 支持frameProcessor低延迟处理）；② 权限粒度精确（可单独请求相机/相册/定位权限）；③ 错误可追溯（帧捕获失败、解码超时、图片格式不支持等错误均有明确回调）。

提示：选择手动集成不是为了炫技，而是因为业务方明确要求“扫描失败时显示具体原因：是光线太暗？还是图片模糊？或是非标准二维码？”——这种颗粒度的需求，任何黑盒库都无法满足。

2.2 为什么 VisionCamera 是当前唯一可靠选择

2024 年中，react-native-camera已停止维护，其衍生库react-native-camera-kit在 Android 12+ 上频繁崩溃；而react-native-vision-camera由同一作者（Mikael Rågård）主导，核心优势在于：

• 真正的零拷贝帧传递：VisionCamera 的frameProcessor可直接在原生线程处理Frame对象，无需将 YUV 数据序列化为 JS 对象再传回，避免了 300ms+ 的序列化开销。实测在 iPhone 13 上，1080p 预览下解码延迟稳定在 80~120ms，而旧方案普遍在 350ms 以上。

• 声明式权限管理：它内置useCameraDevices()Hook，自动根据设备能力返回back/front/ultra-wide等设备对象，并附带isMultiCamSupported、supportsFlash等布尔属性，让你在 JS 层就能做“如果设备支持闪光灯，则渲染开关按钮”这类逻辑，不用写原生判断。

• 渐进式降级策略：当用户拒绝相机权限时，它不会直接报错，而是返回undefined设备，你可以在 UI 上优雅提示“请前往设置开启相机权限”，而不是让 App 白屏崩溃。

注意：VisionCamera 要求 React Native ≥ 0.71，且 iOS 必须启用 Swift 支持（use_frameworks!）。如果你的项目还在 RN 0.68，升级是必选项，别试图降级适配——我试过用 patch-package 强行兼容，结果在 M1 Mac 上构建失败 7 次，最终花半天升级 RN，反而节省了三天排错时间。

2.3 相册识别为何不能复用摄像头解码器

这里有个关键认知误区：很多人以为“同一个解码库，既能在摄像头流里用，也能在静态图里用”。但 VisionCamera 的codeScanner插件设计上，scanCodes函数是绑定在Frame实例上的，而Frame对象只能由 VisionCamera 的useCameraDevice创建的摄像头生成。相册图片是ImagePickerResponse返回的uri字符串，两者数据源完全不同。强行把 uri 转成 Frame 会触发Invalid frame type错误。正确做法是：相册流程走独立路径——用react-native-vision-camera-code-scanner提供的静态解码函数scanCodesFromImage，它接受uri或base64，内部会自动加载图片、转换色彩空间、调用底层解码器。这个函数不依赖摄像头实例，是真正意义上的“离线解码”。

3. 核心细节解析与实操要点：从环境初始化到首帧预览的完整链路

3.1 iOS 端：Xcode 配置的 5 个致命细节

很多教程只说“在Info.plist里加NSCameraUsageDescription”，但实际远不止于此。我在 Xcode 15.4 中，为让 VisionCamera 正常工作，必须完成以下 5 步，缺一不可：

1. 启用 Swift 支持并指定版本：在ios/Podfile顶部添加：

   # 必须放在 platform :ios, '12.0' 之后 use_frameworks! $RNFirebaseAsStaticFramework = true

   然后在ios/YourApp.xcworkspace中，右键YourApp→New File→ 选择Swift File→ 保存时 Xcode 会弹窗问“是否创建 Bridging Header”，点Create。这一步强制 Xcode 初始化 Swift 环境，否则 VisionCamera 的 Swift 模块无法链接。

2. Info.plist 权限描述必须完整：除了基础的相机和相册，VisionCamera 还可能用到麦克风（用于某些 AR 场景的音频同步），所以Info.plist至少要包含：

   <key>NSCameraUsageDescription</key> <string>需要访问相机以扫描二维码</string> <key>NSPhotoLibraryUsageDescription</key> <string>需要访问相册以识别图片中的二维码</string> <key>NSMicrophoneUsageDescription</key> <string>需要访问麦克风以支持增强现实功能</string> <!-- 如果你的 App 有定位需求，还需加 --> <key>NSLocationWhenInUseUsageDescription</key> <string>需要定位以提供基于位置的服务</string>

3. Link Binary With Libraries 必须手动添加：打开YourApp→Build Phases→Link Binary With Libraries，点击+号，搜索并添加：

   • libRNVisionCamera.a
   • libRNVisionCameraCodeScanner.a
   • libc++abi.tbd（这是 C++ 异常处理库，缺失会导致std::bad_cast崩溃）

4. Build Settings 中的两个关键开关：

   • Enable Bitcode：设为NO（VisionCamera 官方明确要求，设为 YES 会导致 Archive 失败）
   • Always Embed Swift Standard Libraries：设为YES（确保 Swift 运行时随 App 打包）

5. Podfile 中的 post_install 钩子：这是最容易被忽略的一步。VisionCamera 依赖CocoaPods的use_modular_headers!，但 RN 默认不启用。在ios/Podfile底部添加：

   post_install do |installer| react_native_post_install(installer) installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.9' config.build_settings['ENABLE_BITCODE'] = 'NO' end end end

   然后执行cd ios && pod deintegrate && pod install --repo-update。不执行pod deintegrate，旧的.xcworkspace缓存会干扰新配置。

实操心得：每次修改Info.plist或Build Settings后，必须Clean Build Folder（Xcode 菜单栏Product → Clean Build Folder），再Cmd+R运行。我曾因忘记 Clean，导致修改了 3 小时的权限描述始终不生效，最后发现 Xcode 在用旧的缓存二进制。

3.2 Android 端：Gradle 配置与权限的 4 层校验

安卓的坑比 iOS 更隐蔽，因为它允许你“看似成功运行”，但实际摄像头打不开。我总结出必须校验的 4 层：

第一层：Gradle 版本对齐
android/build.gradle中：

// 必须匹配 RN 官方推荐版本 ext { buildToolsVersion = "34.0.0" minSdkVersion = 21 compileSdkVersion = 34 targetSdkVersion = 34 ndkVersion = "25.1.8937393" }

注意ndkVersion必须精确到小数点后，VisionCamera 3.15.0 要求25.1.8937393，用25.2会报NDK version mismatch。

第二层：app/build.gradle 的 kotlin 和 compose 配置

android { namespace "com.yourapp" compileSdk 34 defaultConfig { applicationId "com.yourapp" minSdk 21 targetSdk 34 versionName "1.0" versionCode 1 // 必须添加这一行，否则 VisionCamera 的 Kotlin 扩展无法识别 multiDexEnabled true } // 必须启用 Java 11，否则编译报错 compileOptions { sourceCompatibility JavaVersion.VERSION_11 targetCompatibility JavaVersion.VERSION_11 } kotlinOptions { jvmTarget = '11' } }

第三层：AndroidManifest.xml 的权限与硬件声明

<uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!-- Android 13+ 需要这个 --> <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> <!-- 声明硬件需求，避免 Google Play 分发给不支持设备 --> <uses-feature android:name="android.hardware.camera" android:required="true" /> <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

第四层：动态权限请求的时机陷阱
不要在组件useEffect里直接request(PERMISSIONS.ANDROID.CAMERA)！VisionCamera 的useCameraDeviceHook 内部会检查权限，如果权限未授予，它会静默返回undefined，UI 不会报错，但预览黑屏。正确做法是：

const device = useCameraDevice('back'); const [hasPermission, setHasPermission] = useState(false); useEffect(() => { (async () => { const status = await requestCameraPermissions(); setHasPermission(status === 'granted'); })(); }, []); if (device == null || !hasPermission) { return <View style={styles.loading}><Text>请求权限中...</Text></View>; }

即：先请求权限，再检查设备是否存在。顺序颠倒，就是黑屏。

3.3 JS 层：帧处理与解码的性能临界点控制

即使原生配置全对，JS 层写法不当也会导致卡顿。VisionCamera 的frameProcessor是在原生线程运行的，但它的输出（如codes数组）仍需序列化到 JS 线程。如果每帧都触发console.log(codes)，序列化开销会让 FPS 掉到 10 以下。我的优化策略是：

• 解码频率控制：不每帧都扫，而是用useRef记录上一次成功解码时间，间隔 500ms 再扫下一次：

  const lastScanTime = useRef(0); const frameProcessor = useFrameProcessor((frame) => { 'worklet'; if (Date.now() - lastScanTime.current < 500) return; const codes = scanCodes(frame, ['qr', 'ean-13']); if (codes.length > 0) { lastScanTime.current = Date.now(); runOnJS(onCodeScanned)(codes[0].value); // 仅在 JS 线程触发回调 } }, []);

• 解码类型精简：scanCodes(frame, ['qr'])比scanCodes(frame, ['qr', 'ean-13', 'code-128'])快 40%，因为解码器只需加载 QR Code 的特征模型。业务只要扫二维码，就别加其他类型。

• 相册图片预处理：ImagePicker返回的图片可能是 HEIC（iOS）或 WebP（安卓），scanCodesFromImage不支持。必须先用react-native-image-resizer转成 JPEG：

  const resized = await resizeImage({ path: response.assets[0].uri, maxWidth: 1200, maxHeight: 1200, format: 'JPEG', quality: 80, }); const result = await scanCodesFromImage(resized.uri, ['qr']);

注意：resizeImage的quality参数不是越高越好。实测quality: 100时，1200px 图片体积达 3MB，解码耗时 1.2s；quality: 80时体积 800KB，耗时 320ms，且识别率无差异。这是典型的“过犹不及”。

4. 实操过程与核心环节实现：从创建页面到双通道识别的完整代码

4.1 页面结构与状态管理设计

我们不使用全局状态管理（如 Redux），因为扫码是原子操作，状态极简。核心状态只有 4 个：

• cameraPermissionGranted: 布尔值，相机权限是否已授
• cameraDevice: VisionCamera 的CameraDevice对象，或null
• scanning: 布尔值，是否处于扫描中（用于禁用按钮）
• lastResult: 字符串，最后识别到的二维码内容

页面结构采用“Tab 切换”模式，上半部分是摄像头预览区，下半部分是操作按钮区，底部 Tab 切换“实时扫描”和“相册识别”：

// ScannerScreen.tsx export default function ScannerScreen() { const [activeTab, setActiveTab] = useState<'camera' | 'gallery'>('camera'); const [cameraPermissionGranted, setCameraPermissionGranted] = useState(false); const [cameraDevice, setCameraDevice] = useState<CameraDevice | null>(null); const [scanning, setScanning] = useState(false); const [lastResult, setLastResult] = useState<string | null>(null); // 权限请求与设备获取 useEffect(() => { const initCamera = async () => { const status = await requestCameraPermissions(); setCameraPermissionGranted(status === 'granted'); if (status === 'granted') { const device = await Camera.getCameraDevice('back'); setCameraDevice(device); } }; initCamera(); }, []); return ( <SafeAreaView style={styles.container}> {/* 预览区 */} {activeTab === 'camera' ? ( <CameraPreview cameraDevice={cameraDevice} permissionGranted={cameraPermissionGranted} onCodeScanned={setLastResult} /> ) : ( <GalleryPreview onCodeScanned={setLastResult} /> )} {/* 操作区 */} <View style={styles.actionBar}> <TouchableOpacity style={[styles.tabButton, activeTab === 'camera' && styles.activeTab]} onPress={() => setActiveTab('camera')} > <Text style={styles.tabText}>实时扫描</Text> </TouchableOpacity> <TouchableOpacity style={[styles.tabButton, activeTab === 'gallery' && styles.activeTab]} onPress={() => setActiveTab('gallery')} > <Text style={styles.tabText}>相册识别</Text> </TouchableOpacity> </View> {/* 结果展示 */} {lastResult && ( <View style={styles.resultBox}> <Text style={styles.resultText}>识别成功：</Text> <Text style={styles.resultValue} numberOfLines={2}>{lastResult}</Text> </View> )} </SafeAreaView> ); }

4.2 实时扫描模块：CameraPreview 组件详解

CameraPreview是核心，它封装了 VisionCamera 的所有复杂性：

// components/CameraPreview.tsx import { Camera, useCameraDevice, useCameraFormat } from 'react-native-vision-camera'; import { useFrameProcessor, scanCodes } from 'react-native-vision-camera-code-scanner'; import { runOnJS } from 'react-native-reanimated'; type CameraPreviewProps = { cameraDevice: CameraDevice | null; permissionGranted: boolean; onCodeScanned: (value: string) => void; }; export function CameraPreview({ cameraDevice, permissionGranted, onCodeScanned }: CameraPreviewProps) { const [torch, setTorch] = useState<'off' | 'on'>('off'); const [isScanning, setIsScanning] = useState(true); const lastScanTime = useRef(0); // 自动选择最优格式（分辨率/帧率平衡） const format = useCameraFormat(cameraDevice, [ { videoResolution: '1080p', fps: 30 }, { videoResolution: '720p', fps: 60 }, ]); // 帧处理器：worklet 环境运行 const frameProcessor = useFrameProcessor((frame) => { 'worklet'; if (!isScanning || Date.now() - lastScanTime.current < 500) return; // 仅扫描 QR Code，提升速度 const codes = scanCodes(frame, ['qr']); if (codes.length > 0) { lastScanTime.current = Date.now(); runOnJS(onCodeScanned)(codes[0].value); // 扫到后暂停 1 秒，避免连续触发 setIsScanning(false); setTimeout(() => setIsScanning(true), 1000); } }, [isScanning]); if (!permissionGranted || cameraDevice == null) { return ( <View style={styles.permissionPlaceholder}> <Text>请授予相机权限以开始扫描</Text> </View> ); } return ( <View style={styles.cameraContainer}> <Camera style={styles.camera} device={cameraDevice} isActive={true} torch={torch} format={format} frameProcessor={frameProcessor} frameProcessorFps={5} // 限制帧处理频率，省电 /> {/* 闪光灯开关 */} <TouchableOpacity style={styles.torchButton} onPress={() => setTorch(prev => prev === 'off' ? 'on' : 'off')} > <Icon name={torch === 'on' ? 'flash' : 'flash-off'} size={24} color="#fff" /> </TouchableOpacity> {/* 扫描框蒙层 */} <View style={styles.scanOverlay}> <View style={styles.scanLine} /> </View> </View> ); } const styles = StyleSheet.create({ cameraContainer: { flex: 1, backgroundColor: 'black', }, camera: { ...StyleSheet.absoluteFillObject, }, torchButton: { position: 'absolute', top: 40, right: 20, width: 50, height: 50, borderRadius: 25, backgroundColor: 'rgba(0,0,0,0.5)', justifyContent: 'center', alignItems: 'center', }, scanOverlay: { ...StyleSheet.absoluteFillObject, justifyContent: 'center', alignItems: 'center', }, scanLine: { width: '80%', height: 2, backgroundColor: '#00FF00', borderRadius: 1, }, });

关键点解析：

• frameProcessorFps={5}：强制 VisionCamera 每秒最多向帧处理器推送 5 帧，而非默认的 30 帧。因为人眼识别二维码不需要高帧率，降低此值可显著减少 CPU 占用，实测 iPhone 13 上 CPU 从 45% 降至 18%。

• setTimeout(() => setIsScanning(true), 1000)：扫到码后暂停 1 秒，防止用户还没看清结果，界面就又触发下一次识别。这是用户体验的黄金细节。

• scanOverlay蒙层：纯 CSS 实现，不涉及原生，避免影响性能。绿色扫描线用height: 2而非borderTopWidth，因为后者在某些安卓机型上会有渲染抖动。

4.3 相册识别模块：GalleryPreview 组件实现

GalleryPreview专注于“选图→预处理→解码”三步：

// components/GalleryPreview.tsx import { launchImageLibrary } from 'react-native-image-picker'; import { resizeImage } from 'react-native-image-resizer'; import { scanCodesFromImage } from 'react-native-vision-camera-code-scanner'; type GalleryPreviewProps = { onCodeScanned: (value: string) => void; }; export function GalleryPreview({ onCodeScanned }: GalleryPreviewProps) { const pickImage = async () => { const options: ImagePickerOptions = { mediaType: 'photo', includeBase64: false, quality: 0.8, maxHeight: 1200, maxWidth: 1200, }; launchImageLibrary(options, async (response) => { if (response.didCancel || response.errorCode) { console.warn('ImagePicker cancelled or error:', response.errorCode); return; } if (response.assets && response.assets.length > 0) { try { // 第一步：转 JPEG（解决 HEIC/WebP 兼容问题） const resized = await resizeImage({ path: response.assets[0].uri, maxWidth: 1200, maxHeight: 1200, format: 'JPEG', quality: 80, }); // 第二步：解码 const result = await scanCodesFromImage(resized.uri, ['qr']); if (result.length > 0) { onCodeScanned(result[0].value); } else { Alert.alert('未识别到二维码', '请确保图片清晰，二维码完整可见'); } } catch (error) { console.error('Scan failed:', error); Alert.alert('识别失败', '图片格式不支持或二维码质量过低'); } } }); }; return ( <View style={styles.container}> <TouchableOpacity style={styles.pickButton} onPress={pickImage}> <Text style={styles.pickButtonText}>从相册选择图片</Text> </TouchableOpacity> <Text style={styles.hintText}>支持 JPG、PNG 格式，建议图片大小不超过 2MB</Text> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20, }, pickButton: { backgroundColor: '#007AFF', paddingHorizontal: 40, paddingVertical: 16, borderRadius: 8, }, pickButtonText: { color: 'white', fontSize: 16, fontWeight: '600', }, hintText: { marginTop: 20, color: '#666', fontSize: 14, textAlign: 'center', }, });

关键点解析：

• resizeImage的quality: 80是经过 12 次实测得出的最优值：低于 70，图片模糊导致识别率暴跌；高于 85，文件体积增大但识别率无提升，纯属浪费带宽。

• scanCodesFromImage返回的是Promise<Code[]>，不是Promise<string>。必须检查result.length > 0，否则result[0].value会报undefined错误。

• 错误处理分两级：launchImageLibrary的errorCode（如permission、camera_unavailable）和scanCodesFromImage的catch（如invalid_image_format、no_qr_code_found）。分别给出针对性提示，而不是笼统的“识别失败”。

5. 常见问题与排查技巧实录：11 个真实坑位及解决方案

5.1 iOS 真机黑屏：Xcode 中的 “No Video Data” 错误

现象：App 在 iPhone 上启动后，摄像头区域纯黑，Xcode 控制台报Error: No video data received from camera。

排查路径：

1. 检查Info.plist是否漏了NSCameraUsageDescription；
2. 检查Build Settings → Linking → Other Linker Flags是否包含-lc++；
3. 检查Build Phases → Link Binary With Libraries是否漏了libc++abi.tbd；
4. 终极检查：在 Xcode 中，Product → Scheme → Edit Scheme → Run → Arguments，查看Environment Variables是否为空。如果存在OS_ACTIVITY_MODE = disable，删除它——这是 RN CLI 自动生成的，会屏蔽 VisionCamera 的日志输出，导致你无法看到真正的错误。

解决方案：按顺序执行上述 4 步，90% 的黑屏问题可解决。若仍不行，在Camera组件上加onInitialized={() => console.log('Camera initialized')}，确认是否进入初始化回调。

5.2 安卓模拟器无预览：Camera2 API 不可用

现象：Android Studio 模拟器（如 Pixel 4 API 34）启动后，预览区灰色，无任何报错。

原因：大多数模拟器默认禁用 Camera2 API，而 VisionCamera 强制使用它。

验证方法：在模拟器设置中，Settings → System → Developer options → Camera app，查看是否为Camera2。若为Legacy，则不支持。

解决方案：

• 方案 A（推荐）：换用真机调试，成本最低；
• 方案 B：在模拟器AVD Manager中，编辑你的虚拟设备 →Show Advanced Settings→Camera→ 将Front/Back Camera都设为Webcam0（即调用电脑摄像头）；
• 方案 C：在app/src/main/java/com/yourapp/MainActivity.java中，于onCreate方法内添加：

  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) { getWindow().setFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON, WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON); }

  这能强制唤醒摄像头硬件。

5.3 扫描灵敏度低：总提示“请靠近二维码”

现象：明明二维码清晰，距离 30cm，却一直提示“请靠近”，或需手动对焦多次才识别。

根因分析：VisionCamera 默认关闭自动对焦（AF），尤其在低端安卓机上，镜头无法自动调节焦距。

解决方案：

• 在Camera组件中，显式启用 AF：

  <Camera ... enableFocusDetection={true} // 启用焦点检测 autoFocus={'on'} // 强制开启自动对焦 />

• 同时，在useFrameProcessor中，加入对焦辅助逻辑：

  const frameProcessor = useFrameProcessor((frame) => { 'worklet'; // 当检测到二维码区域时，触发一次对焦 const codes = scanCodes(frame, ['qr']); if (codes.length > 0 && codes[0].bounds.width > 100) { // bounds.width > 100 表示二维码在画面中已足够大，可尝试对焦 runOnJS(() => { if (cameraRef.current) { cameraRef.current.focus(); } }); } }, []);

5.4 相册识别失败：HEIC 格式图片报错

现象：iOS 用户从相册选图后，scanCodesFromImage报Error: Unsupported image format。

原因：iPhone 默认用 HEIC 格式存储照片，而react-native-vision-camera-code-scanner的静态解码器不支持 HEIC。

解决方案：必须在resizeImage前，先用react-native-image-picker的includeBase64: true选项获取 base64，再用react-native-image-resizer的base64: true选项转 JPEG：

// 替代方案：绕过 uri，用 base64 流式处理 const options: ImagePickerOptions = { mediaType: 'photo', includeBase64: true, // 关键！ quality: 0.8, }; launchImageLibrary(options, async (response) => { if (response.assets && response.assets[0].base64) { const resized = await resizeImage({ base64: response.assets[0].base64, maxWidth: 1200, maxHeight: 1200, format: 'JPEG', quality: 80, }); const result = await scanCodesFromImage(resized.path, ['qr']); // 注意这里是 resized.path } });

5.5 多次扫描后内存泄漏：JS 对象堆积

现象：连续扫描 20 次后，App 卡顿，内存占用飙升至 1.2GB，Xcode 的 Memory Graph 显示大量Frame对象未释放。

原因：useFrameProcessor创建的 worklet 函数持有对onCodeScanned回调的引用，而该回调若来自父组件（如setLastResult），会形成闭包，阻止 GC。

解决方案：使用useCallback包裹回调，并在frameProcessor中用runOnJS时传入稳定引用：

// 在父组件中 const handleCodeScanned = useCallback((value: string) => { setLastResult(value); }, []); // 在 CameraPreview 中 <Camera frameProcessor={frameProcessor} // frameProcessor 内部用 runOnJS(handleCodeScanned) 而非 runOnJS(onCodeScanned) />

5.6 闪光灯无效：iOS 上点击无反应

现象：torch={'on'}设置后，闪光灯不亮。

原因：VisionCamera 的torch属性只在device.supportsFlash === true时生效，而useCameraDevice('back')返回的设备对象，其supportsFlash属性需在device != null后才能读取。

解决方案：在Camera组件中，动态判断：

<Camera torch={device?.supportsFlash ? torch : 'off'} ... />

并在 UI 上禁用闪光灯按钮：

{device?.supportsFlash ? ( <TouchableOpacity onPress={() => setTorch(...)} /> ) : ( <View style={styles.torchDisabled} /> )}

5.7 Android 13+ 相册权限崩溃：READ_MEDIA_IMAGES 缺失

现象：Android 13 设备上，点击“相