1. 相册选图解析二维码为什么比扫一扫更容易翻车Zxing 图片识别指的是用 Zxing 这个开源库去解析一张已经存在的二维码图片而不是打开摄像头实时扫码。它适合谁适合做 Android 端工具类 App、票务核销、设备配网、活动签到这类场景——用户手里已经有一张二维码截图或照片你只需要从相册里选出来把里面的字符串读出来就行。听起来比扫一扫简单但真正动手你会发现坑不少。摄像头扫码时Zxing 拿到的是连续的 YUV 帧图像质量、角度、光照它都能实时调整而从相册选图你拿到的是一个content://开头的 Uri背后可能是 MediaStore、DownloadsProvider、ExternalStorageProvider甚至某个网盘 App 的私有 Provider。你要先把它变成能解码的 Bitmap还要控制采样率否则一张 4000×3000 的照片直接丢给解码器内存和耗时都会很难看。更麻烦的是很多教程只给了scanningImage(path)这一段前面 Uri 转路径、权限申请、线程切换全被省略了。结果就是代码复制过去path是 null或者解码返回 null日志里只有一句NotFoundException完全不知道从哪查。这篇就把从相册选图到解析成功的完整链路拆开给出可复制的依赖、权限、核心解码骨架以及失败日志的排查动作。2. 前置准备依赖、权限与 TaoToken 接入配置2.1 build.gradle 依赖Zxing 的核心库是coreAndroid 端集成一般用zxing-android-embedded或者只引 core 自己写解码逻辑。如果你只需要图片识别不涉及摄像头扫码引 core 就够了体积更小。// app/build.gradle dependencies { implementation com.google.zxing:core:3.5.3 // 如果还需要摄像头扫码再加下面这个 // implementation com.journeyapps:zxing-android-embedded:4.3.0 }core版本建议用 3.5.x早期 3.3.x 在部分中文编码和纠错级别上有差异。引完之后 Sync 一下确认没有冲突。2.2 AndroidManifest 权限配置从相册选图Android 6.0 到 13 的权限模型一直在变这是最容易出问题的地方。你需要按版本区分manifest xmlns:androidhttp://schemas.android.com/apk/res/android !-- Android 12 及以下读取外部存储 -- uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / !-- Android 13 及以上用细分媒体权限 -- uses-permission android:nameandroid.permission.READ_MEDIA_IMAGES / application android:requestLegacyExternalStoragetrue ... ... /application /manifestrequestLegacyExternalStoragetrue在 targetSdk 29 时有用30 以后系统会忽略它但加上不影响。真正要处理的是运行时权限Android 13 上申请READ_EXTERNAL_STORAGE会直接被拒必须申请READ_MEDIA_IMAGES。2.3 用 TaoToken 做解码结果的语义校验图片识别出来的字符串有时候是乱码或者被截断的。我在项目里会加一层校验把解码结果丢给模型判断它是不是一个合法的 URL、订单号或 JSON。TaoToken 的 API 兼容常见对话接口接入成本很低。# 获取 API Key 后用 curl 验证一下模型对话是否通 curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 判断这串内容是否是合法URLhttps://example.com/order?id123}] }API Key 在控制台的 API Keys 页面创建模型对话入口可以直接在线试。如果你后面要做长期编码或 Agent 类功能Coding Plan 会更划算。接入文档里有完整的参数说明。3. 可复制配置Uri 转路径、Bitmap 采样与解码骨架3.1 相册选图的 Intent 与回调先看选图入口。用ACTION_PICK或ACTION_GET_CONTENT都行前者直接进图库后者会弹出选择器。private static final int REQUEST_PICK_IMAGE 1001; private void pickImageFromGallery() { Intent intent new Intent(Intent.ACTION_PICK, MediaStore.Images.Media.EXTERNAL_CONTENT_URI); intent.setType(image/*); startActivityForResult(intent, REQUEST_PICK_IMAGE); } Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode REQUEST_PICK_IMAGE resultCode RESULT_OK data ! null) { Uri imageUri data.getData(); // 注意这里不要在主线程做解码 new Thread(() - { String path Utils.getPath(getApplicationContext(), imageUri); Result result scanningImage(path); runOnUiThread(() - handleResult(result)); }).start(); } }关键点data.getData()拿到的是 Uri不是路径。Android 10 以后分区存储很多 Uri 根本转不出真实路径所以下面的getPath要能兜底。3.2 Uri 转绝对路径的兼容写法这段是 excerpt 里提到的核心工具方法我把它整理成可直接用的版本并补上注释说明每个分支对应哪种 Provider。public class Utils { public static String getPath(final Context context, final Uri uri) { final boolean isKitKat Build.VERSION.SDK_INT Build.VERSION_CODES.KITKAT; // DocumentProviderAndroid 4.4 的文件选择器 if (isKitKat DocumentsContract.isDocumentUri(context, uri)) { // 外部存储 if (isExternalStorageDocument(uri)) { final String docId DocumentsContract.getDocumentId(uri); final String[] split docId.split(:); final String type split[0]; if (primary.equalsIgnoreCase(type)) { return Environment.getExternalStorageDirectory() / split[1]; } } // 下载目录 else if (isDownloadsDocument(uri)) { final String id DocumentsContract.getDocumentId(uri); final Uri contentUri ContentUris.withAppendedId( Uri.parse(content://downloads/public_downloads), Long.valueOf(id)); return getDataColumn(context, contentUri, null, null); } // 媒体库 else if (isMediaDocument(uri)) { final String docId DocumentsContract.getDocumentId(uri); final String[] split docId.split(:); final String type split[0]; Uri contentUri null; if (image.equals(type)) { contentUri MediaStore.Images.Media.EXTERNAL_CONTENT_URI; } else if (video.equals(type)) { contentUri MediaStore.Video.Media.EXTERNAL_CONTENT_URI; } else if (audio.equals(type)) { contentUri MediaStore.Audio.Media.EXTERNAL_CONTENT_URI; } final String selection _id?; final String[] selectionArgs new String[]{split[1]}; return getDataColumn(context, contentUri, selection, selectionArgs); } } // MediaStore 通用 else if (content.equalsIgnoreCase(uri.getScheme())) { return getDataColumn(context, uri, null, null); } // 文件路径 else if (file.equalsIgnoreCase(uri.getScheme())) { return uri.getPath(); } return null; } public static String getDataColumn(Context context, Uri uri, String selection, String[] selectionArgs) { Cursor cursor null; final String column _data; final String[] projection {column}; try { cursor context.getContentResolver().query(uri, projection, selection, selectionArgs, null); if (cursor ! null cursor.moveToFirst()) { final int columnIndex cursor.getColumnIndexOrThrow(column); return cursor.getString(columnIndex); } } finally { if (cursor ! null) cursor.close(); } return null; } public static boolean isExternalStorageDocument(Uri uri) { return com.android.externalstorage.documents.equals(uri.getAuthority()); } public static boolean isDownloadsDocument(Uri uri) { return com.android.providers.downloads.documents.equals(uri.getAuthority()); } public static boolean isMediaDocument(Uri uri) { return com.android.providers.media.documents.equals(uri.getAuthority()); } }注意Android 10 以后_data列可能返回 null因为分区存储不允许直接访问真实路径。这时候getPath会返回 null你需要改用ContentResolver.openInputStream(uri)直接读流再BitmapFactory.decodeStream。这是很多老教程没覆盖的坑。3.3 Bitmap 采样与 MultiFormatReader 解码拿到路径后不要直接decodeFile全尺寸加载。先读边界算采样率再解码。这样一张 4000×3000 的图会被压到 200px 高度左右解码速度从几百毫秒降到几十毫秒。protected Result scanningImage(String path) { if (TextUtils.isEmpty(path)) { return null; } HashtableDecodeHintType, Object hints new Hashtable(); hints.put(DecodeHintType.CHARACTER_SET, UTF-8); // 提高识别率尝试更努力地解码 hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); // 支持多种码制不限于 QR hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128, BarcodeFormat.EAN_13)); BitmapFactory.Options options new BitmapFactory.Options(); options.inJustDecodeBounds true; BitmapFactory.decodeFile(path, options); // 目标高度 200px按比例算采样率 int sampleSize 1; if (options.outHeight 200) { sampleSize Math.round(options.outHeight / 200f); } options.inJustDecodeBounds false; options.inSampleSize sampleSize; options.inPreferredConfig Bitmap.Config.RGB_565; Bitmap scanBitmap BitmapFactory.decodeFile(path, options); if (scanBitmap null) { return null; } RGBLuminanceSource source new RGBLuminanceSource(scanBitmap); BinaryBitmap bitmap1 new BinaryBitmap(new HybridBinarizer(source)); MultiFormatReader reader new MultiFormatReader(); reader.setHints(hints); try { return reader.decode(bitmap1); } catch (NotFoundException e) { Log.e(Zxing, 未找到二维码: e.getMessage()); } catch (ChecksumException e) { Log.e(Zxing, 校验和错误: e.getMessage()); } catch (FormatException e) { Log.e(Zxing, 格式错误: e.getMessage()); } finally { reader.reset(); scanBitmap.recycle(); } return null; }这里用MultiFormatReader替代了 excerpt 里的QRCodeReader好处是同一张图里如果是 Code128 条码也能识别。TRY_HARDER会牺牲一点速度换识别率图片识别场景下值得开。3.4 中文乱码处理Zxing 解码出来的字符串如果二维码是用 GB2312 编码生成的直接读会乱码。需要做一次编码探测和转换。private String recode(String str) { String format ; try { boolean ISO Charset.forName(ISO-8859-1).newEncoder().canEncode(str); if (ISO) { format new String(str.getBytes(ISO-8859-1), GB2312); } else { format str; } } catch (UnsupportedEncodingException e) { e.printStackTrace(); } return format; }提示如果二维码内容是纯 ASCII比如 URLcanEncode返回 true但转换后不会变。只有真正含中文且被错误编码时这一步才有意义。更稳妥的做法是优先用 UTF-8 解码失败再尝试 GB2312。4. 验证请求从选图到解析成功的完整步骤4.1 验证步骤第一步在真机上安装 App进入主界面点击「从相册选择」按钮。第二步选一张包含二维码的截图或照片。第三步观察 Logcat 输出过滤 tagZxing。第四步如果解析成功界面会显示二维码内容如果失败会弹出「图片格式有误」。4.2 成功日志长什么样解析成功时Logcat 里应该能看到类似这样的输出I/Zxing: 解析成功内容长度48 I/Result: https://example.com/order?id123456signabc如果开了TRY_HARDER解码耗时一般在 50–150ms 之间。超过 500ms 说明图片太大或者采样率没生效。4.3 用 TaoToken 做结果二次校验解析出来的字符串有时候是残缺的。我会把结果发给模型做一次语义判断确认它是不是完整的 URL 或订单号。这一步在票务核销场景特别有用能提前拦住脏数据。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 这串二维码内容是否完整只回答是或否https://example.com/order?id123}] }模型对话入口可以直接在线测试不用写代码就能验证效果。如果校验通过再把结果回传给父 Activity。5. 本篇常见错排查NotFoundException、空路径与乱码5.1 解码返回 null日志只有 NotFoundException这是最常见的。原因通常有三个图片里根本没有二维码、二维码太小采样率设太大导致细节丢失、或者二维码对比度太低。排查动作先把inSampleSize固定为 1用原图解码试试如果原图能解说明采样率算错了。另外检查TRY_HARDER是否开启。5.2 getPath 返回 nullAndroid 10 以上_data列可能拿不到。这时候不要死磕路径改用流式解码InputStream is getContentResolver().openInputStream(uri); Bitmap bitmap BitmapFactory.decodeStream(is); // 后续用 RGBLuminanceSource 解码这个方案在所有版本上都通用推荐作为兜底。5.3 中文乱码如果二维码是用 GB2312 生成的而 Zxing 默认按 UTF-8 解就会乱码。排查动作打印原始字节的十六进制看是否符合 GB2312 编码特征。处理方式就是上面的recode方法或者直接在hints里指定CHARACTER_SET为GB2312再试一次。5.4 子线程 Toast 崩溃在子线程里直接Toast.makeText().show()会抛RuntimeException: Cant create handler inside thread that has not called Looper.prepare()。解决办法有两个一是用runOnUiThread切回主线程二是像 excerpt 里那样Looper.prepare()Looper.loop()。推荐前者更干净。5.5 权限被拒后没有回调Android 13 上申请READ_EXTERNAL_STORAGE会被静默拒绝。排查动作检查targetSdkVersion如果是 33 及以上必须申请READ_MEDIA_IMAGES。另外用户如果选了「不再询问」需要引导去设置页手动开启。6. 接入与排障API Keys、文档与 Coding Plan图片识别链路跑通之后如果你要把解码结果接到后端做业务校验或者做批量图片解析的 Agent建议先把 API Key 管好。API Keys 页面可以创建多个 Key按环境区分。接入文档里有完整的鉴权和错误码说明排障时对着看能省不少时间。长期做 Android 端编码或者 Agent 类功能的话Coding Plan 比按量付费更划算适合高频调用场景。模型对话入口可以随时在线验证解码结果是否符合预期不用每次都写测试代码。整套流程走下来最关键的其实不是解码那几行代码而是 Uri 转路径的兼容处理和采样率的计算。这两块处理好了NotFoundException会少一大半。剩下的就是权限和线程问题按上面的排查动作逐个过一遍基本都能定位到。 Zxing图片识别实战：从相册选二维码图片解析的配置与验证总结
1. 相册选图解析二维码为什么比扫一扫更容易翻车Zxing 图片识别指的是用 Zxing 这个开源库去解析一张已经存在的二维码图片而不是打开摄像头实时扫码。它适合谁适合做 Android 端工具类 App、票务核销、设备配网、活动签到这类场景——用户手里已经有一张二维码截图或照片你只需要从相册里选出来把里面的字符串读出来就行。听起来比扫一扫简单但真正动手你会发现坑不少。摄像头扫码时Zxing 拿到的是连续的 YUV 帧图像质量、角度、光照它都能实时调整而从相册选图你拿到的是一个content://开头的 Uri背后可能是 MediaStore、DownloadsProvider、ExternalStorageProvider甚至某个网盘 App 的私有 Provider。你要先把它变成能解码的 Bitmap还要控制采样率否则一张 4000×3000 的照片直接丢给解码器内存和耗时都会很难看。更麻烦的是很多教程只给了scanningImage(path)这一段前面 Uri 转路径、权限申请、线程切换全被省略了。结果就是代码复制过去path是 null或者解码返回 null日志里只有一句NotFoundException完全不知道从哪查。这篇就把从相册选图到解析成功的完整链路拆开给出可复制的依赖、权限、核心解码骨架以及失败日志的排查动作。2. 前置准备依赖、权限与 TaoToken 接入配置2.1 build.gradle 依赖Zxing 的核心库是coreAndroid 端集成一般用zxing-android-embedded或者只引 core 自己写解码逻辑。如果你只需要图片识别不涉及摄像头扫码引 core 就够了体积更小。// app/build.gradle dependencies { implementation com.google.zxing:core:3.5.3 // 如果还需要摄像头扫码再加下面这个 // implementation com.journeyapps:zxing-android-embedded:4.3.0 }core版本建议用 3.5.x早期 3.3.x 在部分中文编码和纠错级别上有差异。引完之后 Sync 一下确认没有冲突。2.2 AndroidManifest 权限配置从相册选图Android 6.0 到 13 的权限模型一直在变这是最容易出问题的地方。你需要按版本区分manifest xmlns:androidhttp://schemas.android.com/apk/res/android !-- Android 12 及以下读取外部存储 -- uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / !-- Android 13 及以上用细分媒体权限 -- uses-permission android:nameandroid.permission.READ_MEDIA_IMAGES / application android:requestLegacyExternalStoragetrue ... ... /application /manifestrequestLegacyExternalStoragetrue在 targetSdk 29 时有用30 以后系统会忽略它但加上不影响。真正要处理的是运行时权限Android 13 上申请READ_EXTERNAL_STORAGE会直接被拒必须申请READ_MEDIA_IMAGES。2.3 用 TaoToken 做解码结果的语义校验图片识别出来的字符串有时候是乱码或者被截断的。我在项目里会加一层校验把解码结果丢给模型判断它是不是一个合法的 URL、订单号或 JSON。TaoToken 的 API 兼容常见对话接口接入成本很低。# 获取 API Key 后用 curl 验证一下模型对话是否通 curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 判断这串内容是否是合法URLhttps://example.com/order?id123}] }API Key 在控制台的 API Keys 页面创建模型对话入口可以直接在线试。如果你后面要做长期编码或 Agent 类功能Coding Plan 会更划算。接入文档里有完整的参数说明。3. 可复制配置Uri 转路径、Bitmap 采样与解码骨架3.1 相册选图的 Intent 与回调先看选图入口。用ACTION_PICK或ACTION_GET_CONTENT都行前者直接进图库后者会弹出选择器。private static final int REQUEST_PICK_IMAGE 1001; private void pickImageFromGallery() { Intent intent new Intent(Intent.ACTION_PICK, MediaStore.Images.Media.EXTERNAL_CONTENT_URI); intent.setType(image/*); startActivityForResult(intent, REQUEST_PICK_IMAGE); } Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode REQUEST_PICK_IMAGE resultCode RESULT_OK data ! null) { Uri imageUri data.getData(); // 注意这里不要在主线程做解码 new Thread(() - { String path Utils.getPath(getApplicationContext(), imageUri); Result result scanningImage(path); runOnUiThread(() - handleResult(result)); }).start(); } }关键点data.getData()拿到的是 Uri不是路径。Android 10 以后分区存储很多 Uri 根本转不出真实路径所以下面的getPath要能兜底。3.2 Uri 转绝对路径的兼容写法这段是 excerpt 里提到的核心工具方法我把它整理成可直接用的版本并补上注释说明每个分支对应哪种 Provider。public class Utils { public static String getPath(final Context context, final Uri uri) { final boolean isKitKat Build.VERSION.SDK_INT Build.VERSION_CODES.KITKAT; // DocumentProviderAndroid 4.4 的文件选择器 if (isKitKat DocumentsContract.isDocumentUri(context, uri)) { // 外部存储 if (isExternalStorageDocument(uri)) { final String docId DocumentsContract.getDocumentId(uri); final String[] split docId.split(:); final String type split[0]; if (primary.equalsIgnoreCase(type)) { return Environment.getExternalStorageDirectory() / split[1]; } } // 下载目录 else if (isDownloadsDocument(uri)) { final String id DocumentsContract.getDocumentId(uri); final Uri contentUri ContentUris.withAppendedId( Uri.parse(content://downloads/public_downloads), Long.valueOf(id)); return getDataColumn(context, contentUri, null, null); } // 媒体库 else if (isMediaDocument(uri)) { final String docId DocumentsContract.getDocumentId(uri); final String[] split docId.split(:); final String type split[0]; Uri contentUri null; if (image.equals(type)) { contentUri MediaStore.Images.Media.EXTERNAL_CONTENT_URI; } else if (video.equals(type)) { contentUri MediaStore.Video.Media.EXTERNAL_CONTENT_URI; } else if (audio.equals(type)) { contentUri MediaStore.Audio.Media.EXTERNAL_CONTENT_URI; } final String selection _id?; final String[] selectionArgs new String[]{split[1]}; return getDataColumn(context, contentUri, selection, selectionArgs); } } // MediaStore 通用 else if (content.equalsIgnoreCase(uri.getScheme())) { return getDataColumn(context, uri, null, null); } // 文件路径 else if (file.equalsIgnoreCase(uri.getScheme())) { return uri.getPath(); } return null; } public static String getDataColumn(Context context, Uri uri, String selection, String[] selectionArgs) { Cursor cursor null; final String column _data; final String[] projection {column}; try { cursor context.getContentResolver().query(uri, projection, selection, selectionArgs, null); if (cursor ! null cursor.moveToFirst()) { final int columnIndex cursor.getColumnIndexOrThrow(column); return cursor.getString(columnIndex); } } finally { if (cursor ! null) cursor.close(); } return null; } public static boolean isExternalStorageDocument(Uri uri) { return com.android.externalstorage.documents.equals(uri.getAuthority()); } public static boolean isDownloadsDocument(Uri uri) { return com.android.providers.downloads.documents.equals(uri.getAuthority()); } public static boolean isMediaDocument(Uri uri) { return com.android.providers.media.documents.equals(uri.getAuthority()); } }注意Android 10 以后_data列可能返回 null因为分区存储不允许直接访问真实路径。这时候getPath会返回 null你需要改用ContentResolver.openInputStream(uri)直接读流再BitmapFactory.decodeStream。这是很多老教程没覆盖的坑。3.3 Bitmap 采样与 MultiFormatReader 解码拿到路径后不要直接decodeFile全尺寸加载。先读边界算采样率再解码。这样一张 4000×3000 的图会被压到 200px 高度左右解码速度从几百毫秒降到几十毫秒。protected Result scanningImage(String path) { if (TextUtils.isEmpty(path)) { return null; } HashtableDecodeHintType, Object hints new Hashtable(); hints.put(DecodeHintType.CHARACTER_SET, UTF-8); // 提高识别率尝试更努力地解码 hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); // 支持多种码制不限于 QR hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128, BarcodeFormat.EAN_13)); BitmapFactory.Options options new BitmapFactory.Options(); options.inJustDecodeBounds true; BitmapFactory.decodeFile(path, options); // 目标高度 200px按比例算采样率 int sampleSize 1; if (options.outHeight 200) { sampleSize Math.round(options.outHeight / 200f); } options.inJustDecodeBounds false; options.inSampleSize sampleSize; options.inPreferredConfig Bitmap.Config.RGB_565; Bitmap scanBitmap BitmapFactory.decodeFile(path, options); if (scanBitmap null) { return null; } RGBLuminanceSource source new RGBLuminanceSource(scanBitmap); BinaryBitmap bitmap1 new BinaryBitmap(new HybridBinarizer(source)); MultiFormatReader reader new MultiFormatReader(); reader.setHints(hints); try { return reader.decode(bitmap1); } catch (NotFoundException e) { Log.e(Zxing, 未找到二维码: e.getMessage()); } catch (ChecksumException e) { Log.e(Zxing, 校验和错误: e.getMessage()); } catch (FormatException e) { Log.e(Zxing, 格式错误: e.getMessage()); } finally { reader.reset(); scanBitmap.recycle(); } return null; }这里用MultiFormatReader替代了 excerpt 里的QRCodeReader好处是同一张图里如果是 Code128 条码也能识别。TRY_HARDER会牺牲一点速度换识别率图片识别场景下值得开。3.4 中文乱码处理Zxing 解码出来的字符串如果二维码是用 GB2312 编码生成的直接读会乱码。需要做一次编码探测和转换。private String recode(String str) { String format ; try { boolean ISO Charset.forName(ISO-8859-1).newEncoder().canEncode(str); if (ISO) { format new String(str.getBytes(ISO-8859-1), GB2312); } else { format str; } } catch (UnsupportedEncodingException e) { e.printStackTrace(); } return format; }提示如果二维码内容是纯 ASCII比如 URLcanEncode返回 true但转换后不会变。只有真正含中文且被错误编码时这一步才有意义。更稳妥的做法是优先用 UTF-8 解码失败再尝试 GB2312。4. 验证请求从选图到解析成功的完整步骤4.1 验证步骤第一步在真机上安装 App进入主界面点击「从相册选择」按钮。第二步选一张包含二维码的截图或照片。第三步观察 Logcat 输出过滤 tagZxing。第四步如果解析成功界面会显示二维码内容如果失败会弹出「图片格式有误」。4.2 成功日志长什么样解析成功时Logcat 里应该能看到类似这样的输出I/Zxing: 解析成功内容长度48 I/Result: https://example.com/order?id123456signabc如果开了TRY_HARDER解码耗时一般在 50–150ms 之间。超过 500ms 说明图片太大或者采样率没生效。4.3 用 TaoToken 做结果二次校验解析出来的字符串有时候是残缺的。我会把结果发给模型做一次语义判断确认它是不是完整的 URL 或订单号。这一步在票务核销场景特别有用能提前拦住脏数据。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 这串二维码内容是否完整只回答是或否https://example.com/order?id123}] }模型对话入口可以直接在线测试不用写代码就能验证效果。如果校验通过再把结果回传给父 Activity。5. 本篇常见错排查NotFoundException、空路径与乱码5.1 解码返回 null日志只有 NotFoundException这是最常见的。原因通常有三个图片里根本没有二维码、二维码太小采样率设太大导致细节丢失、或者二维码对比度太低。排查动作先把inSampleSize固定为 1用原图解码试试如果原图能解说明采样率算错了。另外检查TRY_HARDER是否开启。5.2 getPath 返回 nullAndroid 10 以上_data列可能拿不到。这时候不要死磕路径改用流式解码InputStream is getContentResolver().openInputStream(uri); Bitmap bitmap BitmapFactory.decodeStream(is); // 后续用 RGBLuminanceSource 解码这个方案在所有版本上都通用推荐作为兜底。5.3 中文乱码如果二维码是用 GB2312 生成的而 Zxing 默认按 UTF-8 解就会乱码。排查动作打印原始字节的十六进制看是否符合 GB2312 编码特征。处理方式就是上面的recode方法或者直接在hints里指定CHARACTER_SET为GB2312再试一次。5.4 子线程 Toast 崩溃在子线程里直接Toast.makeText().show()会抛RuntimeException: Cant create handler inside thread that has not called Looper.prepare()。解决办法有两个一是用runOnUiThread切回主线程二是像 excerpt 里那样Looper.prepare()Looper.loop()。推荐前者更干净。5.5 权限被拒后没有回调Android 13 上申请READ_EXTERNAL_STORAGE会被静默拒绝。排查动作检查targetSdkVersion如果是 33 及以上必须申请READ_MEDIA_IMAGES。另外用户如果选了「不再询问」需要引导去设置页手动开启。6. 接入与排障API Keys、文档与 Coding Plan图片识别链路跑通之后如果你要把解码结果接到后端做业务校验或者做批量图片解析的 Agent建议先把 API Key 管好。API Keys 页面可以创建多个 Key按环境区分。接入文档里有完整的鉴权和错误码说明排障时对着看能省不少时间。长期做 Android 端编码或者 Agent 类功能的话Coding Plan 比按量付费更划算适合高频调用场景。模型对话入口可以随时在线验证解码结果是否符合预期不用每次都写测试代码。整套流程走下来最关键的其实不是解码那几行代码而是 Uri 转路径的兼容处理和采样率的计算。这两块处理好了NotFoundException会少一大半。剩下的就是权限和线程问题按上面的排查动作逐个过一遍基本都能定位到。