Flutter联网搜索位置功能仅模拟器正常 真机运行异常排查

问题表现 #

• 参考教程完成编码后，应用仅可在模拟器上正常运行
• 真机设备上联网搜索位置的功能无法正常工作，无法确认代码实现是否存在错误

现有核心实现代码 #

搜索栏文本变化回调逻辑 #

void onSearchBarTextChanged(String value) async {
if (await connectionStatus.checkConnection()) {
  isSnackbarOn = false;
  if (value == '') {
    typingState = false;
    loadingState = false;
  } else {
    loadingState = true;
    typingState = true;
    update();
    locationList = ((await api.getCities(value))
        .toList()
        .map((city) => Location.fromAPI(city))).toList();
    loadingState = false;
  }
  update();
} else {
  searchTextConroller.clear();
  if (!isSnackbarOn) {
    showSnackBar(
        title: "Connection", description: "No internet connection");
  }
}
}

文本输入组件实现 #

Container(
          child: controller.components.buildAppbar(
              node: controller.focusNode,
              onLocationIconClicked: () => controller.getLocationFromGps(),
              onTextChanged: (value) =>
                  controller.onSearchBarTextChanged(value),
              offset: controller.scrollOffset,
              controller: controller,
              onClickBack: () => controller.backClicked()),
        ),

排查修复方案 #

• 优先检查平台网络权限配置：这是模拟器运行正常、真机功能失效的最高频原因。模拟器默认拥有宽松的权限配置，多数教程不会特意提真机所需的权限声明，缺失时真机直接拦截网络请求：
  • Android端：在android/app/src/main/AndroidManifest.xml的manifest根节点下（与application标签同级）添加网络权限声明<uses-permission android:name="android.permission.INTERNET" />。如果使用的接口是HTTP而非HTTPS，还要在application标签上添加android:usesCleartextTraffic="true"，否则Android 9以上版本的真机会默认拦截明文HTTP请求。
  • iOS端：在ios/Runner/Info.plist中添加ATS配置，允许应用发起网络请求，否则系统默认拦截非HTTPS请求。
• 排查网络状态检测逻辑误判：当前代码逻辑会先通过connectionStatus.checkConnection()判断网络连通性，再发起搜索请求。很多网络状态检测插件在国产定制ROM、需要网页认证的公共WiFi环境下会出现误判，明明有网络却返回无网结果，直接走到弹无网提示的分支。可以临时注释掉这层网络判断，直接调用搜索接口测试，确认是不是检测逻辑的问题。
• 补全异步请求的异常捕获：当前api.getCities的调用外层没有做异常捕获，真机环境下如果出现证书校验失败、DNS解析失败、请求被系统拦截等问题，会直接静默失败，没有任何报错提示。给请求加上try-catch，调试时打印具体错误信息就能快速定位问题：

try {
  locationList = ((await api.getCities(value))
      .toList()
      .map((city) => Location.fromAPI(city))).toList();
} catch (e) {
  debugPrint('位置搜索请求异常: $e');
  loadingState = false;
  update();
}

• 核对接口请求兼容性：部分教程使用的测试接口可能对请求来源做了校验，比如拦截非常规User-Agent、非移动端正式签名的请求，可以通过抓包查看真机是否正常发出请求、接口返回的具体错误码是什么，针对性调整请求配置即可。

内容的提问来源于stack exchange，提问作者trovap