Flutter Flavors条件资源打包出现"Assets Must Be File Paths"错误

问题场景 #

按官方文档配置Flavors条件资源打包，希望根据free/premium等不同Flavor打包对应资源，避免包体积冗余。但配置后出现两个问题：

1. Lint工具提示YAML错误：Assets are required to be file paths (strings). Try converting the value to be a string.
2. 带着警告运行时，出现资源找不到错误：

   ════════ Exception caught by image resource service ════════════════════════════
   The following assertion was thrown resolving an image codec:
   Unable to load asset: "/assets/premium/test.png".
   Exception: Asset not found
   

使用的pubspec.yaml配置：

flutter:
  assets:
    - assets/common/
    - path: assets/free/
      flavors:
        - free
    - path: assets/premium/
      flavors:
        - premium

Flavor环境变量配置代码：

const String? appFlavor = String.fromEnvironment('FLUTTER_APP_FLAVOR') != '' ? String.fromEnvironment('FLUTTER_APP_FLAVOR') : null;

print('appFlavor: $appFlavor');

原因分析 #

1. Flutter版本兼容性：Flavored Assets功能是Flutter 3.7.0及以上版本才正式支持的特性，旧版本Flutter或Lint工具无法识别这种配置格式，导致抛出警告。
2. 资源路径错误：加载资源时路径开头多加了斜杠，Flutter的asset路径不需要以/开头，否则会导致路径解析错误。
3. Lint工具未更新：即使Flutter版本达标，旧版的dart lint规则可能还未适配Flavored Assets的配置语法，导致误报警告。

解决方案 #

1. 确认Flutter版本 #

运行以下命令检查版本，确保≥3.7.0：

flutter --version

如果版本过低，执行升级：

flutter upgrade

2. 修正资源加载路径 #

将代码中的资源路径开头的斜杠移除，比如：

// 错误写法
Image.asset("/assets/premium/test.png")

// 正确写法
Image.asset("assets/premium/test.png")

3. 处理Lint警告 #

• 升级lint依赖：如果使用了lint或flutter_lints包，在pubspec.yaml中更新到最新版本：

  dev_dependencies:
    flutter_lints: ^2.0.0 # 或更高版本
  

• 暂时忽略警告：如果升级后仍有警告，可在analysis_options.yaml中添加规则忽略：

  linter:
    rules:
      - avoid_unused_constructor_parameters: false # 替换为对应警告的规则名，或直接忽略该类错误
  

  注：实际配置中可根据Lint提示的具体规则名进行针对性忽略，确保不影响其他代码检查。

4. 确保Flavor环境变量正确传入 #

运行应用时必须明确指定Flavor环境变量，例如：

# 运行free版本
flutter run --dart-define=FLUTTER_APP_FLAVOR=free

# 运行premium版本
flutter run --dart-define=FLUTTER_APP_FLAVOR=premium

验证步骤 #

1. 执行flutter clean清理构建缓存，避免旧资源残留。
2. 重新运行对应Flavor的应用，检查资源是否正常加载。
3. 打包后验证包内资源：例如针对Android，解压apk后查看assets目录，确认仅包含对应Flavor的资源文件夹。

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