前端3年踩坑实录：1个扫码库把React搞崩2次

浏览器扫码听起来像是个「有手就行」的需求——直到你在生产环境看到 React 报错Node.removeChild: The node to be removed is not a child of this node。这不是你的代码问题，是两个运行时争夺 DOM 控制权的经典翻车现场。

最近用html5-qrcode给 Next.js 项目做扫码功能，踩了三个深坑。这篇把完整的事件线还原一遍，包括那个让我调试到凌晨两点的竞态条件。

选型：为什么不是 zxing-js 或 jsQR

浏览器扫码有三条技术路线：zxing-js功能全但 API 繁琐，jsQR轻量却得自己处理摄像头权限和帧循环，html5-qrcode把这两层都包了。对于不想维护getUserMedia兼容层的产品团队，这是唯一理性的选择。

安装命令一行：

npm install html5-qrcode

架构设计很简单：同一个Html5Qrcode实例，图片上传走scanFile()，实时摄像头走start()。代码层面区分调用方式即可，核心逻辑复用。

但纸面架构和真实 DOM 是两回事。

第一崩：React 与第三方库的 DOM 战争

最初的实现很直觉：用 React 状态控制摄像头容器的显隐。

{cameraActive && (

问题在html5-qrcode的工作机制。调用start()后，库会往#qr-camera-feed里注入、和若干内部

。这些节点不在 React 的虚拟 DOM 里。

当用户关闭摄像头，cameraActive置为false，React 尝试卸载它记忆中的那个#qr-camera-feed。但真实 DOM 已经被库改得面目全非——React 找不到它以为存在的子节点，直接抛异常。

修复方案是彻底放弃 React 对容器内部的控制：

{/* 提示层和摄像头层完全分离 */}

{!cameraActive && (

点击启动摄像头

关键点：容器永远挂载，只用 CSS 控制可见性。库对 DOM 的修改被限制在一个 React 不会触碰的隔离区内。

第二崩：扫码成功时的竞态条件

第一个坑修好后，功能跑通了——直到测试发现偶发的崩溃。

复现路径：二维码进入画面 → 成功回调触发 → 回调里调用stopCamera()→scanner.stop()执行 → 库内部还在处理刚才那一帧 → 状态不一致。

根本原因是html5-qrcode的start()是异步的，但很多人以为它返回时扫描就已经就绪。实际上，内部引擎还在预热，帧处理循环和回调注册存在时间窗口。

解决方案是用 ref 做运行状态守卫：

const scannerRef = useRef(null);

const scannerRunningRef = useRef(false);

启动流程：

await scanner.start(...);

scannerRunningRef.current = true; // 必须在 start() resolve 之后

停止流程：

if (scannerRunningRef.current) {

scannerRunningRef.current = false;

await scanner.stop();

}

这个 flag 的作用不是性能优化，是防止重复停止和状态错乱。扫码成功回调里第一件事就是检查并置 false，再执行业务逻辑。

第三坑：图片扫描的内存泄漏

图片上传模式看起来更安全——没有摄像头流，没有实时回调。但scanFile()内部会创建临时的Image对象和 canvas 上下文，大文件或批量扫描时内存曲线会缓慢爬升。

库文档没提的是，scanFile()的第二个参数showImage如果设为true，会在 DOM 里留一个预览图节点。如果你用 React 管理预览 UI，这个内部节点就成了孤儿。

统一的做法：第二个参数永远传false，预览层自己用URL.createObjectURL()实现，扫描完手动revokeObjectURL()。

三个坑的共同主题：第三方库和 React 的边界管理。

浏览器扫码这个需求，表面是 CV 代码，实际是运行时协调。html5-qrcode 把底层复杂度包得很好，但包不住它和 React 在 DOM 所有权上的根本冲突。