graphql_flutter ^5.0.0 真机运行异常问题求助（Flutter 3.3.0环境）

1. 检查网络权限配置 #

• Android：确认android/app/src/main/AndroidManifest.xml中已添加网络权限：

  <uses-permission android:name="android.permission.INTERNET" />
  

  Android 10+设备需额外确认无网络访问限制配置。
• iOS：在ios/Runner/Info.plist中添加网络权限描述，若GraphQL服务使用HTTP协议，需配置ATS例外：

  <!-- 允许任意网络请求（仅开发环境建议使用） -->
  <key>NSAppTransportSecurity</key>
  <dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
  </dict>
  <!-- 或针对特定域名配置更安全的ATS规则 -->
  <!-- <key>NSAppTransportSecurity</key>
  <dict>
    <key>NSExceptionDomains</key>
    <dict>
      <key>your-graphql-domain.com</key>
      <dict>
        <key>NSIncludesSubdomains</key>
        <true/>
        <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
        <true/>
      </dict>
    </dict>
  </dict> -->
  

2. 验证依赖兼容性与版本调整 #

• 执行命令升级graphql_flutter到适配Flutter 3.3.0的最新稳定版：

  flutter pub upgrade graphql_flutter
  

• 若升级后问题仍存在，可临时降级到已知兼容的版本（如4.0.0系列），验证是否为版本兼容问题。

3. 处理真机TLS证书信任问题 #

• 若GraphQL服务使用自签名证书，真机默认会拒绝连接，需手动配置信任：
  • Android：将证书文件放入android/app/src/main/res/raw目录，通过HttpLink自定义HttpClient实现证书信任。
  • iOS：将证书添加到项目中，在Info.plist的NSExceptionDomains中配置对应域名的证书信任规则。

4. 清理缓存并重新构建 #

• 清理Flutter缓存并重新拉取依赖：

  flutter clean
  flutter pub get
  

• 卸载真机上的旧应用后，重新安装：

  flutter install
  

5. 检查Release模式编译配置 #

• Android：在android/app/proguard-rules.pro中添加规则，避免GraphQL相关类被混淆：

  -keep class com.apollographql.** { *; }
  -keep class graphql.** { *; }
  

• iOS：若开启Bitcode后出现异常，可在Xcode项目的Build Settings中关闭Bitcode（设置为No）。

6. 查看真机日志定位具体错误 #

• 连接真机后，执行以下命令获取详细运行日志，定位GraphQL请求相关的异常（如连接失败、证书错误、序列化问题等）：

  flutter logs
  

内容的提问来源于stack exchange，提问作者George Jonathan Osafo-Osei