1. 连续扫码到底难在哪：先把场景和需求掰开
做微信小程序连续扫码这件事，我前后踩过至少三轮坑。第一次是在一个门店收货的场景里，业务方的原话是"你就让仓管拿着手机一直扫，扫完一箱再扫下一箱，别每次都要点一下"。听起来简单，真做起来才发现，单次扫码和连续扫码之间隔着的不是一层循环，而是一整套状态管理、性能控制和硬件交互的设计。
先说清楚这篇文章要解决什么。微信小程序连续扫码，指的是用户在不退出当前页面的前提下，对多个条码或二维码进行快速、连续识别，并把结果实时收集到一个列表里，最后统一处理或分批提交。它和你平时调一次wx.scanCode扫一个码拿一个结果，完全是两码事。适合读这篇文章的人有三类：正在做仓储盘点、门店收货、图书录入、资产盘点这类需要批量扫码业务的小程序开发者；想给自家小程序加一个"连扫模式"的产品同学；还有被扫码枪和相机权限折腾过、想找一条靠谱路线的人。
为什么它值得单独拿出来讲？因为微信小程序在这个能力上有几个天然限制，绕不过去。第一，wx.scanCode是调起微信内置的全屏扫码页，每次扫完都会退回来，用户要重新点一下按钮才能再扫，连续扫的效率极低，而且界面完全不受你控制。第二，真正能实现"扫完不停、界面常驻"的方案，是camera组件的scanCode模式，但它对基础库版本、真机环境、页面层级都有要求，开发者工具上还测不出效果。第三，扫码的输入是高频事件，如果不去重、不加锁、不做节流，用户手一抖同一个码能进来七八次，列表直接就乱了。
我自己第一次上线连扫功能时，就吃过没做去重的亏。测试环境里手速慢，扫得慢，看起来一切正常；到了真实仓库，仓管拿着手机对着一箱货连续晃，同一个二维码在一秒内被触发了五次，后台收到五条重复记录，盘点数量直接对不上。这个教训让我意识到，连续扫码的核心不是"怎么把码扫出来"，而是"怎么让扫出来的码干净、有序、可控地进入业务流"。
所以这篇文章我会按这个顺序讲：先把三条可用的技术路线摆出来做对比，讲清楚每条路线的适用边界；然后重点拆camera组件scanCode模式的完整实现，包括授权前置检查、状态机设计、去重节流的三层过滤、批量提交；再补一个很多同学会遇到的扫码枪场景；最后用一张速查表加一份避坑清单收尾。整个过程我会给出可复制的代码和参数选择的理由，尽量让不同基础的人都能拿去改一改就用。
前提说明：文中所有代码基于微信小程序原生框架，
camera组件的scanCode模式要求基础库 2.11.0 及以上，真机调试，开发者工具不支持该模式。
2. 三条技术路线对比：选错了后面全是返工
2.1 路线一：wx.scanCode 递归调用
这是绝大多数人第一次实现连扫会想到的方案，因为最简单：写一个函数，调用wx.scanCode，在success回调里拿到结果，把结果 push 进数组，然后在回调末尾再调一次自己，形成递归。
这个方案的优点是代码量极小，兼容性极好，几乎所有基础库版本都能跑，而且扫出来的结果质量很稳定——微信内置的扫码引擎优化得比你自己搞的好得多，模糊、反光、倾斜的情况下识别率都挺高。
缺点也很致命。首先，wx.scanCode每次会调起一个全屏的扫码界面，扫完之后这个界面会关闭，回到你自己的页面，你要再扫就得再调一次，视觉上会有一个明显的页面切换闪烁。用户在扫下一个码之前，会看到自己的列表页面闪一下再进入扫码页。这个体验在扫码频率低（比如每分钟三五个）的时候还能忍，一旦要求连续快速扫，这个闪烁会让人非常烦躁。
其次，你无法在扫码界面上叠加任何自定义 UI，比如实时显示"已扫 12 件"、显示扫描框颜色变化、加个震动提示，这些统统做不到。因为那个界面是微信的，不是你自己的。
还有个隐藏问题：wx.scanCode是异步的，递归调用如果不加锁，用户在扫码页还没返回的时候连续操作，可能出现多个扫码流程并发的诡异状态。我见过有人在这里用递归加setTimeout硬凑，最后代码逻辑乱得自己都不敢改。
所以我的结论是：wx.scanCode递归调用适合"扫码频率低、对界面无要求、追求快速上线"的场景，比如偶尔扫一两次的辅助功能。真正要做连扫，别选它。
2.2 路线二：camera 组件 scanCode 模式
这是做连续扫码的正解。camera组件从基础库 2.11.0 开始，mode属性支持设置为scanCode，配合bindscancode事件，就能实现"相机常驻、扫到就回调、页面不跳转"的效果。
它的核心优势是：相机画面一直在你自己的页面里，你可以随便在上面叠 UI——扫到码的时候把扫描框变绿、播放一声"嘀"、把结果实时追加到下方列表、显示累计数量，这些统统可行。扫码事件是持续触发的，用户只要把手机对着码，识别成功就会回调一次，不需要任何点击操作，真正意义上的"连扫"。
代价是环境要求更严格。camera组件在开发者工具里是以占位图的形式存在，scanCode模式根本跑不起来，必须用真机调试。而且camera是原生组件，早期需要通过cover-view来覆盖内容，虽然现在同层渲染已经比较成熟，但一些老机型、老版本微信上还是会有层级问题。
另外，camera的scanCode模式和takePhoto不能同时用，如果你既要连扫又要拍照留证，得在mode之间切换，切换时相机会重新初始化，有一个短暂的黑屏，这个要在产品设计上提前考虑。
2.3 路线三：扫码枪 HID 输入 + input 监听
还有一种场景是很多人会忽略的：门店里已经有一套 USB 扫码枪或者蓝牙扫码枪，用户不想用手机摄像头，就想用扫码枪"哒哒哒"扫。这类扫码枪通常工作在 HID 键盘模式，扫一个码就等于在电脑上敲了一串字符，末尾通常带一个回车或换行。
在小程序里接收扫码枪输入，只能靠一个获得焦点的input组件。因为小程序没有全局键盘监听能力，你不聚焦输入框，扫码枪敲的字符就没有任何地方接收。所以这条路线的核心难点是：怎么让input始终保持焦点，怎么判断一条码输入结束了，以及怎么在每次扫完后清空输入框而不丢失焦点。
这条路线的优点是速度快、误码率低，专业扫码枪的识别能力远超手机相机，适合固定工位的场景。缺点是对移动场景不友好，用户得抱着手机还得拖着枪，而且焦点管理在小程序里挺容易出幺蛾子——用户手一滑点到别的地方，焦点就丢了，扫码枪扫什么都进不来。
2.4 一张表说清怎么选
| 对比项 | wx.scanCode 递归 | camera scanCode 模式 | 扫码枪 HID 输入 |
|---|---|---|---|
| 界面可控性 | 无 | 完全可控 | 完全可控 |
| 连续扫码体验 | 差，每次跳转 | 好，相机常驻 | 好，取决于硬件 |
| 基础库要求 | 极低 | 2.11.0 及以上 | 极低 |
| 能否真机外调试 | 可以 | 不行，必须真机 | 可以 |
| 识别能力 | 微信引擎，强 | 微信引擎，强 | 硬件决定，通常最强 |
| 适用场景 | 低频辅助扫码 | 移动端连扫主力方案 | 固定工位批量录入 |
| 主要难点 | 体验差、界面不可控 | 版本/真机/层级 | 焦点保持、结束符判断 |
我的建议很直接：移动场景一律走camera的scanCode模式；固定工位有扫码枪的，走 HID 输入；只有那种"顺手加个扫码功能、一天用不了几次"的需求，才用wx.scanCode图省事。
3. camera + scanCode 模式完整实现
3.1 前置检查：授权、版本、真机三件事
动手写代码之前，有三件事必须先确认，否则你会发现代码写着写着就卡住，还不知道卡在哪。
第一是相机授权。camera组件需要scope.camera权限。用户第一次进入页面时，微信会自动弹授权框；但如果用户之前拒绝过，就不会再弹了，camera组件也不会显示画面，只会是一片空白。所以页面加载时要做一次权限检查，被拒绝过的情况要引导用户去设置页手动打开。
onLoad() { this.recentMap = new Map() wx.getSetting({ success: (res) => { const auth = res.authSetting['scope.camera'] if (auth === false) { // 用户曾经拒绝，需要引导去设置 this.setData({ needSetting: true, cameraReady: false }) } else { this.setData({ cameraReady: true, needSetting: false }) } }, fail: () => { this.setData({ cameraReady: true }) } }) }, openSetting() { wx.openSetting({ success: (res) => { if (res.authSetting['scope.camera']) { this.setData({ cameraReady: true, needSetting: false }) } } }) }这里有个细节：authSetting['scope.camera']有三个值，undefined表示从未询问过，true表示已授权，false表示被拒绝。我在代码里把undefined和true都当成可以使用，因为undefined的情况下组件渲染时会自动触发授权弹窗。
第二是基础库版本。camera的scanCode模式需要 2.11.0 及以上。你可以在小程序后台设置最低基础库版本，也可以在代码里用wx.getSystemInfoSync().SDKVersion做一次判断，低于 2.11.0 就降级到wx.scanCode方案，给用户一个提示。这个降级逻辑虽然麻烦，但能避免一部分老用户进来就是白屏。
第三是务必真机调试。我在开发者工具里调了半天，一直以为是自己代码写错了，后来换真机才发现，工具里camera组件压根不出画面，bindscancode也不会触发。这个坑几乎每个人都踩过一次，提前说一声能省你两小时。
注意：
camera组件在同一时刻只能有一个页面实例生效。如果你有多个页面都放了camera，跳转时旧页面的相机没释放，新页面可能黑屏。跳转前主动把cameraReady置为false销毁组件，是个稳妥的做法。
3.2 页面结构：相机铺满，UI 叠上去
页面结构我用"相机铺满、UI 浮动"的思路。相机占满整个屏幕区域，扫描框、状态栏、结果列表用绝对定位叠在上面。
<view class="scan-page"> <camera wx:if="{{cameraReady}}" class="camera" mode="scanCode" device-position="back" flash="{{flash}}" bindscancode="onScanCode" binderror="onCameraError" > <!-- 同层渲染成熟的环境下，普通 view 也能覆盖 --> <view class="scan-mask"> <view class="scan-frame {{locked ? 'frame-locked' : ''}}"></view> </view> </camera> <view wx:elif="{{needSetting}}" class="auth-tip"> <text>需要开启相机权限才能连续扫码</text> <button size="mini" bindtap="openSetting">去开启</button> </view> <view class="top-bar"> <text>已扫 {{scanList.length}} 件</text> <text bindtap="toggleFlash">闪光灯：{{flash === 'off' ? '关' : '开'}}</text> </view> <scroll-view class="result-list" scroll-y> <view wx:for="{{scanList}}" wx:key="key" class="result-item"> <text class="idx">{{index + 1}}</text> <text class="code">{{item.code}}</text> <text class="time">{{item.time}}</text> </view> </scroll-view> <view class="bottom-bar"> <button bindtap="clearAll">清空</button> <button type="primary" bindtap="submitAll">提交 {{scanList.length}} 条</button> </view> </view>这里解释几个关键点。mode="scanCode"是核心，没有它相机只是个取景器。device-position="back"固定后置摄像头，扫码必须用后置。flash做成可切换的，仓库、地下室这类光线差的环境，闪光灯常亮（torch）或者自动（auto）能显著提升识别率。
扫描框我用了一个view直接放在camera内部。这在支持同层渲染的环境下是可行的，iOS 微信 6.7.2 起、Android 微信 7.0.6 起camera支持同层渲染，普通view能正常覆盖。如果你要兼容更老的版本，就把内部的view换成cover-view，语义上更保险，但cover-view支持的样式非常有限，圆角、渐变这些基本用不了，需要权衡。
3.3 状态机：为什么不能裸写循环
很多人写连扫的时候，脑子里想的是"扫到就加进去"，然后直接写：
onScanCode(e) { this.data.scanList.push(e.detail.result) // 错的 this.setData({ scanList: this.data.scanList }) }这段代码有两个问题。第一，直接改this.data不会触发视图更新，必须通过setData，而且上面这种写法虽然setData了，但因为引用没变，某些情况下更新会出问题。第二，也是最要命的，没有加锁和去重，相机在一次识别中可能连续触发多次bindscancode，同一个码会进来好几遍。
正确的做法是设计一个简单的状态机。我用一个locked标志表示"当前正在处理一条扫码结果，暂不接受新的"。它的流转是这样的：
idle（可接收） --识别到码--> locked（处理中，去重/校验/渲染） locked --延时 300~500ms 后--> idle（可接收）为什么是延时而不是立即解锁？因为相机的识别是有惯性的，用户把手机对着同一个码，即使你处理完了，相机可能还在这个码的视野里，下一次识别马上又触发。加一个 300 到 500 毫秒的锁定期，就是给用户一个"移开手机对准下一个码"的物理时间，这个时间窗也顺便把同一码的重复触发挡掉了。
onScanCode(e) { if (this.data.locked) return const code = (e.detail.result || '').trim() if (!code) return // 业务编码规则校验，不符合的丢弃 if (!/^[A-Za-z0-9\-_]{4,64}$/.test(code)) { wx.showToast({ title: '码格式不符', icon: 'none', duration: 800 }) this.lock(600) return } // 时间窗口去重 const now = Date.now() const last = this.recentMap.get(code) if (last && now - last < 2000) { return } this.recentMap.set(code, now) // 拿到一条有效记录，上锁并渲染 this.lock(400) this.appendRecord(code) }, lock(duration = 400) { this.setData({ locked: true }) clearTimeout(this._unlockTimer) this._unlockTimer = setTimeout(() => { this.setData({ locked: false }) }, duration) }locked除了控制逻辑，还可以驱动 UI：锁定期间把扫描框变成绿色、边框加粗，用户一眼就知道"这条收进去了，可以扫下一个"。这种即时反馈对连扫体验非常关键，比任何文案提示都有效。
3.4 结果追加与列表渲染
追加记录时，要注意setData的性能。连扫场景下，列表可能很快涨到几百条，如果每次都全量setData整个数组，页面会越来越卡。
appendRecord(code) { const now = new Date() const pad = (n) => (n < 10 ? '0' + n : '' + n) const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}` const record = { key: `${code}_${Date.now()}`, code, time } // 只追加，不重建整个数组引用 const list = this.data.scanList.concat(record) this.setData({ [`scanList[${list.length - 1}]`]: record, total: list.length }) // 保持本地完整数据，用于提交 this.allRecords = list wx.vibrateShort({ type: 'medium' }) }这里用了一个小技巧：setData用路径写法scanList[i]只更新新增的那个元素，而不是整个数组。对于列表增长很快的场景，这个优化能明显降低数据传输量。但要注意页面data里的scanList只用来渲染，完整的记录我另外存在this.allRecords上，提交的时候用后者，避免因为渲染层做过裁剪而丢数据。
还有一个我之前踩过的坑：wx.vibrateShort需要基础库 2.13.0 及以上才支持type参数，低版本会报错但不影响主流程，包一层try或者用fail兜底一下就行。震动反馈在连扫里其实很重要，用户扫的时候眼睛经常是盯着货的，不看屏幕，一声震动加一声提示音，比看屏幕确认快得多。
3.5 三层过滤：把脏数据挡在列表之外
连扫场景里的脏数据主要有三类：重复码、格式不符的码、环境误识别。我一般用三层过滤来挡。
第一层是格式校验。用正则把明显不符合业务编码规则的码直接丢掉。比如你的商品码都是 13 位数字，那就用/^\d{13}$/卡一道；是自定义的带前缀的，就按前缀卡。这一层能挡掉相当一部分误扫进来的杂码，比如货架上的其他二维码、快递单上的码。
第二层是时间窗口去重。用Map记录每个码最近一次出现的时间戳，设定一个窗口（比如 2 秒），窗口内同一个码只收一次。这里用Map而不是数组，是因为Map的查找是 O(1)，列表到几千条的时候性能差异很明显。
第三层是业务白名单或唯一性校验。如果是资产盘点这种场景，同一个资产本来就不该出现两次，那就用Set记录已扫过的码，重复的直接提示"该资产已扫描"，不再入列。
// 业务唯一性去重（可选，盘点类场景） if (this.scannedSet.has(code)) { wx.showToast({ title: '该码已扫描', icon: 'none', duration: 800 }) this.lock(500) return } this.scannedSet.add(code)三层过滤加起来的代码量不大，但它决定了你的连扫功能是"能用"还是"可靠"。我现在的习惯是，不管业务有没有明确要求去重，格式校验和时间窗口这两层一定加上，这是底线。
4. 扫码结果的业务落地：从列表到后端
4.1 本地列表的性能与裁剪策略
扫码结果在一个页面里不断累积，最直接的问题就是渲染压力。我实测过，一个普通的scroll-view列表，超过 300 条记录之后，在千元机上滚动就开始有轻微掉帧；超过 800 条，输入响应会明显变迟钝。
这里不用急着上虚拟列表，通常有更省事的做法。我一般做展示裁剪：渲染层只保留最近 50 到 100 条记录，更早的记录仍然存在this.allRecords里参与提交，但不在界面上展示。用户想看总数就看顶部的计数，想翻历史记录就单独开一个页面，用分页加载。
const MAX_RENDER = 100 appendRecord(code) { // ... 组装 record this.allRecords.push(record) let renderList = this.data.scanList.concat(record) if (renderList.length > MAX_RENDER) { renderList = renderList.slice(renderList.length - MAX_RENDER) } this.setData({ scanList: renderList, total: this.allRecords.length }) }这个策略的好处是简单、稳定，渲染量恒定在 100 条以内，不管扫多少都不会卡。列表项用wx:key绑定唯一 key（我上面用code + 时间戳），避免列表重排时的错乱。
4.2 批量提交与断网补偿
连扫的最终目的是把结果交给后端。这里有几个设计点必须提前想好。
第一，不要每扫一条就提交一次。连扫可能在一分钟内产生几十上百条记录，一条一次请求，不仅慢，还可能触发接口限流。我的做法是本地累积，达到一个阈值（比如 20 条）或者用户主动点提交时，一次性打包发出去。
第二，提交要做幂等。网络超时重试的时候，同一批数据可能被后端收到两次。要么让后端用批次号（batchId）做幂等，要么在前端给每条记录加一个本地生成的唯一 id，提交时带上，后端按 id 去重。批次号方案更省事，我一般在前端生成一个batchId，重试时复用同一个，后端只认第一批。
buildBatch() { const records = this.allRecords.slice() const batchId = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}` return { batchId, items: records.map(r => ({ code: r.code, scanTime: r.ts })) } }第三，断网补偿。仓库、地下室这种地方信号差是常态。我的做法是把未提交成功的批次写进wx.setStorageSync，页面加载时先检查有没有残留的待提交批次，有的话提示用户并尝试重新提交。这样即使中途断网、用户退出了小程序，重新进来也不会丢数据。
savePending(batch) { wx.setStorageSync('pending_scan_batch', batch) } clearPending() { wx.removeStorageSync('pending_scan_batch') }有一段记录是我印象最深的：有个客户的地下仓库几乎没信号，仓管扫了一天，晚上回到办公室点提交，才发现中途的几批数据因为网络超时全丢了。后来加上本地缓存这一层，才算彻底解决。所以如果你做的连扫场景涉及弱网环境，本地补偿这一块千万别省。
4.3 反馈设计：震动、声音与视觉
连扫体验里，反馈设计的重要性经常被低估。用户扫的时候不会一直盯着屏幕，尤其是货架高处的码，人得仰着头。这时候如果每条成功的记录都只是静静地进列表，用户心里没底，会反复扫同一个码确认，反而制造了重复。
我的反馈组合是这样的：识别成功立即触发wx.vibrateShort一次短震动，同时播放一段很短的提示音，扫描框从白色变成绿色并轻微放大一下。三段反馈在同一时刻发生，用户不看屏幕也知道"这条成了"。
提示音这块要注意，小程序没有内置的音效播放能力，需要准备一个几百毫秒的音频文件，用InnerAudioContext播放。这个音频要足够短，建议控制在 200 毫秒以内，否则连续扫的时候声音会叠在一起。另外要在页面上提供一个静音开关，办公场所里连扫提示音一直响会影响别人。
playBeep() { if (!this.beepCtx) { this.beepCtx = wx.createInnerAudioContext() this.beepCtx.src = '/assets/beep.mp3' } this.beepCtx.stop() this.beepCtx.play() }错误反馈要区分开。格式不符、重复扫描这些，用不同的震动时长（vibrateShort的type用heavy）加一声较低沉的提示音，扫描框变红。用户能通过声音和震动区分成功和失败，操作节奏就不会乱。
5. 扫码枪场景的补充方案
5.1 让 input 焦点不掉
用扫码枪的时候，最大的敌人是"焦点丢失"。用户在操作过程中手一滑碰到屏幕别的地方，input就失焦了，扫码枪扫什么都进不来，而且因为屏幕上看不出什么异常，用户会一脸懵地反复扫。
我用的策略是"焦点自愈"：给input绑定bindblur，一旦失焦就立即重新聚焦。
<input class="gun-input" focus="{{gunFocus}}" value="{{gunValue}}" bindinput="onGunInput" bindblur="onGunBlur" confirm-type="done" bindconfirm="onGunConfirm" />onGunBlur() { // 失焦后稍作延迟重新聚焦，避免和页面其他操作打架 setTimeout(() => { this.setData({ gunFocus: true }) }, 100) }这里要注意一个细节：focus属性是"设置一次生效一次"，如果你一直把gunFocus设为true，后面再设true不会触发重新聚焦。所以失焦时先把gunFocus置为false，再置回true，才能触发。
onGunBlur() { this.setData({ gunFocus: false }) setTimeout(() => { this.setData({ gunFocus: true }) }, 80) }另外，如果页面上有按钮需要点击，点击按钮必然导致input失焦，这是无法避免的。我的做法是把按钮操作做得轻量，点完之后立即恢复焦点，或者干脆用长按、滑动这类不抢焦点的交互。
5.2 结束符判断与正则过滤
扫码枪的本质是"快速输入一串字符然后回车"。在小程序里，这个回车能不能被捕获，取决于扫码枪的配置。有些枪配置成发送\r\n，小程序的bindconfirm能触发；有些枪只发字符不发回车，就得靠输入停顿来判断。
稳妥的做法是两种都兼容。先设一个短定时器，每次input变化就重置它，如果 80 到 120 毫秒内没有新的输入，就认为这条码输入完了。这个间隔要卡准：太短了，扫码枪输入速度快（有些枪两三个字符之间只隔几毫秒），可能把一条码拆成两条；太长了，用户扫完下一条要等。
onGunInput(e) { const val = e.detail.value this.setData({ gunValue: val }) clearTimeout(this._gunTimer) this._gunTimer = setTimeout(() => { this.handleGunCode(val) }, 100) }, onGunConfirm(e) { // 扫码枪发送回车时走这里 clearTimeout(this._gunTimer) this.handleGunCode(e.detail.value) }, handleGunCode(raw) { const code = (raw || '').trim() this.setData({ gunValue: '' }) // 清空，准备下一条 if (!code) return // 同一个码在 1.5 秒内重复出现，忽略 const now = Date.now() const last = this.recentMap.get(code) if (last && now - last < 1500) return this.recentMap.set(code, now) this.appendRecord(code) }关于扫码枪本身的配置，有一点值得提：不同品牌扫码枪的默认输出模式不一样，有的默认 HID 键盘模式，有的可能被配成了串口模式。如果你发现扫码枪扫了之后小程序一点反应都没有，先确认它是不是 HID 键盘模式，用一个记事本测试一下能不能正常打出字符，这一步能快速定位问题出在扫码枪还是小程序。
还有一个正则过滤的实战技巧。有些扫码枪扫空白或者反光的时候会输出一串乱七八糟的字符，我一般会用业务编码的正则先卡一道，不符的直接丢弃并且不做任何提示，避免这种误触干扰用户。真正的扫码和一串乱码，用长度加字符集的规则基本能区分开。
6. 常见问题与排查实录
6.1 高频问题速查表
这张表是我自己遇到并解决过的问题，也包含一些同行问过我的高频疑问，按现象、原因、解决方式整理。
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| 开发者工具里相机不显示 | 工具不支持 camera 组件渲染 | 必须真机调试，工具只能看布局 |
| 真机上相机黑屏 | 权限被拒、组件未渲染、多实例冲突 | 检查 scope.camera，确认单个 camera 实例 |
| bindscancode 不触发 | 基础库低于 2.11.0 或 mode 未设置 | 升级基础库，确认 mode="scanCode" |
| 同一个码连续入列多次 | 未做去重和加锁 | 加 locked 状态 + 时间窗口去重 |
| 扫描框被相机挡 Resident | 原生组件层级问题 | 用 cover-view 或确认同层渲染环境 |
| 列表到几百条后卡顿 | 全量 setData | 只渲染最近 N 条，路径更新 |
| 扫码枪输入不进 | input 失焦 | 做焦点自愈，失焦后重新 focus |
| 一条码被拆成两条 | 结束符判断间隔太短 | 把定时器延迟调到 100ms 左右 |
| 闪光灯切换无效 | flash 值传错 | 可选值只有 auto/on/off/torch |
| 提交后重复入账 | 无幂等设计 | 用 batchId 或唯一 id 做幂等 |
6.2 真机与开发者工具的行为差异
这一块值得单独讲，因为它是新手最容易困惑的地方。微信开发者工具是一个模拟环境，对于camera、wx.vibrateShort、InnerAudioContext这类和硬件、系统强相关的能力，模拟程度很低。
具体来说，camera组件在工具里渲染成一张静态占位图，scanCode模式完全不生效，bindscancode一次也不会触发。震动在工具里没有反馈。音频播放的行为也和真机有差异，比如在真机上切到后台音频会被暂停，工具里不一定。所以我的习惯是：布局和逻辑在工具里调，涉及相机、震动、音频、性能的问题一律真机验证。
真机验证的时候还要注意机型差异。我在 iOS 上跑得好好的连扫，到了某台低端 Android 机上，相机预览就很卡，识别响应也慢半拍。原因通常有两个：一是那台机器的摄像头本身性能有限，二是同层渲染在该版本微信上没生效，导致相机和覆盖层之间出现了额外的合成开销。遇到这种情况，把页面的动画、阴影这些视觉效果砍掉，往往能明显改善。
6.3 我踩过的坑，以及给后来人的建议
第一个坑是没考虑连续扫同一个码的合理性。有一批商品的外箱码和内盒码是关联的，用户在扫的时候经常扫到外箱码又扫到内盒码，看起来是重复，其实不是。我一开始用简单字符串去重，直接把内盒码给拦了。后来改成用业务主键去重，加上类目区分，才解决。所以去重逻辑一定要贴合业务语义，不能只做字符串层面的判断。
第二个坑是提交时机没设计好。早期版本是用户点了"完成"才提交，结果有个仓管扫了两百多条，最后手机没电了，数据全丢。后来改成"满 50 条自动提交一次 + 手动提交 + 本地缓存"，三重保障，再没丢过数据。
第三个坑是忽略了弱网下的重试风暴。有一次接口临时挂了，前端不停地自动重试，用户手机发烫，流量也跑了不少。后来加了指数退避，重试间隔从 2 秒开始逐步拉长，第二次 4 秒，第三次 8 秒，最多重试五次。这个小改动让弱网下的表现稳定了很多。
第四个坑是UI 反馈做得太"安静"。最早的版本扫成功只是在列表里默默加一行，用户总怀疑没扫上，反复扫同一个码，反而制造了重复。加上震动加提示音之后，重复扫码率肉眼可见地下降了。这让我意识到，连扫功能的成败，一半在识别，一半在反馈。
第五个坑是没有给用户一个"改错"的入口。扫码总会出错，可能是扫错了一件，也可能是扫重复了。如果列表里的记录不能删除，用户唯一的办法就是全部清空重扫，那前面的工作全白费。后来我在每条记录上加了一个删除按钮，长按或者点右侧的叉就能移除。这个功能上线之后，用户的抱怨少了一大半。
如果让我给正在做或者准备做连扫功能的同学一句建议，那就是：先把"异常路径"想清楚，再写正常流程。重复怎么处理、错了怎么删、断网怎么办、权限被拒怎么引导，这四个问题想明白了，代码其实很好写。反过来，只想着"怎么把码扫出来"，上线之后你会发现用户遇到的几乎全是异常情况，而不是你想象中的顺利连扫。
