企业官网建设流程全解析

前阵子帮一个做仓储管理的团队排查扫码慢的问题，现场看到的场景很有代表性：仓库顶上几盏高棚灯泛着黄光，货架上的标签贴了快两年，边角起翘，正面还有一道被周转箱擦出来的浅划痕；操作员拿手持终端对着标签，稍微歪一点就得来回扫三四次，平均一次入库要花两秒多。他们最初的判断是"扫码枪不行了"，换了两款硬件，问题照旧。真正的原因说出来有点朴素——二维码识别这条链路上，成像质量、预处理策略和解码器的回退逻辑三者没有配合好，硬件只是最末端的执行者。后来我们在软件层面加了局部对比度增强、按模块宽度做缩放重试、失败帧自动回退重采样，同一批标签的首次识别率从七成出头提到了九成七，操作员的手感一下子就顺了。

这篇文章就是把这类事情讲透。它不是什么新鲜技术，二维码从上世纪九十年代被发明出来，到今天几乎贴在每一个快递箱、每一张名片、每一张点菜单上，但真正把它做稳的人并不多。我打算从整条链路的拆解讲起，说清楚一张码从进入镜头到吐出字符串之间到底发生了什么，哪些环节决定了成败，参数该怎么算，库该怎么选，代码怎么写，出了问题按什么顺序排查。适合三类人看：正在做扫码类功能开发但识别率卡住的工程师、需要给业务方解释"为什么扫不出来"的技术负责人、以及刚接触图像处理想找一个完整练手项目的同学。不需要你有很深的计算机视觉背景，高中几何加上一点点 Python 就能跟上。

1. 二维码识别的整体链路拆解与选型思路

1.1 从摄像头到字符串，一张码经历了什么

很多人对二维码识别的想象是"拍照，然后解码"，好像中间只有一步。实际上中间隔着一整条流水线，而且每一段都可能成为瓶颈。我把这条链路拆成五段：图像采集、预处理、定位与几何校正、网格采样、纠错译码与数据还原。

图像采集这一段决定了后面所有环节的上限。同一张码，用一千万像素的工业相机拍和用低端摄像头的自动曝光拍，进入算法时的质量天差地别。我见过最典型的翻车场景是摄像头自动对焦在远景上，码本身只占了两百来个像素，看起来"明明拍到了"，但模块宽度算下来不到两个像素，解码器根本没有足够的信息判定黑白。

预处理是把"能看的图"变成"好算的图"，灰度化、去噪、对比度增强、二值化都在这里。这一步的性价比最高，也最容易被跳过——不少人拿到图直接丢给解码库，库内部确实有自己的二值化，但那是通用策略，不会针对你的场景调。

定位与几何校正是二维码识别真正区别于普通图像识别的地方。二维码有三个位置探测图形，就是大家熟悉的三个"回"字形方块，它们的黑白比例恒定为 1:1:3:1:1，扫描线只要横穿过去就能按比例找到候选点。找到三个点，就能反推出第四个角的坐标，进而做透视变换，把倾斜、旋转、甚至轻微曲面造成的梯形畸变拉回正方形。这一步做完，图像才变成"正对着拍"的样子，后面才能按网格取点。

网格采样就是按版本规定的行列数，在每个模块中心取一个像素或一小块区域的平均值，得到一串 0/1 比特流。最后纠错译码负责把这些比特还原成数据，同时纠正采样过程中出错的部分。

我实测过一个统计：在识别失败的样本里，定位失败（完全没找到三个探测图形）占了大约六成，采样后纠错超限占三成，剩下的才是采集阶段的彻底糊掉。这个分布很关键，它意味着大部分优化精力应该花在"让定位更稳"上，而不是一味提高纠错等级。

1.2 三条技术路线的取舍：开源库、商业接口、自研

真到落地时，第一个决策不是写代码，而是选路线。主流就三条，我把它们放在一张表里对比，都是我自己项目里踩过或对比过的。

