Flutter开发本地包时无法加载包内Image图片资源问题

核心错误点 #

你当前的配置存在两处不匹配，直接导致资源加载失败：

• 包自身pubspec.yaml的资源路径配置错误：packages/package_name/assets/bg.png是外部依赖项引用你包资源时的路径格式，包自身的pubspec需要填写相对于自身文件位置的本地相对路径
• Dart代码资源引用方式错误：直接写packages/开头的全路径且未指定包名参数，Flutter无法定位到包内置的资源目录

正确配置步骤 #

1. 修改包内pubspec.yaml的资源声明 #

打开本地包根目录下的pubspec.yaml，将资源路径替换为相对当前pubspec文件的本地路径，你的资源存放在lib/assets下，正确配置如下：

flutter:
  assets:
    # 单个资源写法
    - lib/assets/bg.png
    # 如果要加载整个目录的所有资源，直接写目录路径，末尾斜杠不能丢
    # - lib/assets/

注意：只有当主项目/其他依赖包要引用你这个包的资源时，才需要在它们自己的pubspec里写packages/package_name/xxx格式的路径，包自身的pubspec绝对不能用这个格式。

2. 修改Dart代码中的资源加载逻辑 #

在包内部的代码中加载自有资源，使用Image.asset时必须传入package参数指定当前包名，不需要手动拼接packages/或lib/前缀：

// 包内加载自有资源的标准写法
Image.asset(
  // 路径写lib目录之后的相对路径即可，你的资源在lib/assets下，就写assets/xxx
  'assets/bg.png',
  // 这里的包名必须和你包pubspec.yaml中name字段的值完全一致，大小写敏感
  package: 'package_name',
)

不推荐手动写全路径Image.asset('packages/package_name/assets/bg.png')的写法：该写法在配置正确时虽然能生效，但可维护性极差，一旦修改包名需要全局替换所有资源路径，漏改就会触发加载错误。

3. 清理缓存重启项目 #

配置修改完成后，执行以下命令清理构建缓存，再重新运行项目即可正常加载资源：

flutter clean
flutter pub get

避坑提示 #

• 包名必须和pubspec中name:字段的值完全一致，大小写、下划线都不能错，否则Flutter无法匹配到对应包的资源目录
• 如果要实现资源完全由包内部管理、不需要主项目额外配置，资源必须放在包的lib/目录下，不要放在包根目录的非lib目录中，否则主项目必须在自己的pubspec中声明资源路径才能加载
• 声明目录资源时，路径末尾的斜杠不能省略，否则Flutter不会递归加载目录下的所有文件

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