1. 项目概述为什么在2021年还要专门写 device_info2021年Flutter 已经稳定进入 2.x 主线Dart 语言升级到 2.12 并全面启用空安全null safety整个生态正经历一次关键的“质量跃迁”。但恰恰是在这个节点上大量团队在做设备信息采集时突然发现——原来一直依赖的device_info插件在新版本 Flutter 新版 Android/iOS 构建环境下开始频繁报错、返回空值、甚至编译失败。这不是小问题它直接卡住灰度发布、AB测试分流、崩溃日志归因、合规 SDK 初始化等核心链路。我接手过三个不同行业的项目都卡在这个点上某电商 App 在 iOS 15 Beta 上deviceModel返回null某教育类应用在 Android 12 预览版中androidId变成还有个金融类项目因为buildNumber获取失败导致热更新校验逻辑误判整批用户被强制跳转到应用商店。这背后不是插件“坏了”而是平台规则变了。Android 11API 30起限制非特权应用访问ANDROID_ID和SERIALiOS 14 强制要求NSUserTrackingUsageDescription权限声明且identifierForVendor在用户重置广告标识符后会变更Flutter 自身也在 2.2 后收紧 Platform Channel 的线程模型旧版device_info的 Java/Kotlin/Objective-C 实现若未适配getPlatformVersion异步调用或未处理空安全桥接就会在 Dart 层抛出PlatformException或静默失败。所以“2021年使用 device_info”这件事本质是一次面向真实生产环境的兼容性攻坚——它不炫技但必须稳不求新但必须准不讲原理但每一步都要有依据。这篇文章就是为那些正在翻文档、查 GitHub Issues、对着控制台红字发愁的开发者写的。它不复述 API 列表不堆砌示例代码而是带你从为什么 2021 年要重看 device_info出发拆解它的底层通信机制、各平台权限边界、空安全迁移陷阱、以及当它失效时你真正能靠什么兜底。全文所有结论均来自我在 2021 年 Q2–Q4 期间对 7 个线上项目的实测验证包括真机覆盖 Android 8–12、iOS 13–15模拟器覆盖 x86_64/arm64构建方式涵盖 debug/profile/release 三态。你可以把它当作一份“2021 年 Flutter 设备信息采集生存指南”而不是一篇过时的插件教程。2. 核心设计思路与方案选型逻辑2.1 为什么是 device_info而不是自己手写 Platform Channel这是很多新手的第一疑问。答案很实在不是不能写而是不值得写。device_info插件当时主流版本是^2.0.3封装了三端最稳定、最合规的原生调用路径Android 端它不直接读Build.SERIAL已被弃用而是组合Build.MODEL、Build.MANUFACTURER、Build.VERSION.RELEASE并通过Settings.Secure.ANDROID_ID需READ_PHONE_STATE权限和BuildConfig.VERSION_NAME来自pubspec.yaml的version字段构成完整设备指纹。它还做了降级处理——当ANDROID_ID因权限缺失返回null时自动 fallback 到Build.SERIAL仅限 API 29或Build.getSerial()API ≥ 29需READ_PRIVILEGED_PHONE_STATE普通应用拿不到此时它会返回unknown而非 crash。iOS 端它不碰IDFA广告标识符需用户授权且 iOS 14 默认禁用而是用UIDevice.current.model返回 iPhone、iPad、UIDevice.current.name用户设置的设备名、[UIDevice currentDevice].systemVersion以及最关键的[[UIDevice currentDevice] identifierForVendor]。后者是 Apple 官方推荐的、同一开发商下所有 App 共享的、用户重置后才变更的唯一标识完全规避隐私红线。Web 端虽非本题重点但 2021 年已支持它用navigator.userAgentnavigator.platform做轻量识别不请求任何权限符合 Web 安全沙箱。自己手写 Channel 的代价是什么你要分别维护 Java/Kotlin含 Gradle 配置、ProGuard 规则、Objective-C/Swift含 Info.plist 权限声明、Xcode Build Settings、以及 Dart 层的异常捕获和空值处理。而device_info已帮你把这三层的坑踩平了——它在 2021 年 3 月发布的2.0.0版本就完成了 null safety 迁移且其 GitHub Issues 中 92% 的兼容性问题都在 2.0.2 版本中修复。提示不要迷信“最新版”。2021 年中device_info_plusdevice_info的社区增强版虽已出现但它在 iOS 14.5 上存在identifierForVendor缓存失效 Bug导致同设备多次调用返回不同值。我们实测下来device_info ^2.0.3是当年最稳的选择——它不花哨但每个字段都有明确的 fallback 策略和平台注释。2.2 为什么必须搭配 permission_handlerdevice_info本身不申请权限它只“读”。但读某些字段需要前置权限。2021 年最大的认知误区就是以为device_info是“开箱即用”的。以 Android 为例androidId需android.permission.READ_PHONE_STATE危险权限Android 6.0 需运行时申请serialNumberAPI ≥ 29 需android.permission.READ_PRIVILEGED_PHONE_STATE系统级权限普通 App 拿不到supportedAbis无需权限但需minSdkVersion 21iOS 更隐蔽identifierForVendor虽不需显式授权但若 App 在后台被系统终止后重启首次调用可能返回nilApple 的设计缺陷此时你需要主动触发一次UIDevice.current.isMultitaskingSupported来“唤醒”设备对象。所以权限管理不是可选项而是必选项。permission_handler ^8.1.62021 年主流版本提供了统一的跨平台 APIif (await Permission.phone.request().isGranted) { final info await DeviceInfoPlugin().androidInfo; print(Android ID: ${info.androidId}); }它比原生checkSelfPermissionrequestPermissions少写 80% 的胶水代码且内部已处理 Android 11 的package visibility白名单逻辑需在AndroidManifest.xml中声明queries。注意permission_handler的Permission.phone在 Android 12 会被标记为“废弃”但在 2021 年它是获取androidId的唯一合法途径。别被后来的文档误导——要看你 targetSdkVersion 是多少。2.3 为什么不能只信device_info必须设计兜底链路这是 2021 年血泪教训。我们曾在一个金融类 App 中发现device_info在华为 EMUI 11基于 Android 10上androidId字段永远返回9774d56d682e549c这是 Android 模拟器的默认 ID。原因EMUI 系统层对Settings.Secure.ANDROID_ID做了全局缓存且未随用户重置而刷新。于是我们建立了三级兜底策略主链路device_infopermission_handler获取androidId/identifierForVendor次链路当主链路为空或明显异常如长度 ≠ 16 位十六进制字符串降级到flutter_udid一个纯 Dart 实现的设备 ID 生成器基于Build.fingerprintBuild.hostBuild.id哈希不需权限终链路当次链路也失效如用户清除了 App 数据哈希种子丢失则用shared_preferences本地生成并持久化一个 UUID仅用于本次会话内追踪这个策略的关键在于“可验证、可降级、可审计”。我们给每个 ID 来源打标enum DeviceIdSource { deviceInfo, // 主链路 udid, // 次链路 localUuid, // 终链路 }上报日志时一并发送source字段后续可在 BI 系统中分析各来源占比——如果localUuid占比突然升至 30%说明主链路大面积失效需立刻排查系统兼容性。3. 核心细节解析与实操要点3.1 Android 端权限、配置与字段含义的硬核对照2021 年 Android 端的坑90% 出在配置和字段理解上。先看一张真实字段对照表基于AndroidDeviceInfo类Dart 字段名对应原生 API是否需权限2021 年实际可用性备注androidIdSettings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID)READ_PHONE_STATE★★★☆☆需手动申请API 29 可能返回null需判空boardBuild.BOARD无★★★★★硬件主板名如qcombootloaderBuild.BOOTLOADER无★★★★☆启动加载器版本如unknownbrandBuild.BRAND无★★★★★品牌名如googledeviceBuild.DEVICE无★★★★★设备代号如walleyedisplayBuild.DISPLAY无★★★★☆系统显示 ID如QP1A.190711.020fingerprintBuild.FINGERPRINT无★★★★★全局唯一构建指纹如google/walleye/walleye:10/QP1A.190711.020/5798548:user/release-keyshardwareBuild.HARDWARE无★★★★★硬件名称如walleyehostBuild.HOST无★★★★☆编译主机名如abfarm6idBuild.ID无★★★★★构建 ID如QP1A.190711.020manufacturerBuild.MANUFACTURER无★★★★★制造商如GooglemodelBuild.MODEL无★★★★★用户可见型号如Pixel 2productBuild.PRODUCT无★★★★☆产品名如walleyetagsBuild.TAGS无★★★★☆构建标签如release-keystypeBuild.TYPE无★★★★★构建类型如userversionBaseOsBuild.VERSION.BASE_OS无★★☆☆☆常为空基础 OS 版本多数设备返回versionCodenameBuild.VERSION.CODENAME无★★★★★代号如RELversionIncrementalBuild.VERSION.INCREMENTAL无★★★★☆构建增量号如5798548versionPreviewSdkBuild.VERSION.PREVIEW_SDK_INT无★☆☆☆☆仅预览版预览 SDK 版本号正式版为 0versionReleaseBuild.VERSION.RELEASE无★★★★★用户可见版本号如10versionSdkIntBuild.VERSION.SDK_INT无★★★★★SDK 整数版本如29versionSecurityPatchBuild.VERSION.SECURITY_PATCH无★★★★☆安全补丁日期如2020-07-01关键实操点androidId不是“设备唯一 ID”而是“应用安装实例 ID”。同一设备重装 AppandroidId会变不同 App即使同包名也会不同。它适合做“单 App 内用户去重”不适合做“跨 App 设备归因”。fingerprint是最稳定的字段它由Build类所有字段拼接哈希生成只要系统没刷机它就永不变化。我们曾用它作为androidId的 fallback当androidId为空时取fingerprint.substring(0, 16)前 16 位作为临时 ID。model和device必须一起看。model是用户看到的Pixel 2device是系统内部的walleye。有些 OEM 厂商会篡改model如把Redmi Note 8改成M2004J19C但device很难伪造。实操心得别在 release 包里打印fingerprint它包含编译时间、主机名等敏感信息可能泄露你的 CI/CD 环境。我们用flutter build apk --no-shrink打包时会加一行脚本自动替换fingerprint字段为release_build。3.2 iOS 端隐私合规与identifierForVendor的生命周期真相iOS 端的复杂性不在技术而在规则。2021 年 iOS 14.5 正式落地 ATTApp Tracking Transparency框架但device_info读取的identifierForVendor不受 ATT 约束——因为它不用于广告追踪而是用于“同一开发商下 App 的功能协同”。然而identifierForVendor有三个反直觉特性它不是永久的当用户在“设置 隐私 广告 重置广告标识符”后identifierForVendor不会变但当用户“卸载所有该开发商的 App 后再重装”它会变。它可能为 nilApp 首次启动、且从未调用过UIDevice.current任何属性时identifierForVendor可能返回nil。这不是 Bug是 Apple 的懒加载机制。它不区分 App同一个开发商相同 Team ID下的所有 App共享同一个identifierForVendor。所以我们的实操方案是FutureString? _getIosId() async { try { final info await DeviceInfoPlugin().iosInfo; // 强制触发 UIDevice 初始化 await Future.delayed(const Duration(milliseconds: 10)); if (info.identifierForVendor ! null) { return info.identifierForVendor; } else { // 降级用 bundle ID 系统版本哈希 final hash sha256.convert(utf8.encode( ${info.systemName}_${info.systemVersion}_${info.utsname.machine}, )); return hash.toString().substring(0, 16); } } catch (e) { return null; } }Info.plist 必须添加的键值2021 年易漏项keyNSUserTrackingUsageDescription/key string我们需要您的授权来提供个性化内容和广告/string !-- 即使不用 IDFAApple 审核也要求声明此键 -- keyUIBackgroundModes/key array stringaudio/string stringlocation/string /array !-- 若 App 需后台获取设备信息如定位上报需声明对应模式 --注意NSUserTrackingUsageDescription是 Apple 审核红线。2021 年 Q3我们一个教育 App 因未添加此键被拒申诉理由“我们没用 IDFA”无效——Apple 明确回复“只要代码中引用了AdSupport.frameworkdevice_info的 iOS 实现会 import 它就必须声明”。3.3 Web 端轻量识别与 UA 解析的务实取舍device_info在 Web 端的实现极其轻量// web/device_info_web.dart override FutureIosDeviceInfo getIosInfo() throw UnimplementedError(); override FutureAndroidDeviceInfo getAndroidInfo() throw UnimplementedError(); override FutureWebDeviceInfo getWebInfo() async { final ua html.window.navigator.userAgent; final platform html.window.navigator.platform; return WebDeviceInfo( userAgent: ua, platform: platform, ); }它不尝试解析 UA因为 UA 字符串千奇百怪Chrome on Windows:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36Safari on iPad:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.1 Safari/605.1.15微信内置浏览器:Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.10(0x18000a27) NetType/WIFI Language/zh_CN所以我们的策略是只做三件事记录原始userAgent字符串供后端 UA 分析引擎处理提取platformWin32、MacIntel、Linux armv7l判断大类用正则匹配/(iPhone|iPad|iPod|Android)/i判断是否为移动设备这样做的好处是零权限、零网络请求、100% 稳定。坏处是无法精确到机型如分不清 iPhone 12 和 iPhone 13。但对于 Web 端的 AB 测试、性能监控、错误归因这已经足够。实操心得Web 端不要试图用navigator.hardwareConcurrencyCPU 核心数或navigator.deviceMemory内存大小做设备分级——它们在 Safari 上返回undefined在部分安卓 WebView 中返回0.5。2021 年务实比精准更重要。4. 实操过程与核心环节实现4.1 从零搭建Flutter 2.2 device_info 2.0.3 的完整流程假设你用的是 Flutter 2.2.32021 年最稳定的 stable 版本以下是零误差的实操步骤Step 1添加依赖在pubspec.yaml中dependencies: flutter: sdk: flutter device_info: ^2.0.3 permission_handler: ^8.1.6 dev_dependencies: flutter_test: sdk: flutter flutter_lints: ^1.0.0注意device_info ^2.0.3与flutter 2.2.3完全兼容。别用^2.1.0它要求 Dart 2.14而 2.2.3 默认带 2.13.4。Step 2Android 端配置android/app/src/main/AndroidManifest.xmluses-permission android:nameandroid.permission.READ_PHONE_STATE / !-- 如果 targetSdkVersion 30Android 11还需添加 queries -- queries package android:namecom.android.phone / /queriesandroid/app/build.gradle确认minSdkVersion≥ 16device_info最低要求android/app/src/main/kotlin/.../MainActivity.kt确保继承FlutterFragmentActivityFlutter 2.0 要求Step 3iOS 端配置ios/Podfile取消注释# platform :ios, 9.0并改为platform :ios, 11.0device_info要求 iOS ≥ 11ios/Runner/Info.plist添加NSUserTrackingUsageDescription如前所述ios/Runner.xcworkspace在 Xcode 中打开检查Signing Capabilities→Background Modes是否启用如需后台采集Step 4Dart 层调用带完整错误处理import package:device_info/device_info.dart; import package:permission_handler/permission_handler.dart; class DeviceInfoService { static final DeviceInfoPlugin _deviceInfo DeviceInfoPlugin(); static FutureMapString, dynamic getDeviceInfo() async { final MapString, dynamic info {}; // Android if (Platform.isAndroid) { try { final androidInfo await _deviceInfo.androidInfo; info.addAll({ platform: android, model: androidInfo.model, brand: androidInfo.brand, version: androidInfo.version.release, sdkInt: androidInfo.version.sdkInt, androidId: await _getAndroidId(), // 封装了权限检查 }); } on PlatformException catch (e) { info[error] Android PlatformException: ${e.message}; } } // iOS else if (Platform.isIOS) { try { final iosInfo await _deviceInfo.iosInfo; info.addAll({ platform: ios, model: iosInfo.utsname.machine, // 比 iosInfo.model 更准如 iPhone13,2 name: iosInfo.name, systemName: iosInfo.systemName, systemVersion: iosInfo.systemVersion, identifierForVendor: await _getIosId(), }); } on PlatformException catch (e) { info[error] iOS PlatformException: ${e.message}; } } // Web else if (Platform.isWeb) { try { final webInfo await _deviceInfo.webInfo; info.addAll({ platform: web, userAgent: webInfo.userAgent, platform: webInfo.platform, }); } catch (e) { info[error] Web error: $e; } } return info; } static FutureString? _getAndroidId() async { final status await Permission.phone.status; if (status.isGranted) { try { final androidInfo await _deviceInfo.androidInfo; return androidInfo.androidId; } catch (e) { return null; } } else { final result await Permission.phone.request(); if (result.isGranted) { final androidInfo await _deviceInfo.androidInfo; return androidInfo.androidId; } else { return null; } } } }Step 5初始化时机选择千万别在main()中就调用device_info需要 Platform Channel 就绪。正确时机是首次启动在MaterialApp的home页面initState()中调用并setState更新 UI后台唤醒监听WidgetsBinding.instance.addObserver()的didChangeAppLifecycleState当状态为AppLifecycleState.resumed时重新拉取防止系统杀进程后identifierForVendor失效4.2 空安全迁移Dart 2.12 下的 5 个致命陷阱Flutter 2.2 默认启用 null safety而device_info2.0.3 是首批完成迁移的插件之一。但迁移不是“加个?”那么简单这里有 5 个真实踩过的坑Trap 1androidId类型是String?但文档没说它可能为// ❌ 错误以为 null 就是唯一空值 if (androidInfo.androidId null) { /* 处理 */ } // ✅ 正确必须同时判空字符串 if (androidInfo.androidId null || androidInfo.androidId!.isEmpty) { /* 处理 */ }原因Android 系统在权限拒绝后Settings.Secure.getString()返回null但在某些 OEM ROM如小米 MIUI中它返回空字符串。Trap 2iosInfo.utsname.machine是String?但utsname结构体本身可能为null// ❌ 危险链式调用会 crash final machine iosInfo.utsname.machine; // ✅ 安全逐层判空 final machine iosInfo.utsname?.machine ?? unknown;Trap 3getAndroidInfo()方法签名是FutureAndroidDeviceInfo但它可能抛出PlatformException而非返回null这意味着你不能写final info await _deviceInfo.androidInfo; // 如果失败这里就抛异常不会走到下一步 print(info.androidId); // 这行永远不会执行必须用try/catch不能依赖空值判断。Trap 4WebDeviceInfo的userAgent字段是String?但 Web 端永远不为null这是插件为保持 API 一致性做的“假可空”。实测中html.window.navigator.userAgent在所有现代浏览器中都返回非空字符串。所以你可以放心断言final userAgent webInfo.userAgent!; // 加 ! 是安全的Trap 5permission_handler的status是PermissionStatus枚举但PermissionStatus.permanentlyDenied在 Android 上永远不会出现Android 没有“永久拒绝”概念只有denied用户点“不再询问”后下次request()会直接返回denied不会弹窗。所以你的逻辑里不需要处理permanentlyDenied。实操心得我们写了一个DeviceInfoValidator类专门做字段清洗String cleanString(String? s) s?.trim().isNotEmpty true ? s! : unknown; int cleanInt(int? i) i ?? 0;所有从device_info拿到的字段必须过一遍这个清洗器再存入本地数据库或上报。5. 常见问题与排查技巧实录5.1 典型问题速查表问题现象可能原因排查命令/方法解决方案PlatformException(error, java.lang.NullPointerException, null, null)Android 端READ_PHONE_STATE权限未授予且androidInfo对象未判空adb logcatgrep device_info 查看 Java 层堆栈iosInfo.identifierForVendor为nullApp 首次启动UIDevice未初始化在 Xcode 控制台输入po [UIDevice currentDevice]看是否返回有效对象如前所述加Future.delayed或调用isMultitaskingSupporteddevice_info在 release 模式下返回空值ProGuard 混淆了Build类字段flutter build apk --no-shrink测试在android/app/proguard-rules.pro中添加-keep class android.os.Build { *; }permission_handler申请权限后仍返回deniedAndroid 11 的package visibility未声明adb shell dumpsys package packages | grep your.package.name查看requested permissions在AndroidManifest.xml中添加queries块Web 端userAgent为空字符串代码在main()中过早调用html.window尚未就绪在浏览器控制台执行navigator.userAgent看是否正常改为在WidgetsBinding.instance.addPostFrameCallback中调用device_info在 iOS 模拟器上返回iPhone Simulator但真机返回iPhone13,2这是正常行为模拟器硬件信息固定无需解决业务层应接受此差异在设备归因逻辑中将iPhone Simulator视为一类特殊设备5.2 真实故障复盘华为 P40 Pro 的androidId之谜2021 年 8 月我们收到大量华为 P40 ProEMUI 11.0.0用户的崩溃日志报错PlatformException(error, Attempt to invoke virtual method java.lang.String android.os.Build$VERSION.getRELEASE() on a null object reference, null, null)跟踪发现device_info的 Java 层在调用Build.VERSION.RELEASE时Build.VERSION对象为null。根因分析华为在 EMUI 11 中修改了Build类的静态初始化逻辑。当 App 在后台被系统回收后Build类的静态块未重新执行导致Build.VERSION为null。这不是device_info的 Bug而是 OEM 的 ROM 问题。临时解决方案我们在android/app/src/main/java/io/flutter/plugins/deviceinfo/DeviceInfoPlugin.java中将String release Build.VERSION.RELEASE;改为String release Build.VERSION.RELEASE ! null ? Build.VERSION.RELEASE : 10; // 默认 fallback并提交 PR 给device_info官方仓库后被2.0.4版本合并。长期规避策略所有Build字段访问必须加! null判空关键字段如androidId、model建立本地缓存App 启动时优先读缓存再异步刷新监控Build.VERSION为null的设备占比超过 0.1% 就触发告警5.3 性能与稳定性压测数据我们用flutter_driver对device_info做了 1000 次并发调用压测Android 11 真机调用方式平均耗时95% 分位耗时失败率备注单次getAndroidInfo()12.3 ms28.7 ms0.0%权限已授予单次getAndroidInfo()权限未授150.2 ms320.5 ms0.0%含权限弹窗等待连续 100 次调用无 await8.1 ms/次15.2 ms/次0.0%Platform Channel 异步队列处理getIosInfo()真机3.2 ms7.8 ms0.0%iOS 原生调用极快getWebInfo()Chrome0.1 ms0.3 ms0.0%纯 JS 变量读取结论device_info的性能不是瓶颈瓶颈永远在权限申请和系统 API 延迟。所以不要在滚动列表、动画帧等敏感路径中调用它。最佳实践是App 启动时调用一次结果存入GetIt或Riverpod全局复用。5.4 合规