我的默认建议很明确：除非有特殊约束，先用开源库把整条链路跑通，把预处理和回退逻辑做扎实，能解决八成场景。商业接口的价值主要在极端工况——严重畸变、强反光、超低分辨率、破损严重的码，云端模型确实更强，但它带来的是网络时延和调用成本，在需要高频连续扫的场景（比如流水线分拣，一秒要过三件）根本没法用。自研只在两种情况下考虑：一是开源库的某个行为你实在绕不过去又必须改，二是你在做产品化的识别 SDK。

有一个折中做法我挺推荐：本地开源库做第一道，快速出结果；置信度低或者解码失败时，把这一帧送商业接口兜底。这样正常帧的时延保持在几十毫秒，异常帧才付成本，整体调用量能压到百分之几。

1.3 选型时最容易被忽略的三个约束

技术对比表看完了，真正决定项目成败的往往是表格之外的约束。

第一个是输入源的实际成像条件。同一个算法，手机后置摄像头、USB 免驱摄像头、工业面阵相机、手持终端的扫描头，出来的图像特性完全不同。手机有很强的自动曝光和降噪，图像干净但可能过度锐化；工业相机动态范围大但色彩偏灰；手持扫描头为了省电常常用低分辨率加高帧率。选型前我建议先抓一批真实图像存成样本集，哪怕只有两百张，也比凭空评估靠谱。

第二个是时延预算。人眼对交互的容忍阈值大概在 200ms 以内，超过这个数操作员会明显感觉"卡"。如果你的链路里有网络请求，就要把最坏情况算进去，而不是看平均值。我在一个项目里见过平均 80ms、P99 到了 1.2 秒的情况，原因是极少数大图触发了服务端的重试，现场感受就是"偶尔卡一下"，但这一下足以让操作员重复扫码。

第三个是硬件算力。开源库在 x86 上跑得飞快，换到 ARM 开发板或者低端安卓终端，同样的图和参数可能慢五到十倍。ZXing 的 Java 实现在低端机上处理一张 1080p 图能到两百多毫秒，这时候就得靠降分辨率、限定 ROI、跳帧这些手段往回找。选型阶段一定要在目标硬件上实测，别在开发机上跑通了就拍板。

2. 图像预处理：识别率的八成在这

2.1 灰度化与二值化，别急着上全局阈值

二维码只关心黑白，颜色信息是冗余的，所以第一步几乎总是转灰度。常见公式是加权求和：灰度 = 0.299R + 0.587G + 0.114B，权重来自人眼对不同波长敏感度的差异，绿色权重最高。OpenCV 的cvtColor默认走的就是这套。有人图省事直接取三个通道的平均值，效果会差一点，尤其在暖色光下，红色墨水印的码平均法算出来的灰度偏高，黑白边界会糊。

真正麻烦的是二值化。全局阈值（比如固定 127）在均匀光照下够用，但现场光照几乎从不均匀——顶灯正下方一片过曝，货架深处一片暗。这时候一个阈值必然顾此失彼，亮区全白、暗区全黑，码的对比度被吃掉了。局部自适应阈值才对症，OpenCV 的adaptiveThreshold用的思路是：对每个像素，取它邻域内的均值（或高斯加权均值）减去一个常数 C，作为该点的阈值。

这里有两个参数必须会算。blockSize是邻域大小，必须是大于 1 的奇数。它太小，噪声会被当成信号，二值化结果一片麻点；它太大，就退化成全局阈值。经验取值是这个邻域要明显大于单个模块的宽度，又小于整张码的尺寸，我一般按图像短边的 1/20 到 1/40 去试。举个具体例子：一张 1280×720 的图，短边 720，取 1/30 就是 24，凑成奇数用 25，这是起点，然后上下浮动试 21、31、41。更好的做法是先用检测到的码区域估算模块宽度，再把 blockSize 设成模块宽度的 4 到 8 倍，这样对不同尺寸的码都自适应。

