Flutter中Image.asset加载图片失败：无法找到指定资源

架构老林

2026-7-3

Flutter本地图片加载失败（Asset not found）排查方案

以下是针对Unable to load asset报错的精准排查步骤：

严格校验pubspec.yaml格式
Flutter的YAML配置对缩进和格式要求极高，确保assets节点的层级正确，示例如下：
```
flutter:
  uses-material-design: true
  assets:
    - assets/icons/instagram.png
    # 若需加载整个文件夹下的资源，可写为：- assets/icons/
```
注意：冒号后必须加空格，路径不要加引号，缩进用2个空格（不要用Tab）。
匹配路径与文件名的大小写
Flutter的资源路径区分大小写，比如文件名是Instagram.png，代码里写instagram.png会直接找不到，需完全匹配文件名的大小写。
确认文件实际位置
检查项目根目录下是否存在assets/icons/instagram.png，不要把assets文件夹放在lib目录下，必须放在项目根目录（和pubspec.yaml同级）。
清理缓存并重启项目
缓存可能导致配置修改不生效，执行以下命令：
```
flutter clean
flutter pub get
```
之后完全关闭模拟器/真机和Flutter运行服务，重新启动项目。
检查代码中的路径格式
确保代码里的路径没有多余空格，使用英文引号，示例：
```
Image.asset(
  'assets/icons/instagram.png',
  color: Color.fromRGBO(16, 42, 67, 1),
)
```
尝试文件夹级别的资源引用
如果单张图片配置无效，可在pubspec.yaml中引用整个icons文件夹：
```
assets:
  - assets/icons/
```
代码中仍使用原路径加载图片，Flutter会自动扫描该文件夹下的所有资源。
验证图片文件完整性
用图片查看器打开instagram.png，确认文件未损坏，且格式为Flutter支持的类型（png、jpg、webp等）。