前阵子接手一个移动端的扫码需求项目用的 React Native Expo。需求本身不复杂就是要扫商品条码、扫二维码拿参数跳转页面。我心想Expo 生态这么成熟扫码应该是最简单的一环了吧结果真正做起来才发现光是“扫码”这两个字背后就能藏着一堆坑权限配置、条码类型、连续扫码防抖、版本兼容、还有真机和模拟器上的表现差异。从“能扫出来”到“扫得稳、扫得快、不闪退”中间的差距全靠踩坑填平。这篇就把整个“react native expo扫码解决”的过程完整复盘一遍从方案选型到环境配置从核心实现到问题排查把我实际验证过的做法全部写出来希望能帮你省掉半天折腾时间。先说明一下这篇文章基于我实际使用 Expo SDK 搭配 expo-camera 的开发经历涉及的环境是 React Native 0.7x 以上的 Expo 托管工作流。如果你用的是 bare workflow 或者纯 RN CLI部分细节会有些差异但核心思路仍然通用。1. 扫码方案选型为什么我选 expo-camera1.1 市面上常见的扫码实现方式React Native 生态里做扫码大致有这么几条路调用系统相机拿到图片后交给第三方识别服务这种思路适合后端识别、批量识别的场景但客户端扫码讲究实时性摄像头预览画面必须逐帧分析走服务端轮询既不现实也浪费流量。使用 expo-camera 的条码扫描能力Expo 官方维护的相机模块自带条码识别功能支持在摄像头预览流中直接返回识别结果托管工作流直接可用。接入 react-native-camera 这类第三方库功能最全支持定制扫码框、多格式识别、手电筒但因为涉及原生代码在 Expo 托管工作流里需要 prebuild 或者弹出原生工程维护成本明显高。使用专门的开源扫码组件底层通常也是封装原生相机区别在于 API 更友好自带 UI 模板适合快速做 Demo。我个人的选择是 expo-camera原因有四个。第一它由 Expo 官方维护API 变更和 SDK 升级同步不会出现“升级 RN 版本后库就没人管了”的情况。第二托管工作流里无需处理原生代码权限声明、相机调用都由 Expo 封装好了对只想快速上线业务的人来说省心。第三条码识别性能足够常见的 EAN-13、QR Code 识别准确率和速度都达标。第四它支持在 CameraView 上叠加自定义 UI扫码框、提示文字都能自由绘制不需要被第三方组件的固定样式绑住。有朋友可能会说 react-native-camera 识别更快、更稳定这点我不否认。但它要求你必须处理原生工程Expo 的很多便利优势就没了。对于大多数扫码场景expo-camera 的性能完全够用没必要为了理论上的“更快”背上额外的维护负担。1.2 扫码需求里的隐藏细节很多人在选型时只想到“能扫就行”但实际业务里扫码往往不是独立功能而是和其他系统耦合在一起的。就拿我这次来说需求分了三层用户打开扫码页能看到相机预览画面画面中间有扫码框引导扫到条码或二维码后自动识别并携带扫描结果跳转识别结果要做校验比如条码格式、二维码里的参数合法性不合法的情况要给出友好提示。这三层需求看着简单却直接决定了技术选型的几个关键点预览画面能不能自定义 UI识别结果返回的是原始字符串还是结构化对象以及识别回调的触发频率能不能控制。用 expo-camera这三件事都直接在 API 层面解决了不需要额外写原生桥接代码。2. 环境准备与依赖配置2.1 SDK 版本与安装我用的环境是 Expo SDK 52React Native 0.76 左右expo-camera 在该版本中对应的版本是 ~16.x。安装命令很简单npx expo install expo-camera这里务必使用npx expo install而不是直接npm install原因在于 Expo 的依赖版本必须和 SDK 版本严格对应。手动安装最新版很可能因为 API 不兼容导致运行时崩溃这是最容易踩的第一个坑。安装完成后还需要确认两件事一是项目里有expo-barcode-scanner的话要确认它已经退役迁移了二是确认app.json里的权限描述文案已经配置好否则 iOS 首次弹出权限框时可能直接异常。2.2 相机权限配置Expo 在托管工作流里会自动处理大部分原生权限但“自动处理”不等于“不用配置”。iOS 端必须在app.json里添加相机权限的用途说明否则应用启动时调用相机权限会直接崩溃。配置如下{ expo: { ios: { infoPlist: { NSCameraUsageDescription: 需要使用相机扫描商品条码和二维码 } }, android: { permissions: [CAMERA] } } }Android 端的权限声明比 iOS 宽松一些但 Android 6.0 以上也是运行时权限模型Expo 会在调用相机时自动触发权限弹窗。如果你在开发中发现权限弹窗没出现大概率是app.json里的 permissions 没加全或者是走了旧缓存。权限这块我再补充一个细节iOS 的用途说明文案不要随便写审核时对相机权限的说明要求是真实且具体的。我见过有项目写“用于拍照上传”结果审核被要求补充说明的场景虽然这种属于应用商店审核层面的事但提前写好能避免返工。2.3 权限配置速查表我把两种平台的权限配置要点整理成了表格方便对照平台配置位置关键配置项缺失后果iOSapp.json → ios.infoPlistNSCameraUsageDescription调用相机直接崩溃Androidapp.json → android.permissionsCAMERA无法弹出相机权限请求相机预览黑屏双端app.json → expo.pluginsexpo-camera 插件配置如需要部分高级配置不生效如果你用 Expo 的预构建功能expo prebuild生成原生工程插件会把这些权限配置自动写入原生工程这算是一个便利点。但如果是旧项目升级过来建议执行一次npx expo prebuild --clean重新生成原生工程避免权限配置残留。3. 核心功能实现与关键参数拆解3.1 基础扫码页实现先看一个最基本的实现用 CameraView 渲染相机预览开启条码识别import { CameraView, useCameraPermissions } from expo-camera; import { useState } from react; import { StyleSheet, View, Text, TouchableOpacity } from react-native; export default function ScanScreen() { const [permission, requestPermission] useCameraPermissions(); const [scanned, setScanned] useState(false); const [scanResult, setScanResult] useState(); if (!permission) { return View style{styles.container} /; } if (!permission.granted) { return ( View style{styles.container} Text style{styles.text}需要相机权限才能扫码/Text TouchableOpacity style{styles.button} onPress{requestPermission} Text授权相机/Text /TouchableOpacity /View ); } const handleBarCodeScanned ({ type, data }) { setScanned(true); setScanResult(data); // 业务逻辑校验数据、跳转页面 }; return ( View style{styles.container} CameraView style{StyleSheet.absoluteFillObject} facingback barcodeScannerSettings{{ barcodeTypes: [qr, ean13, ean8, code128], }} onBarcodeScanned{scanned ? undefined : handleBarCodeScanned} / View style{styles.overlay} View style{styles.scanFrame} / Text style{styles.tip}将条码放入框内即可自动扫描/Text /View /View ); }这段代码有几个关键点要展开讲。useCameraPermissions这个 Hook 负责读取和申请相机权限它返回三个东西权限状态、申请权限的方法、以及一个请求函数。官网示例里普遍用requestPermission这个解构变量名但它实际返回的是requestPermission还是permission.request不同版本有小差异建议直接按官方文档来。开发中容易踩的坑是权限状态为null时不能渲染 CameraView必须先处理这个分支。barcodeScannerSettings里的barcodeTypes定义了要识别的条码类型。这里要特别提醒barcodeTypes是个数组类型名是小写字符串比如ean13虽然实际标准名是EAN-13但 API 里必须写小写。如果写成大写识别直接不生效且不会有任何报错这是非常隐蔽的坑。onBarcodeScanned回调的触发频率很高只要相机预览里出现可识别的条码就会持续回调。所以代码里用scanned状态做了一次开关一旦识别成功立即把回调置空避免重复触发。这个机制后面会专门说。3.2 识别结果的数据结构与类型校验onBarcodeScanned回调会收到一个对象包含两个核心字段type表示条码类型data是扫描得到的原始字符串。当前版本的 expo-camera 返回的就是这个结构但早期版本的字段名曾经是data和type混合使用还有过rawData之类的历史字段。这块要注意兼容。拿到data之后实际业务通常需要做格式校验。比如扫码拿到的可能是一段 URL也可能是纯数字的商品条码还可能是自定义格式的支付参数。我的处理方式是写一个校验函数根据type字段分流const handleBarCodeScanned ({ type, data }) { if (type qr) { // 校验 URL 格式提取 query 参数 const matched data.match(/^https?:\/\/[^\s]$/); if (matched) { // 跳转业务页面 navigation.navigate(Detail, { url: data }); } else { Alert.alert(提示, 二维码格式不正确); } } else { // 商品条码场景校验纯数字和长度 const isValidEAN /^\d{8}$|^\d{13}$/.test(data); if (isValidEAN) { // 查询商品信息 } else { Alert.alert(提示, 无法识别的商品条码); } } };这里有个容易忽略的细节二维码的内容是纯文本完全由生成方决定所以你不能假设它一定是合法 URL。就算正则校验通过了业务请求也可能失败建议在 UI 层加 loading 反馈而不是静默失败。3.3 连续扫码与防抖处理扫码页不止是扫一次就结束。实际业务中用户可能连续扫描多个商品比如盘点场景或者扫一个之后想继续扫下一个。我的处理方案是识别成功后弹窗确认用户点击“继续扫描”按钮后才重新开启扫码。const [scanned, setScanned] useState(false); const handleBarCodeScanned ({ type, data }) { setScanned(true); setScanResult(data); }; const handleContinue () { setScanned(false); setScanResult(); };如果需求是“识别成功立即再次进入识别状态”可以做延迟重置const handleBarCodeScanned ({ type, data }) { setScanned(true); // 处理业务逻辑 setTimeout(() setScanned(false), 1500); };这个 1500 毫秒的延迟是经验值太短容易在同一张条码上反复触发太长会让用户觉得“卡住了”。更好的做法是加入一个防抖标志位记住最后一次识别的时间间隔小于设定值就忽略新结果。我在项目中实际用的是更保守的策略绝不自动重置必须用户确认后再扫。原因很简单扫码枪和摄像头扫同一个码的触发频率很高自动重置很可能导致同一个码连续跳两次页面用户体验更差。还有一点onBarcodeScanned回调里不能做太重的同步操作。这个回调走的是原生事件通道同步阻塞会影响相机的帧处理严重时会出现黑屏或卡顿。我一般只做状态更新真正的业务请求放到异步函数里。4. 实操过程中的真实踩坑记录4.1 从 barcodeScanner 迁移到 CameraView 的 API 变化我在另一个老项目里维护过一个扫码功能当初用的还是expo-barcode-scanner里的BarCodeScanner组件。Expo SDK 48 之后这个库被标记为废弃推荐迁移到 expo-camera 里的CameraView但迁移过程坑点不少。最大的变化是组件名和属性名的替换。BarCodeScanner对应的是CameraView属性onBarCodeScanned变成了onBarcodeScanned注意首字母大小写有区别。另外旧库的扫码类型通过barCodeTypes传入新库是barcodeScannerSettings.barcodeTypes。这些变化在官方迁移文档里有清单但实际项目里很容易遗漏某一两个属性导致扫码功能彻底失效。我当时遇到过的情况是属性名全改对了但忘记删掉旧库的依赖结果运行时有两个相机模块冲突行为变得随机。排查了很久才意识到是依赖残留。所以迁移务必两步走先换组件和代码再卸载旧依赖最后清缓存重新构建。4.2 扫码识别失败或识别慢的排查思路扫码识别失败是最让人头疼的问题因为它不像语法报错那样有明确提示。我总结了一套排查顺序先看条码类型有没有配全。很多条码表面看着一样实际类型千差万别。二维码有 QR Code、Data Matrix、Aztec 等等一维码也有 EAN-8、EAN-13、Code 128、UPC-A 之分。barcodeTypes没包含对应的类型识别就永远不会触发。建议开发阶段直接把常见类型都加上上线前再按需精简。再看光线条件。这个听起来像废话但真的是最大的影响因素。在光线昏暗的环境下就算条码类型正确识别率也会大幅下降。这不是代码 bug是相机成像质量的问题。实际项目中可以在 UI 上加一个“打开手电筒”按钮亲测对暗光环境识别率提升非常明显。然后看条码是否清晰完整。摄像头对被扫物体的对焦范围有限太近太远都扫不出来。我建议在 UI 上做一层“扫码框”提示引导用户把条码放在画面中央区域而不是全屏乱扫。最后看是不是版本兼容问题。Expo SDK 升级后旧的缓存可能导致原生模块和 JS 层不匹配。我遇到过一次非常诡异的 bug同一段代码在 SDK 50 上能扫码升级到 SDK 52 后扫码回调完全不触发最后执行了npx expo start --clear清掉 Metro 缓存就好了。这种问题不属于代码逻辑纯属环境残留最有效的排查方式就是把缓存清干净重新构建。4.3 相机权限被拒后的引导恢复用户第一次拒绝相机权限之后再次进入扫码页权限状态是denied。此时再调用requestPermission()系统不会再次弹窗而是直接返回拒绝。这种情况下需要引导用户去系统设置里手动打开权限。这里有一个 API 细节useCameraPermissions返回的状态里canAskAgain字段判断当前是否还能再次弹出系统权限框。如果这个字段为false就要展示“去设置”按钮用Linking.openSettings()跳转到系统设置页。if (!permission.granted !permission.canAskAgain) { return ( View style{styles.container} Text相机权限已被永久拒绝请前往系统设置开启/Text TouchableOpacity onPress{() Linking.openSettings()} Text去设置/Text /TouchableOpacity /View ); }这个分支如果漏了用户会卡在扫码页上点“授权”没反应体验非常差。我在几个项目里都见过这个问题所以单独强调。4.4 真机与模拟器上的差异Expo 的扫码功能在 iOS 模拟器上基本没法用因为模拟器调用的是 Mac 的摄像头但实际上模拟器默认没有摄像头硬件支持除非你用 Continuity Camera 之类的外部方案。Android 模拟器可以通过虚拟摄像头模拟画面但也很难模拟出真实条码识别的效果。所以扫码功能必须真机调试。Expo Go 应用扫码打开项目是最快的验证方式但要注意 Expo Go 里的 expo-camera 版本可能和你的项目依赖版本不完全一致识别行为会有细微差异。最稳的做法是开发阶段用 Expo Go 验证功能正式发布前跑一次完整构建在真机上回归所有扫码场景。我还建议准备一组标准的测试码一个二维码内容是 URL、一个 EAN-13 商品条码、一个 Code 128 条码分别覆盖主要识别类型。实测下来不同条码的识别难度差异很大只测一种类型远远不够。5. 扫码功能的体验优化与排坑速查5.1 扫码页面 UI 的绘制技巧CameraView 是全屏预览所有 UI 元素都要叠加在预览层之上。这里有个性能和视觉的平衡问题千万不要用绝对定位的 View 覆盖整个屏幕并设置复杂的半透明背景会导致预览区域看起来发灰也影响识别视觉反馈。推荐做法是只画出四个角的扫码框边线中间留透明区域。四角可以用四个小 View 拼起来也可以用borderWidth 透明背景的方案。我实际用的是四角 View 方案虽然代码量稍大但视觉效果最接近主流扫码 AppView style{styles.scanFrame} View style{[styles.corner, styles.topLeft]} / View style{[styles.corner, styles.topRight]} / View style{[styles.corner, styles.bottomLeft]} / View style{[styles.corner, styles.bottomRight]} / /View四角的样式可以分别定义比如左上角就是左上边框加粗加长其他边不渲染。这样组装出来的框视觉上比一整圈边框精致不少。5.2 识别结果的业务解耦扫码功能本身只是“获取数据”真正复杂的是数据拿到之后如何处理。我建议把扫码识别和业务处理拆成两层扫码层只负责输出{ type, data }业务层负责根据数据做校验、请求、跳转。这样扫码页面可以复用换业务场景时不用动相机逻辑。一个可复用的模式是用回调函数把结果抛出去页面内部只维护扫码状态。function Scanner({ onResult }) { const [scanned, setScanned] useState(false); const handleBarCodeScanned ({ type, data }) { setScanned(true); onResult({ type, data }); }; return ( CameraView onBarcodeScanned{scanned ? undefined : handleBarCodeScanned} / TouchableOpacity onPress{() setScanned(false)} Text继续扫码/Text /TouchableOpacity / ); }这样拆完之后扫码页面变成一个纯工具组件换业务页面时传不同的onResult就行不需要复制一大堆相机代码。5.3 常见问题速查表最后把我在实际开发中遇到的常见问题整理成一张速查表方便排查时直接对照问题现象可能原因解决方案相机预览黑屏权限未授予或未配置检查 app.json permissions授权后再渲染 CameraView扫码无任何反应barcodeTypes 未包含目标类型补全类型注意小写字符串同一张码反复触发跳转缺少防抖处理识别成功后关闭回调用户确认后再开启iOS 首次点开扫码直接退出缺少 NSCameraUsageDescriptionapp.json 添加用途说明重新构建扫码识别成功率低光线暗、条码太近太远补手电筒按钮优化扫码框引导升级 SDK 后扫码失效依赖缓存或原生模块未同步npx expo start --clear执行 prebuild --clean旧项目迁移后行为异常旧依赖残留卸载 expo-barcode-scanner检查属性名这张表覆盖了我踩过的大部分坑。有些问题不是每台机器都会出现但处理思路是通用的先查权限再查配置最后查缓存。6. 实战中沉淀下来的三条经验扫码功能做多了之后我对这类“看似简单的小功能”有了更深的体会。最后分享三条我个人的经验希望能帮你避免绕远路。第一权限处理一定要做全三分支。权限未决定、权限已拒绝但可再次询问、权限被永久拒绝这三种情况在 UI 上都要有对应处理。很多扫码页在“用户拒绝权限后点什么都没反应”就是因为只做了两分支。这个不是纯技术问题是使用体验的核心关卡。第二连续扫码的交互设计比识别本身更重要。技术上把回调防抖做好只是第一步真正影响体验的是“扫完之后用户接下来要做什么”。是自动跳转还是弹确认框还是留在当前页继续扫都要根据业务场景来定。没有绝对正确的方案但一定要有明确的逻辑不能让用户扫完一个码之后无所适从。第三一定要留一条手动输入入口。相机扫码识别率永远不可能是 100%只要有一次失败用户就需要一个后备方案。我在所有扫码页面底部都加了“手动输入”的链接点击后弹出输入框让用户手动填写条码内容或 URL。这个功能平时用不上但关键时刻能救回一个完整业务流程。这个习惯我保持了很长时间不止一次被业务方点名表扬过。扫码功能的本质是“把一个物理世界的标识转化为可处理的数字信息”它通常只是流程的起点。如果你想基于这个思路继续扩展后续可以往这几个方向延伸扫到码之后自动调接口查询商品信息并展示卡片、扫码历史记录本地存储、批量连续扫码并自动填充表单。这些功能框架都能复用核心就是把扫码组件做薄把业务逻辑抽离。希望这篇基于实际经历的记录能帮你把扫码这件事做得又快又稳。