常数 C 的作用是把阈值往下压一点，避免把浅灰噪点判成黑。C 取 5 到 15 比较常见，对比度低的图（比如灰底黑码、褪色标签）要往小调甚至取 2 到 3，否则码里的黑模块会被削掉一圈，直接影响定位时的 1:1:3:1:1 比例判定。我吃过一次亏：一批户外贴的码用亚光材质，颜色偏灰，C 用了默认的 10，结果定位成功率只有六成，改成 3 之后立刻回到九成以上。

2.2 反光、阴影、模糊这三类脏数据的处理手法

现场图像的问题基本可以归到这三类，处理方式完全不同，得先分类再动手。

反光是高光区域把模块整个盖白了。判断方法很简单：把图转到 HSV 空间，看 V 通道（明度）里有多少像素接近 255，如果反光区域正好压住了定位图形，那这帧基本没救，任何算法都补不出被饱和吃掉的边缘信息。能做的有三件事：一是多帧融合，连续抓三到五帧，每帧反光位置略有差异，取每像素的中位数或者最小值，这个方法在固定工位上非常有效，代价是要多采几帧；二是用 CLAHE（限制对比度的自适应直方图均衡）把局部动态范围拉开，让过曝区域边缘的过渡重新变得可分辨；三是物理层面解决，换漫反射材质的标签、把光源改成侧向打光、加偏振片，这些改动一次到位，比在算法里死磕划算得多。

模糊要用清晰度指标来量化，最常用的是拉普拉斯方差：对灰度图做拉普拉斯算子卷积，然后算结果的方差。方差越小说明边缘越少、图越糊。阈值因场景而异，我一般先在自己的样本集上跑一遍，看清晰帧和模糊帧的分布，取中间值，比如 80 到 120 之间定一个。低于阈值的帧直接提示"请靠近或保持稳定"，比强行解码后返回一个错误更友好。轻度模糊可以用反锐化掩模（unsharp mask）找回一点边缘，但过度锐化会在模块边界产生振铃，反而干扰定位，我一般把强度控制在 0.5 以内。

阴影问题靠局部阈值就能解决大半，剩下的是阴影边界本身形成的假边缘，可能被误判成定位图形。加一步形态学开运算（先腐蚀后膨胀）去掉细小的孤立连通域，能让候选点数量明显下降。这里的核大小也是按模块宽度来定，一般取模块宽度的 1 到 2 倍。

2.3 缩放与 ROI 裁剪，为什么缩小反而更准

这条听起来反直觉，但确实成立：把大图缩小，识别率有时会上升，速度还更快。

原因在模块宽度。解码器需要每个模块在像素上有足够的采样点，一般要求 2 像素以上，理想是 4 到 8 像素。一张四千万像素的图，如果码只占中间一小块，模块宽度可能是十几像素，这时候信息是过剩的，而多余的分辨率带来的是更多的噪声细节和更长的处理时间。反过来，如果码在整张图里很大，缩到模块宽度 3 到 4 像素，既保留了判定信息，又让定位算法的扫描步长相对变小，反而更容易命中比例。

算一下：一个版本 3 的码是 29×29 模块（含静区会更大）。如果它在图像里占 200 像素宽，模块宽度约 6.9 像素，非常理想；如果占 2000 像素宽，模块宽度 69 像素，这时候缩到 1/8，模块宽度约 8.6 像素，处理的数据量变成六十四分之一，耗时大幅下降而精度基本无损。所以工程上的通用做法是：先估算码在图中占比，把整图缩放到"码宽约 300 到 500 像素"的水平再送解码。

ROI 裁剪是另一个加速利器。视频流场景里，码往往只在画面中某一块区域出现，尤其是固定工位的扫描台。可以先用轻量的运动检测或者上一帧的识别结果，把 ROI 框出来，只处理这一块，耗时能降一个数量级。要注意 ROI 要留出足够的边距，二维码解码需要静区，也就是码四周至少 4 个模块宽的空白，裁得太紧会把定位图形切掉。我一般把检测框向外扩 20% 再裁。

3. 定位与解码：把像素变成数据的核心逻辑

3.1 三个"回"字定江山：位置探测与透视校正

