为什么又写了一个扫码模块
Android 上做二维码扫描,ZXing 几乎是默认答案。它纯 Java 实现、完全离线、格式覆盖广,放几年前确实够用。但真把扫码放进一个有实际用户的产品里,问题会变得具体:用户举着手机在超市冷柜前晃了两秒没扫出来,或者二维码有轻微污损就识别失败,体验就直接掉档。
ZXing 的瓶颈不在“能不能解”,而在“解得多快、多稳”。它是纯 CPU 路径的图像处理,没有针对手机 SoC 做推理加速,低光照和低对比度下需要反复尝试二值化策略,帧率一高就容易积压。Google 的 ML Kit barcode-scanning 走的是另一条路:端侧机器学习模型 + 硬件加速,扫描速度在弱光或模糊场景下比传统 ZXing 快 30% 以上,而且对二维码的容错率更高。实测解码耗时可以压到 35ms 左右,连续扫码的温控表现也更好。
这篇文章不讲“ML Kit 吊打一切”的爽文叙事,只记录一个具体工程选择:用 Trae 辅助生成代码和配置,把 com.google.mlkit:barcode-scanning 接进 CameraX 的实时预览管线,让扫码从“点一下等半秒”变成“框住就出结果”。
先把 Trae 的边界说清楚
Trae 写 Android 代码很快,但它目前跑不了 Android 项目。 它没有 Android Studio 那套 SDK 管理、Gradle 图形化同步和调试器集成,编译、安装、真机验证的“最后一公里”仍然要交给 Android Studio 或命令行 Gradle + adb。
所以这篇文章里 Trae 的正确用法是:用它读需求、生成依赖配置、写代码骨架、批量改文件;用 Android Studio 完成编译和真机调试。两者不是替代关系,是前后道工序。
在开始写扫码模块之前,建议在项目根目录的 .trae/rules/ 下放一个 project_rules.md,把项目约束写死,避免 AI“自由发挥”改坏构建配置。一个最低限度的规则可以长这样:
markdown
---
alwaysApply: true
---
## 项目约束
- 这是 CameraX + ML Kit 的扫码模块,不要引入 ZXing 依赖。
- ML Kit 使用 bundled 模型 `com.google.mlkit:barcode-scanning:17.3.0`,不要改成 play-services 动态下载版本。
- 所有 CameraX 用例必须通过 `bindToLifecycle` 绑定,禁止手动管理 Camera 生命周期。
- 解码回调必须在主线程更新 UI,但 BarcodeScanner.process() 的调用不要放在主线程。
这一步不做,Trae 很容易在后续对话里“顺手”把依赖改成 unbundled 版本,或者塞一段 ZXing 的兜底逻辑进来。
依赖选择:bundled 还是 play-services
ML Kit 的 barcode-scanning 提供两种依赖形态,选错了会直接影响“快捷”这个核心卖点。
| 形态 | 依赖坐标 | App 体积增量 | 首次可用性 |
|---|---|---|---|
| Bundled(推荐) | com.google.mlkit:barcode-scanning:17.3.0 | 约 2.4 MB | 模型随 APK 打包,安装即可用 |
| Unbundled | com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.1 | 约 200 KB | 依赖 Google Play 服务下载模型,首次使用可能无结果 |
数据来源:Google 官方文档。
如果你的 App 本身已经不小,2.4 MB 的增量完全可以接受;换来的是“装完就能扫”,没有首次下载等待,也没有部分国产机型上 Google Play 服务不可用带来的兼容风险。扫码功能对“快捷”的要求,首先就体现在确定性上——用户点开相机,不应该等模型下载。
在 app/build.gradle 里加这一行就够了:
kotlin
dependencies {
// ML Kit barcode scanning — bundled model
implementation("com.google.mlkit:barcode-scanning:17.3.0")
// CameraX
implementation("androidx.camera:camera-core:1.5.1")
implementation("androidx.camera:camera-camera2:1.5.1")
implementation("androidx.camera:camera-lifecycle:1.5.1")
implementation("androidx.camera:camera-view:1.5.1")
}
CameraX 版本保持统一,camera-view 提供 PreviewView 和 CameraController,后面接 ML Kit Analyzer 时不需要手动处理坐标变换。
权限和 CameraX 预览:先让画面出来
在 AndroidManifest.xml 中声明相机权限:
xml
<uses-permission android:name="android.permission.CAMERA" />
运行时权限用 ActivityResultContracts.RequestPermission 处理,没必要再碰 onActivityResult。
CameraX 的启动代码放在 onCreate 或 onViewCreated 中:
kotlin
private fun startCamera() {
val cameraProviderFuture = ProcessCameraProvider.getInstance(this)
cameraProviderFuture.addListener({
val cameraProvider = cameraProviderFuture.get()
val preview = Preview.Builder().build().also {
it.setSurfaceProvider(previewView.surfaceProvider)
}
val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
try {
cameraProvider.unbindAll()
cameraProvider.bindToLifecycle(this, cameraSelector, preview)
} catch (e: Exception) {
Log.e("CameraX", "bind failed", e)
}
}, ContextCompat.getMainExecutor(this))
}
bindToLifecycle(this, cameraSelector, preview) 把预览用例和 Activity/Fragment 的生命周期绑死,切后台自动释放相机,不需要手动写 onPause / onResume 释放逻辑。这是 CameraX 相比 Camera2 在工程上最省心的地方:二维码扫描模块最怕的就是相机资源泄漏,CameraX 把这块直接兜住了。
接入 ML Kit:MlKitAnalyzer 是“快捷”的关键
ML Kit 和 CameraX 的集成有两种写法:手动在 ImageAnalysis.Analyzer 里把 ImageProxy 转成 InputImage 再喂给 BarcodeScanner,或者直接用 CameraX 官方提供的 MlKitAnalyzer。
如果你用 CameraController + PreviewView,MlKitAnalyzer 会自动帮你处理 ImageAnalysis 原始流和 PreviewView 之间的坐标变换,你拿到的 Barcode 对象坐标可以直接画 overlay。省掉坐标换算这一步,意味着少一个出错点,也少一段需要维护的矩阵代码。
创建 BarcodeScanner 时,把格式收窄到 FORMAT_QR_CODE:
kotlin
val options = BarcodeScannerOptions.Builder()
.setBarcodeFormats(Barcode.FORMAT_QR_CODE)
.build()
val barcodeScanner = BarcodeScanning.getClient(options)
限制格式不是可有可无的“微优化”。ML Kit 在扫描时会根据启用的格式分配推理资源,格式列表越短,单帧处理路径越轻。如果你的业务只扫二维码,不要开 FORMAT_ALL_FORMATS。
然后通过 CameraController 把 analyzer 挂上去:
kotlin
cameraController.setImageAnalysisAnalyzer(
ContextCompat.getMainExecutor(this),
MlKitAnalyzer(
listOf(barcodeScanner),
CameraController.COORDINATE_SYSTEM_VIEW_REFERENCED,
ContextCompat.getMainExecutor(this)
) { result: MlKitAnalyzer.Result? ->
val barcode = result?.getValue(barcodeScanner)
barcode?.rawValue?.takeIf { it.isNotBlank() }?.let { value ->
onQrCodeScanned(value)
}
}
)
上面这段逻辑来自 Android 官方 ML Kit Analyzer 文档的推荐写法。COORDINATE_SYSTEM_VIEW_REFERENCED 让返回的 Barcode 坐标已经转换到 PreviewView 的坐标系中,后面如果要在二维码位置画一个扫描框,不需要再做旋转和缩放校正。
解析结果:rawValue 是起点,不是终点
barcode.rawValue 返回的是二维码的原始字符串。如果业务只关心“扫出一个 URL”或者“扫出一段文本”,到这里就可以结束了。但 QR Code 支持结构化数据,ML Kit 会自动把 WiFi、URL、联系人、地理位置等类型解析成对应的字段,你不需要自己写正则去拆 WIFI:S:...;P:...;;。
一个轻量的分发函数可以长这样:
kotlin
fun handleBarcode(barcode: Barcode): ScanPayload {
return when (barcode.valueType) {
Barcode.TYPE_URL -> ScanPayload.Url(barcode.url?.url ?: barcode.rawValue.orEmpty())
Barcode.TYPE_WIFI -> {
val wifi = barcode.wifi
ScanPayload.Wifi(
ssid = wifi?.ssid.orEmpty(),
password = wifi?.password.orEmpty(),
encryption = wifi?.encryptionType ?: 0
)
}
Barcode.TYPE_TEXT -> ScanPayload.Text(barcode.rawValue.orEmpty())
else -> ScanPayload.Raw(barcode.rawValue.orEmpty())
}
}
rawValue 永远作为兜底字段存在,valueType 用来决定要不要走结构化分支。这样即便遇到 ML Kit 没有自动分类的私有二维码格式,也不会把内容丢掉。
让“快捷”落到工程细节上
ML Kit 本身已经够快了,但扫码模块的“手感”往往死在几个工程细节上。
第一,防重复回调。 MlKitAnalyzer 是逐帧分析的,同一个二维码连续几帧都出现在取景框里,回调会被触发多次。用一个 AtomicBoolean 或者时间窗口去重:
kotlin
private val isProcessing = AtomicBoolean(false)
if (isProcessing.compareAndSet(false, true)) {
onQrCodeScanned(value)
// 业务处理完成后,延迟一小段时间再释放
Handler(Looper.getMainLooper()).postDelayed({
isProcessing.set(false)
}, 800)
}
第二,分辨率不要拉满。 二维码识别不需要 4K 预览帧,1280×720 或者 640×480 已经足够覆盖绝大多数场景。高分辨率只会增加 ImageAnalysis 的转换和推理负担,帧率反而可能下降。CameraX 的 ImageAnalysis 默认 target resolution 已经针对 ML Kit 做了适配,非必要不要手动往上调。
第三,闪光灯/自动变焦的兜底。 ML Kit 在弱光下比 ZXing 强,但不代表它是夜视仪。如果你的扫码场景经常出现在地下车库、仓库、超市冷柜附近,加一个“轻触对焦 + 闪光灯切换”的入口,成本很低,但对首次扫描成功率的影响远大于换解码库。ML Kit 的 BarcodeScannerOptions 也支持自动变焦,开启后会让相机在检测到二维码距离过远时自动拉近,进一步减少用户手动调整的操作。
ML Kit vs ZXing:把“快”拆开看
把两个库的差异拆成几个工程维度,比一句“ML Kit 更快”有用:
| 维度 | ZXing | ML Kit barcode-scanning |
|---|---|---|
| 解码路径 | 纯 CPU 图像处理 | 端侧 ML 模型 + 硬件加速 |
| 弱光/模糊场景 | 识别率明显下降,需要手动调参 | 对低对比度、轻微模糊的容错更高 |
| 连续扫码温控 | 长时间扫描容易积热 | 官方针对手机 SoC 优化,连续扫描温控更好 |
| 多码同时识别 | 不支持 | 支持一帧内识别多个二维码 |
| 集成复杂度 | 需要自己接 ImageAnalysis 和坐标变换 | MlKitAnalyzer 开箱即用,坐标自动对齐 |
| App 体积增量 | 较小 | bundled 约 2.4 MB,unbundled 约 200 KB |
数据来源:掘金对比文章、IDCTOP 性能分析、ML Kit 官方文档及移动端优化实践。
如果你的项目对包体极其敏感、并且扫码场景非常可控(光线充足、二维码印刷质量好、不需要连续扫),ZXing 依然是合理选择。但只要涉及“用户随手扫、环境不可控、要快”的产品语境,ML Kit 的硬件加速和模型鲁棒性带来的体验差是实打实的。
用 Trae 写这个模块时,哪些环节真的省时间
Trae 在这个流程里最有价值的不是“从零生成整个 App”,而是吃掉那些零碎但必须准确的配置和骨架代码:
- 把 ML Kit 的 bundled / unbundled 两种依赖坐标和体积差异一次性列清楚,省掉翻文档比对的时间;
- 根据
MlKitAnalyzer的官方示例生成 Kotlin 调用骨架,包括BarcodeScannerOptions、COORDINATE_SYSTEM_VIEW_REFERENCED和getValue(barcodeScanner)这些容易漏掉的参数; - 批量补全
Barcode.valueType的分支结构,把TYPE_URL、TYPE_WIFI、TYPE_TEXT的字段访问代码一次拉出来; - 按照
.trae/rules/里的约束,把 ZXing 依赖和手动 Camera 生命周期管理拦在生成结果之外。
但编译报错、Gradle 同步、真机上相机打不开、ML Kit 模型加载失败这类问题,最终还是要回到 Android Studio 的 Logcat 和调试器里解决。把 Trae 当“高速代码副驾”、把 AS 当“验证工位”,这个分工跑顺之后,一个扫码模块从依赖配置到真机跑通的时间可以从半天压到一两个小时。
小结
ML Kit barcode-scanning 的“快捷”不是营销词,它来自三个可验证的工程事实:端侧 ML 模型替代了纯 CPU 的图像处理路径,硬件加速让单帧解码进入几十毫秒级,MlKitAnalyzer 把 CameraX 集成中最容易出错的坐标变换和用例绑定收进了框架内部。在弱光、模糊、连续帧这些真实扫码场景下,它相对 ZXing 的优势是速度、容错和温控的叠加。
Trae 在这个过程中做的事情更朴素:让你少翻文档、少写重复的配置和分支代码,把精力留给真机验证和交互细节。扫码模块最终好不好用,取决于你有没有把防重复回调、分辨率控制、闪光灯兜底这些“最后一公里”的工程问题处理好——但前提是,解码层本身要够快、够稳。ML Kit 把这层地基打好了。