ARTICLE · 1369126
uni-app 扫不出码?uni.scanCode 的 3 个“静默失败”
uni-app项目中,我在微信小程序里调uni.scanCode,点按钮,没反应。
加console.log,success没走,fail也没走。
然后开始怀疑是不是按钮没绑对,结果换到H5上一试,连相机都不弹。
uni.scanCode不是“跨端通用API”。它在三个端上,各有各的沉默方式。❄️
失败一:H5端“不存在”,但不是报错,是无声无息
H5端不支持。也不会给你一个明确的fail,而是静默失败。
你点按钮,success不走,fail也不走。控制台干干净净,就像什么都没发生过。
H5要做扫码,必须换vue-qrcode-reader这类基于摄像头的库。不能指望uni.scanCode自动降级,它连“我降级不了”这个信息都不告诉你。
这个坑最隐蔽的地方在于:你在小程序上测通了,以为代码没问题。换到H5,功能直接消失,没有任何报错。
失败二:小程序端权限“缺描述”,相机不弹
或者scanType过于宽松,触发了平台的安全限制。
必须在manifest.json或app.json里显式配置scope.userCamera的权限描述:
{"mp-weixin": {"permission": {"scope.userCamera": {"desc": "用于扫描二维码"}}}}
scanType也要限定在真正需要的类型上,比如['qrCode']或['barCode']。不要留空,也不要写['qrCode', 'barCode']了事,越宽的类型,越容易触发平台的静默拦截。
失败三:结果拿到了,但解析错了方向
不能拿到之后直接当对象用:
const result = JSON.parse(res.resultString) // 扫到普通文字直接崩扫到普通文字就JSON.parse报错。或者不try-catch,扫到非预期内容直接崩。
更隐蔽的是,不同端返回的字段名和格式有差异。H5降级方案和原生扫码拿到的结构可能对不上。如果不做归一化,代码在A端能跑、B端就挂。
一个“三端都能跑”的最小封装
async function safeScan() {// 1. 端判断:H5走摄像头库,小程序/App走uni.scanCode// #ifdef H5return await scanWithCameraLibrary()// #endif// 2. 权限预检:小程序端先确认scope.userCamera// #ifdef MP-WEIXINconst setting = await uni.getSetting()if (!setting.authSetting['scope.userCamera']) {await uni.authorize({ scope: 'scope.userCamera' })}// #endif// 3. 调扫码 + 结果归一化解析const res = await uni.scanCode({ scanType: ['qrCode'] })try {return { ok: true, data: JSON.parse(res.resultString) }} catch {return { ok: true, data: res.resultString } // 非JSON内容,原样返回}}
三件事:端判断、权限预检、结果归一化。
轻量位要的是“知道该检查哪三件事”,不是“拿走一个组件”。
什么时候该用uni.scanCode,什么时候该换方案
但只要项目里有H5,或者未来可能上H5,不要把它当成“跨端能力”来设计。
在调用层就做好降级分支。H5用vue-qrcode-reader,小程序/App走uni.scanCode,两边用同一套结果归一化逻辑。
另外,如果需求是“长按图片识别二维码”而不是“调相机扫码”,uni.scanCode的onlyFromCamera和行为会不同,需要单独处理。
💡 总结:
uni.scanCode的坑不在于“会不会用”。
在于它的失败方式太安静。
安静到你以为是自己的代码写错了,安静到你换了三个按钮绑定方式才发现问题不在这。
加一个端判断、加一个权限预检、加一个try-catch,三行代码就能让“扫不了”变成“知道为什么扫不了”。
报错不可怕。可怕的是连报错都没有。
你在小程序里调扫码,有没有遇到过“点了没反应、控制台也不报错”的情况?后来发现是权限描述没配、还是H5上硬调了uni.scanCode?评论区说说。
小鹿
2026.11.17















































