位置探测图形是二维码最精妙的设计。它是 7×7 模块的方块，从外到内是黑、白、黑，比例 1:1:3:1:1。这个比例在任何缩放尺度下都成立，所以检测算法只要沿着水平、垂直、对角线方向扫描，记录黑白游程长度，找符合这个比例的组合，就能得到候选中心点。三个点凑齐，就能确定码的位置、大小和旋转角度。

这里有个细节值得说：为什么是三个而不是四个？因为二维码的另外三个角没有探测图形，第四个角上是一个较小的校正图形（版本 2 以上才有）。三个探测图形构成的直角三角形，本身就包含了旋转信息——从顶点出发的两条边分别是码的两个方向。第四个角的坐标由平行四边形关系推出来：如果三个点是 A、B、C，其中 A 是直角顶点，那么 D = B + C - A。这就是为什么二维码歪着扫也能读，算法根本不在乎你转了多少度。

找到四个角之后做透视变换，把这四个点映射到一个正方形的四个顶点，OpenCV 里就是getPerspectiveTransform加warpPerspective。变换后，图像被拉正，接着按版本号算出网格数（版本 N 的码宽是 4N+17 个模块），在每个格子中心采样。这一步的精度直接决定后续的误码率，所以变换时取点要尽量准，实际实现里会用校正图形做二次微调，把误差从几个像素压到一个像素以内。

3.2 纠错机制：里德-所罗门码的容错边界在哪

二维码用的纠错是里德-所罗门码（Reed-Solomon），和光盘、硬盘、深空通信用的是同一套数学工具。它的核心思想是把数据分成码字（每 8 个模块一个码字），然后附加若干校验码字，使得任意若干个码字损坏都能被数学方法还原出来。

容错分四个等级，我列个表，这几个数字必须记住，选型时会反复用到。

很多人有一个误解，觉得"容错调到 H 就万无一失"。实际情况是，容错等级越高，能装的数据越少，模块密度越大，同样的物理尺寸下模块更小，反而更容易在成像时糊掉。这是一个明确的反向权衡。我一般的建议是：屏幕显示和普通打印用 M；工业标签、户外、可能被摩擦的场景用 Q；只有在码中间要放 logo 或者确实会破损的情况下才用 H，并且要相应增大物理尺寸。

还有一个更关键的边界要讲清楚：纠错是按码字工作的，一个码字是 8 个模块，可能分布在不同的位置。所以一块集中的污渍能不能被纠正，取决于它覆盖了多少个码字，而不是覆盖了多大面积。经验上，单片污渍面积小于码面积的 20% 到 25%，且在 L 级以上，通常都能读出来。但如果污渍正好盖住了一个位置探测图形，那就直接判死刑了——因为定位阶段就找不到这个点了，根本走不到纠错环节。这就是为什么标签设计时要把三个"回"字的位置留出来，别在那里打孔、贴标、或者让手一直捏着。

3.3 版本、掩码与编码模式：影响解码速度的暗线

二维码有 40 个版本，版本 1 是 21×21 模块，之后每升一版，边长加 4 个模块，版本 40 是 177×177。版本号本身藏在码里，由两个位置的一组小块表示，解码器先读版本，才知道该按多大的网格去采样。

掩码是另一个容易被忽略的机制。二维码在编码时会用 8 种掩码图案中的一种对数据区做异或，目的是避免出现大片同色区域（尤其是连续的黑色块），因为大片同色会让定位和采样变难。编码器会评估 8 种掩码的效果，选一个最"花"的。这个机制对识别端是透明的，但它解释了一个现象：为什么两张内容不同的码，扫起来难度可能不一样。

编码模式则直接影响容量和速度。同样一段内容，用数字模式编码（只支持 0 到 9）比用字节模式省三分之一左右的空间；字母数字模式（支持大写字母和少数符号）介于两者之间；中文走的是字节模式（UTF-8）或者专门的汉字模式。我看过一些系统为了"通用"，把所有内容都按字节模式编码，结果一个纯数字的流水号本该用版本 2 就够，硬生生撑到了版本 4，模块变小，识别难度上升。生成端的一点点用心，能省掉识别端大量的麻烦。

