Flutter Web应用API调用触发XMLHttpRequest error问题排查问询

问题基本情况 #

Flutter Web开发过程中调用自研接口时抛出XMLHttpRequest error阻塞开发，已尝试以下操作均未解决问题：

• 删除Flutter缓存tool stamp文件
• 启动浏览器时添加--disable-web-security参数关闭安全校验
  经测试，将请求地址替换为公开测试接口https://jsonplaceholder.typicode.com/todos/1时，请求可正常执行返回结果。

错误堆栈信息 #

Error: XMLHttpRequest error.
    C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/_internal/js_dev_runtime/patch/core_patch.dart 910:28                get current
packages/http/src/browser_client.dart 69:22                                                                                    <fn>
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/zone.dart 1685:54                                              runUnary
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/future_impl.dart 159:18                                        handleValue
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/future_impl.dart 766:44                                        handleValueCallback
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/future_impl.dart 795:13                                        _propagateToListeners
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/future_impl.dart 592:7                                         [_complete]
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/stream_pipe.dart 61:11                                         _cancelAndValue
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/async/stream.dart 1288:7                                             <fn>
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 334:14  _checkAndCall
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/_internal/js_dev_runtime/private/ddc_runtime/operations.dart 339:39  dcall
C:/b/s/w/ir/cache/builder/src/out/host_debug/dart-sdk/lib/html/dart2js/html_dart2js.dart 37301:58                              <fn>

触发错误的业务代码 #

Future CustomerCall(String CustomerID, String APIKey) async {
  final queryParameters = {
    'APIKey': APIKey,
    'customer_id': CustomerID
  };

  final uri = Uri.https('8.8.8.8', '/Customers', queryParameters);
  final response = await http.get(uri, headers: {
    "Accept": "application/json",
    "Access-Control-Allow-Origin": "*"
  });

  print(response.statusCode);
  print(response.body);
}

根因定位 #

公开接口调用正常，说明Flutter工具链、http包本身无异常，删除缓存的操作完全不对症。问题核心是浏览器安全策略拦截请求，具体原因按优先级排查：

1. CORS配置错误：代码里在请求头添加Access-Control-Allow-Origin: *是无效操作，这个字段是服务端返回的响应头，前端手动加在请求里不会被浏览器认可。自研接口没有正确配置CORS规则，没有在响应（包括OPTIONS预检请求的响应）里返回合法的跨域头，浏览器直接拦截响应。
2. --disable-web-security参数未生效：加该参数启动Chrome前必须完全关闭所有Chrome后台进程，且必须指定独立的用户数据目录，否则Chrome会复用已有正常进程，参数不加载。
3. HTTPS证书异常：自研接口如果使用自签名证书、证书过期、证书绑定域名和访问的IP/域名不匹配，浏览器会直接拦截HTTPS请求，抛出XMLHttpRequest error。
4. 端口号本身不会触发该错误，只要端口在请求地址中正确填写、服务端正常监听即可。

可行解决方案 #

开发环境临时调试方案 #

• 方案1：正确启动禁用安全限制的Chrome
  先彻底关闭所有Chrome进程（任务管理器里确认没有Chrome后台进程残留），执行以下命令启动：

  # Windows系统示例
  chrome.exe --disable-web-security --ignore-certificate-errors --user-data-dir=C:\temp\chrome_dev_profile
  

  看到浏览器顶部提示「您使用的是不受支持的命令行标记: --disable-web-security」即为配置成功，用这个Chrome实例访问Flutter Web本地服务即可绕过跨域和证书校验。
• 方案2：使用Flutter Web代理转发（无需改浏览器配置）
  在项目根目录新建proxy.config.json文件：

  {
    "/api/*": {
      "target": "https://你的自研接口地址",
      "secure": false,
      "changeOrigin": true
    }
  }
  

  启动Flutter Web时附加代理参数：

  flutter run -d chrome --web-port=5000 --proxy-config proxy.config.json
  

  前端代码中将请求地址改为相对路径/api/Customers即可，代理会自动转发请求到后端，secure: false会自动忽略自签名证书错误，完全绕开浏览器跨域限制。

生产环境永久修复方案 #

1. 为自研HTTPS服务配置正规CA签发的有效SSL证书，确保证书绑定的域名/IP和前端访问地址一致，无过期、域名不匹配问题。
2. 在自研服务端正确配置CORS规则：
   • 对所有接口（包括OPTIONS方法的预检请求）返回正确的CORS响应头
   • Access-Control-Allow-Origin配置为前端部署的源地址，若接口不携带Cookie、Authorization等身份凭证可临时配置为*，携带凭证时必须指定明确的源地址，不能用通配符
   • Access-Control-Allow-Methods配置允许的请求方法（GET、POST、OPTIONS等）
   • Access-Control-Allow-Headers配置允许的请求头，包含业务用到的Accept、自定义鉴权头等
3. 可选优化：通过Nginx反向代理将前端静态资源和后端接口部署在同一个源下，从根源上消除跨域场景。

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