Coil Compose AsyncImage无法加载TMDB API图片问题排查

核心原因及解决方案 #

• HTTP明文请求被Android限制
  Android 9（API 28）及以上版本默认禁止明文HTTP请求，你使用的TMDB图片URL是http协议，而浏览器、Postman没有这个限制，导致Coil无法加载。
  最快的解决方式是将URL换成HTTPS版本：

  SubcomposeAsyncImage(
      model = "https://image.tmdb.org/t/p/w500/Af4bXE63pVsb2FtbW8uYIyPBadD.jpg",
      contentDescription = "image",
      modifier = Modifier
          .fillMaxWidth(0.25f)
          .fillMaxHeight(),
      contentScale = ContentScale.Crop,
      loading = { CircularProgressIndicator() }
  )
  

  TMDB完全支持HTTPS协议，这是最安全且简便的方案。

• 若必须使用HTTP（不推荐）
  可以通过配置网络安全策略允许特定域名的明文请求：

  1. 在res/xml目录下创建network_security_config.xml：

     <?xml version="1.0" encoding="utf-8"?>
     <network-security-config>
         <domain-config cleartextTrafficPermitted="true">
             <domain includeSubdomains="true">image.tmdb.org</domain>
         </domain-config>
     </network-security-config>
     

  2. 在AndroidManifest.xml的application标签中添加配置：

     <application
         ...
         android:networkSecurityConfig="@xml/network_security_config">
     

• 排查Coil版本与错误细节

  1. 确保使用最新稳定版Coil，旧版本可能存在兼容问题：

     implementation("io.coil-kt:coil-compose:2.5.0") // 替换为最新版本
     

  2. 添加错误回调获取具体失败原因：

     SubcomposeAsyncImage(
         ...
         error = { errorState ->
             Text(text = "加载失败: ${errorState.result.throwable.message}")
         }
     )
     

     根据错误信息可以进一步定位SSL异常、网络权限等问题。

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