3.4 解码失败的排查顺序，按这个来不会乱

出了问题不要瞎试，按固定顺序走，效率最高。

第一步，确认有没有定位成功。大部分开源库都提供只做检测的接口，比如 OpenCV 的QRCodeDetector.detect只返回角点不返回内容。如果这一步就返回空，问题在成像质量、对比度、或者二值化参数上，往第二章的方向调。如果检测到了点但位置明显偏，那大概率是畸变严重或者静区被裁掉了。

第二步，检查采样区域。把透视变换后的图存下来看一眼，是不是正的、网格对不对齐。我遇到过一次，变换后图像整体偏移了半个模块，原因是输入的角点顺序搞反了，导致透视矩阵算错，症状就是"能检测到但永远解不出"。

第三步，看纠错反馈。ZXing 这类库在失败时会给出原因码，区分"找不到格式信息""纠错失败""校验和不匹配"。纠错失败说明采样误码太多，考虑提高容错等级或者改善成像；校验和不匹配往往是静区不足或者码本身生成有问题。

第四步才是怀疑内容。极少数情况是编码端用了非标准字符集，识别出来是乱码而不是失败，这时候要检查两边约定的字符编码是否一致。

4. 工程落地：一套可复现的识别流程

4.1 环境与依赖准备

我以 Python 为例，这套组合在开发验证阶段最省事，跑通之后再用 C++ 或者原生库重写性能敏感的部分。

# 建议 Python 3.9 以上 pip install opencv-python==4.9.0.80 pip install pyzbar==0.1.9 pip install zxing-cpp==2.2.0

Linux 环境下 pyzbar 依赖系统的 libzbar 动态库，缺了会报ImportError: Unable to find zbar shared library，装一下对应发行版的包就行。ARM 板子上要注意架构匹配，交叉编译过的版本和 pip 装的版本可能冲突，我一般直接在目标板上编译，慢是慢点，但少一堆玄学问题。

选型上我通常两个解码器都留着：pyzbar 速度快、接口简单，对普通码够用；zxing-cpp 对畸变和低对比度的鲁棒性更好，还支持返回多个结果。让它们互为补充，一个失败就换另一个试，成本很低。

4.2 一条带多级回退的最小流水线

下面这段是我自己在项目里用的骨架，核心思路是"多策略回退"：先用最省的方式试，失败才升级处理，避免所有图都走最重的路径。

import cv2 import numpy as np from pyzbar.pyzbar import decode as zbar_decode, ZBarSymbol import zxingcpp def sharpness(gray): # 拉普拉斯方差，数值越小越糊 return cv2.Laplacian(gray, cv2.CV_64F).var() def try_decode(img): results = [] # 策略一：pyzbar 直接解，最快 for r in zbar_decode(img, symbols=[ZBarSymbol.QRCODE]): results.append((r.data.decode('utf-8', 'ignore'), 'zbar')) if results: return results # 策略二：zxing-cpp，鲁棒性更好 for r in zxingcpp.read_barcodes(img): results.append((r.text, 'zxing')) if results: return results return [] def recognize(path, max_side=1600): img = cv2.imread(path, cv2.IMREAD_COLOR) if img is None: return None, 'read_fail' # 控制长边，避免超大图拖慢速度 h, w = img.shape[:2] if max(h, w) > max_side: scale = max_side / max(h, w) img = cv2.resize(img, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA) gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # 太糊就别硬解，直接返回，交给上层提示重拍 if sharpness(gray) < 60: return None, 'too_blurry' # 第一轮：原图 got = try_decode(img) if got: return got, 'raw' # 第二轮：CLAHE 拉局部对比度 clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8)) enhanced = clahe.apply(gray) got = try_decode(enhanced) if got: return got, 'clahe' # 第三轮：自适应二值化，blockSize 按短边推算 block = max(11, (min(gray.shape) // 30) | 1) # 保证奇数 binary = cv2.adaptiveThreshold( enhanced, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, block, 7) got = try_decode(binary) if got: return got, 'adaptive' # 第四轮：放大重试，针对小码 up = cv2.resize(enhanced, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_CUBIC) got = try_decode(up) if got: return got, 'upscale' return None, 'all_failed'

