Flutter使用Retrofit更新依赖后@Multipart、@Part注解未定义问题咨询

安全阿岳

2026-11-1

报错根源

这类升级依赖后触发的未定义注解报错，核心是三个版本迭代带来的兼容断层：

注解拼写兼容逻辑移除：代码中写的@MultiPart()存在大小写偏差，正确的注解类名是Multipart（中间的p为小写）。旧版本Retrofit的代码生成阶段对注解拼写的校验比较宽松，哪怕拼写不匹配也能自动路由到Multipart请求的生成逻辑，不会在编译期抛错；新版本收紧了编译期的类型检查，只要注解名称和已定义类名对不上，就会直接报未定义引用。
注解导出规则调整：Retrofit 4.0 及以上版本对原有顶层导出的注解做了拆分，Multipart、Part、PartFile这三类Multipart请求相关的注解，不再默认从retrofit.dart的公共导出入口暴露，漏写对应导入语句就会直接触发未定义名称的编译错误。
参数适配规则废弃：旧版本中直接用普通@Part标注File类型参数的写法，在新版本中已经被标记为不合法参数类型，哪怕注解导入完全正确，也会在代码生成阶段抛出类型不匹配的问题。

新版本适配的Multipart请求实现方案

先完成基础配置修正
- 检查导入语句：在定义接口的文件头部，确保正确引入Retrofit的公共导出包，不需要额外引入框架的私有内部路径：
```
import 'package:retrofit/retrofit.dart';
```
- 校验依赖版本匹配：确保retrofit和retrofit_generator两个依赖的大版本号完全一致，避免出现高版本注解搭配低版本代码生成器的错配问题。

调整接口注解与参数写法
修正拼写错误，同时将文件类型的参数替换为专门的PartFile注解标注，替换后的可运行代码如下：

@RestApi()
abstract class ProfileApi {
  @POST(EditProfile)
  @Multipart() // 修正拼写：移除大写P的偏差
  Future<LoginResponse> editProfile(
    @Part(name: 'name') String name,
    @Part(name: 'email') String email,
    // 本地文件参数改用@PartFile标注，不再使用普通@Part
    @PartFile(name: 'image') File image,
  );
}

触发代码重新生成
写完修改后，必须执行带清理参数的代码生成命令，避免旧的缓存生成文件残留导致报错持续：
```
flutter pub run build_runner build --delete-conflicting-outputs
```

补充注意事项

如果需要上传非本地文件的内容，比如内存中的字节流，可以直接给@PartFile传入MultipartFile类型的参数，不需要手动做文件格式转换。
部分官方文档的示例没有同步更新旧写法的废弃规则，所以直接检索Multipart相关内容时，很难找到最新的适配写法，按照当前的注解规则调整即可正常运行。
不要为了兼容旧写法刻意降级Retrofit版本，新版本对Multipart文件上传的压缩、分片处理逻辑做了优化，稳定性更好。

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