Flutter开发中使用dio ^4.0.0版本库遇到问题寻求解决方案

问题原因及对应解决方案 #

1. 空安全适配异常

如果你的项目开启了Flutter空安全，现有封装代码的静态dio变量未做非空处理会直接编译报错，同时如果未提前调用初始化方法也会触发运行时空指针异常，修正后的初始化代码如下：

import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';

class DioHelper {
  // 加late关键字保证使用前已完成初始化
  static late Dio dio;

  static Future<void> init() async {
    dio = Dio(
      BaseOptions(
        baseUrl: 'https://192.168.0.23/',
        receiveDataWhenStatusError: true,
        // 配置超时时间避免请求无限制挂起
        connectTimeout: 10000,
        receiveTimeout: 15000,
        sendTimeout: 10000,
      ),
    );

    // 开发环境添加日志拦截器，方便排查请求参数和返回值
    if (!kReleaseMode) {
      dio.interceptors.add(LogInterceptor(
        requestBody: true,
        responseBody: true,
        requestHeader: true,
      ));
    }

    // 内网HTTPS证书校验逻辑（见下方说明）
    _setupSSLCert();
  }

  static void _setupSSLCert() {
    (dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = (client) {
      // 开发环境临时放行内网自签证书，生产环境请替换为证书校验逻辑
      client.badCertificateCallback = (cert, host, port) => host == '192.168.0.23';
      return client;
    };
  }

  // 封装通用GET请求方法示例
  static Future<Response> get(String path, {Map<String, dynamic>? queryParams}) async {
    return await dio.get(path, queryParameters: queryParams);
  }
}

注意：必须在main.dart的main方法中，发起任何网络请求之前调用DioHelper.init()完成初始化。

2. 内网HTTPS证书校验失败

你使用的是内网IP的HTTPS服务，通常这类服务都是自签名证书，dio默认会校验证书合法性，校验不通过会直接抛出连接异常，可通过两种方式处理：

• 开发调试阶段：用上面代码中的badCertificateCallback逻辑直接放行对应内网域名的证书
• 生产环境：将服务端的正式证书放到项目assets目录，初始化时加载证书做合法校验，避免安全风险：

// 需提前导入import 'package:flutter/services.dart';
ByteData certData = await rootBundle.load('assets/your_server_cert.cer');
(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = (client) {
  SecurityContext sc = SecurityContext();
  sc.setTrustedCertificatesBytes(certData.buffer.asUint8List());
  return HttpClient(context: sc);
};

3. 平台网络权限未配置

• Android端需要在android/app/src/main/AndroidManifest.xml中添加网络权限，高版本系统还需要开启明文流量许可：

<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<application
  android:usesCleartextTraffic="true"
  ... 其余配置不变
>

• iOS端需要在ios/Runner/Info.plist中添加ATS安全配置，放行HTTP/自签HTTPS请求：

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

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