这段代码有几个刻意的设计。max_side控制在 1600 是经验值，绝大多数场景下码在这个分辨率内已经足够，再大只是浪费算力。清晰度阈值 60 是我在室内光照样本上调出来的，换场景要重新标定。block | 1这个位运算保证 blockSize 是奇数，省得自己写判断。多级回退的返回值里带了策略名，方便后续统计"哪个策略解决了多少问题"，这个数据对优化特别有用——我在一个项目里统计完发现，CLAHE 那一轮贡献了超过三成的识别量，直接说明了初始图像的质量问题，促使团队去改了照明。

4.3 视频流场景的帧调度与去抖

连续视频流和静态图完全是两个问题。最蠢的做法是每帧都跑完整链路，一秒三十帧，CPU 直接打满，而且同一张码会被反复识别出结果，业务层收到几十条重复记录。

正确的做法是分层：先用极轻量的方式判断画面上有没有码。可以降采样到四分之一甚至八分之一，跑一次检测；也可以直接利用上一帧的结果，把 ROI 框出来，下一帧只在这个框附近找。找到之后进入"跟踪"状态，锁定 ROI，只在这个小区域内做完整解码，速度能提升五到十倍。

去抖是另一个必须做的处理。我通常用"连续三帧结果一致才输出"的策略，即在滑动窗口里存最近 N 次的结果，全部相同才向上层提交。这样能过滤掉偶发的误码——注意，二维码本身有校验，误码概率极低，但确实存在解出部分内容再被截断的情况，尤其在图像边界不完整时。N 取 2 到 3 比较平衡，太大反而让人觉得"扫了没反应"。

还有一个细节：识别成功后要短暂抑制，比如锁定 500 毫秒内不再对同一区域重复解码，直到画面发生明显变化（用帧差判断）。这在收银、门禁这类"一次一码"的场景里几乎是标配。

4.4 耗时拆解与优化优先级

优化之前先量一遍，别凭感觉。下表是我在一个 1080p 输入、中等配置设备上的实测拆解，你可以拿自己的数据对照。

优化顺序我建议这样排：先降输入尺寸，再缩 ROI，然后才是调算法参数。前两项是数量级的收益，后面是百分比。我见过有人死磕二值化算法，写了三百行自适应逻辑，最后发现只是输入图是四千万像素没缩，缩完速度直接掉到原来的十分之一。

5. 常见问题排查速查表与现场心得

5.1 十类高频问题速查

这张表基本上覆盖了我这些年遇到的绝大多数故障，按现象查就行。

有一类问题特别隐蔽：码生成得没问题、打印得也没问题，但识别端就是时好时坏。后来查出来是标签贴在金属货架上，金属反光形成了背景高光，正好落在静区里，破坏了定位时的比例判定。解决办法是把标签贴在一块哑光底板上，成本几毛钱，比在算法里做任何补救都有效。这类"算法解决不了、物理解决很便宜"的情况，在实际项目里占比相当高，我现在的习惯是先看现场，再写代码。

5.2 生成端和识别端的配合，这部分能省一半事

很多识别问题其实是生成环节埋的雷。我列几个最值得注意的。

静区必须留够，标准要求码四周至少 4 个模块宽的空白。实际设计里经常为了美观把 Logo 或色块贴到码边上，看起来只是紧了点，识别率立刻掉一截。因为定位算法需要在码外找到一段纯色区域作为扫描的起点和终点，静区不够就找不到边界。

颜色组合要用深色码、浅色底。二维码的本质是反射率差异，深色吸光、浅色反光，对比度越高越好。有人做反色设计（白码黑底），部分解码器支持，但兼容性没保证，尤其是工业扫描头，很多只认正色。也别用大红配深蓝这种组合——在某些传感器的响应曲线下，两者的灰度值几乎一样，人眼看着清楚，机器看着是一片灰。

