uni.scanCode在H5端完全不可用,调用后静默失败并进入fail回调;仅App、微信/支付宝/百度等小程序及鸿蒙平台支持,但各端权限配置与参数行为差异极大。

直接调用 uni.scanCode 在真机上能跑,但在 H5 环境下一定会失败——这不是你代码写错了,是浏览器根本不支持。
uni.scanCode 在哪些平台能用、哪些不能用
它不是“跨平台通用 API”,而是“跨平台封装调用”:各端底层调用不同原生能力,行为差异极大。
- H5 端:
uni.scanCode完全不可用,调用后立刻进fail回调,错误信息是not supported;连控制台警告都没有,静默失败最坑 - 微信小程序:可用,但必须在
manifest.json的mp-weixin节点下配置permission,否则 iOS 会直接拒权 - App(iOS/Android):可用,但依赖 DCloud 原生模块是否集成;部分低端安卓机型开启闪光灯检测反而卡顿
- 鸿蒙:基本可用,但 Android 14 和鸿蒙 NEXT 需额外声明
android.permission.POST_NOTIFICATIONS才能弹出权限提示
真机扫码失败的三大高频原因
90% 的“点不动、黑屏、没反应”都卡在这三步里,顺序不能错:
-
manifest.json里没开相机权限:App 端要勾选「Camera」模块;Android 的permissions数组必须含android.permission.CAMERA;iOS 必须补NSCameraUsageDescription字段 - 没提前调
uni.authorize({ scope: 'scope.camera' })就直奔uni.scanCode:iOS 和部分安卓系统会直接跳过弹窗,返回fail sys permission denied - 用户之前点过“拒绝”:
uni.authorize不会再次弹窗,必须引导用户去系统设置手动开启;可先用uni.getSystemInfoSync().platform === 'ios'做平台判断再提示
关键参数怎么设才不翻车
别信默认值,这几个参数直接影响识别率和体验:
-
scanType:设成['qrCode']比默认全开更稳;加'barCode'才能扫条形码;微信小程序扫小程序码会返回weapp类型,需单独处理res.result.path和res.result.extraData -
onlyFromCamera:设为true可禁用相册选图,避免核销场景被用户绕过 -
autoDecodeCharSet:设为true才能正确解中文、emoji、特殊符号;扫带中文参数的链接时漏掉这个,result会是乱码 - H5 环境下传任何参数都无效——它压根不执行,别白费力气配
H5 环境下怎么“凑合能用”
没有实时摄像头访问权,就只能退一步:让用户拍照或选图,再 JS 解码。
- 用
实现“强制后置摄像头拍照 + 相册备选”,capture="environment"在多数安卓有效,iOS Safari 仅支持相册 - 图片限制大小(建议 ≤2MB),格式限定为 JPEG/PNG;超大会导致
qrcode.js解码超时或内存溢出 - 别用 npm 上叫
qrcode-decoder的包——它对反光、倾斜、低对比度二维码识别率极低;要用纯前端、无依赖的qrcode.js(不是同名 npm 包) - 注意:H5 下
jsqr也可行,但它只支持 QR Code,不支持条形码;若需多码制,要么换quaggaJS(体积大、H5 可用),要么放弃 H5 自定义扫码
最常被忽略的一点:uni.scanCode 的 success 不是唯一出口。App 端部分安卓机型扫码后可能直接走 complete 而不进 success,所有 loading 关闭、按钮重置逻辑必须放在 complete 里,否则 UI 会卡死。











