Flutter CachedNetworkImage请求头异常问题问询

问题现象 #

使用CachedNetworkImage（及CachedNetworkImageProvider）传递自定义请求头时出现以下异常：

• 未设置imageRenderMethodForWeb: ImageRenderMethodForWeb.HttpGet时，请求头完全未传递
• 设置该参数后，服务器仅收到HTTP_ACCESS_CONTROL_REQUEST_HEADERS: auth，请求头值123丢失
• 添加请求头后，组件一直处于加载状态无法完成加载

无请求头或不设置上述参数时，图片可正常加载。

复现代码 #

CachedNetworkImage(
    imageUrl: "https://myurl.com/api/pubmedia?mediaid=${mediaurls[i]}",
    httpHeaders: {'auth': "123"},
    placeholder: (context, url) => CircularProgressIndicator(),
    errorWidget: (context, url, error) => Icon(Icons.error), 
    imageRenderMethodForWeb: ImageRenderMethodForWeb.HttpGet       
)

问题原因分析 #

1. 未设置HttpGet时请求头不传递
   Web端默认使用ImageRenderMethodForWeb.ImageElement渲染，本质是调用浏览器<img>标签加载图片。<img>标签的跨域请求不会携带自定义请求头，这是浏览器的安全限制，并非组件Bug。

2. 设置HttpGet后仅收到头键名、值丢失
   此时浏览器会先发送OPTIONS预检请求，用于询问服务器是否允许携带自定义头auth。该请求的Access-Control-Request-Headers字段仅会列出允许的头键名，不会携带值。你看到的服务器日志是预检请求的头，而非后续真正的GET请求头。

3. 组件一直加载的原因
   服务器未正确处理OPTIONS预检请求，未返回必要的CORS响应头（如Access-Control-Allow-Headers: auth、Access-Control-Allow-Origin），导致浏览器拦截了后续的GET请求，图片无法加载，组件一直处于加载状态。

解决方案 #

1. 服务器端处理OPTIONS请求
   必须返回以下CORS响应头：

   • Access-Control-Allow-Origin: 允许的前端域名（测试阶段可临时用*）
   • Access-Control-Allow-Headers: auth（需包含你要传递的所有自定义头）
   • Access-Control-Allow-Methods: GET, OPTIONS

2. 确保Web端使用HttpGet渲染方式
   保持imageRenderMethodForWeb: ImageRenderMethodForWeb.HttpGet配置，该方式通过HttpClient发起请求，支持携带自定义请求头。

3. 检查请求头键名格式
   确保httpHeaders的键名为字符串（如示例中的'auth'），避免因Dart变量未定义导致的错误。

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