尺寸要按模块宽度倒推。公式很直接：码的物理宽度 = 模块数 × 单个模块的物理尺寸。版本 5 的码是 37×37 模块，如果希望模块物理尺寸不小于 0.3 毫米（这是个经验下限，低于这个值印刷容易糊、扫描头也难分辨），那么码宽至少要 37 × 0.3 ≈ 11.1 毫米，加上静区大约 13 毫米。打印时还要考虑 DPI，300 DPI 下 0.3 毫米差不多是 3.5 个点，勉强够；如果标签只有 8 毫米宽，就得降版本或者减少内容。

内容本身也能优化。一段二十位的纯数字流水号，用数字模式编码只要版本 1 到 2；如果加上前缀字母和连字符，变成字母数字模式，容量掉一截；再混入中文，只能走字节模式，可能直接跳到版本 4。所以生成端的规则应该是：能用数字就别加字母，能短就别长，序列号里的固定前缀如果能省就省，让系统自己拼。

5.3 几个我实实在在踩过的坑

第一个坑是 EXIF 旋转。用手机拍的图，cv2.imread读进来不会自动应用 EXIF 里的方向标记，结果一张竖着拍的图读进来是横的，码在里面转了 90 度。二维码本身支持旋转，理论上不影响，但如果是多码场景，或者后面要做基于位置的业务判断，就会出问题。解决办法是读图后检查 EXIF 的 Orientation 标签，手动旋转。批量处理历史图片时这个坑特别容易踩，因为大部分图是正的，只有少数几张歪的，测试时根本发现不了。

第二个坑是灰度图直接送给某些解码接口。有的库内部默认输入是三通道，传单通道进去会静默失败，返回空结果而不报错。这种"不报错的失败"最难查。我的习惯是封装一层，进去之前统一检查通道数，该转的转。

第三个坑是 ARM 上的浮点性能。同一个算法在 x86 上跑 20 毫秒，在低端 ARM 上跑 300 毫秒，主要差异在自适应二值化和透视变换这类涉及大量浮点运算的环节。后来我们把二值化的 blockSize 调小（邻域小了计算量线性下降），透视变换改成定点运算，整体压到了 60 毫秒以内。这类优化在开发机上完全看不出必要性，一定要在目标硬件上测。

第四个坑是多码同框。一张图上贴了六个标签，识别库默认只返回第一个找到的。业务上以为"只识别一个"，结果漏掉了其他五个，上游数据一直不全。换成支持多结果的接口，或者自己先做一次码区域分割，再逐个识别。分割的做法是先做形态学处理把码区域连成块，用轮廓检测找出候选框，逐个裁出来单独解码。

第五个坑是超时缺失。多级回退的逻辑如果没有超时控制，遇到一张特别糟糕的图，可能在每一级都跑满时间，累计好几百毫秒，在视频流里直接导致丢帧堆积。我现在会在整个识别函数外面套一层时间预算，比如 150 毫秒，超了就返回"未识别"，让上层决定是重拍还是提示。宁可快速失败，也不要慢慢失败。

最后一个，是我个人觉得最有价值的一条：一定要建样本集。每次现场出问题，把那张图存下来，打上标签，归类到"反光""模糊""畸变""破损"里。半年下来你会有一个几百张的真实样本库，任何参数调整都能在上面回归验证，而不是改了一版心里没底。我在一个项目里就是这么做的，从最初的两百张积累到后来的一千多张，识别率从七成提到九成八，每一步改动都有数据支撑，跟业务方沟通的时候也硬气。

这套东西说到底没什么黑科技，就是老老实实把链路的每一段拆开、量出来、针对性地补。真正花时间的不是写代码，是把现场的情况搞清楚——光从哪来、标签贴在哪、操作员的手怎么动、码会被什么蹭到。这些信息决定了参数怎么取、回退怎么设计、什么时候该劝业务方改标签而不是改算法。我现在接这类需求，第一件事永远是去现场站半小时，看别人怎么扫码，比看一天代码有用。