# 依赖包版本更新说明

## 更新日期
2025-11-21

## 更新内容

### 主项目 (pubspec.yaml)

#### 更新前
```yaml
dependencies:
  json_annotation: ^4.8.1
  freezed_annotation: ^2.4.1

dev_dependencies:
  build_runner: ^2.4.7
  json_serializable: ^6.7.1
  retrofit_generator: ^8.0.0
  freezed: ^2.4.7
```

#### 更新后
```yaml
dependencies:
  json_annotation: ^4.9.0
  freezed_annotation: ^3.1.0

dev_dependencies:
  build_runner: ^2.10.4
  json_serializable: ^6.11.2
  retrofit_generator: ^10.2.0
  freezed: ^3.2.3
```

### Example 项目 (example/pubspec.yaml)

#### 更新前
```yaml
dependencies:
  json_annotation: ^4.9.0
  freezed_annotation: ^2.4.1

dev_dependencies:
  build_runner: ^2.4.7
  retrofit_generator: ^9.0.0
  json_serializable: ^6.7.1
  freezed: ^2.4.7
```

#### 更新后
```yaml
dependencies:
  json_annotation: ^4.9.0
  freezed_annotation: ^3.1.0

dev_dependencies:
  build_runner: ^2.10.4
  retrofit_generator: ^10.2.0
  json_serializable: ^6.11.2
  freezed: ^3.2.3
```

## 版本说明

### build_runner
- **旧版本**: 2.4.7
- **新版本**: 2.10.4
- **发布时间**: 2天前 (2025-11-19)
- **说明**: 最新稳定版本，修复了多个已知问题

### json_serializable
- **旧版本**: 6.7.1
- **新版本**: 6.11.2
- **说明**: 使用 6.11.2 而非 6.11.3，因为 6.11.3 与 freezed 3.2.3 存在 analyzer 版本冲突

### retrofit_generator
- **旧版本**: 8.0.0 / 9.0.0
- **新版本**: 10.2.0
- **发布时间**: 33小时前 (2025-11-20)
- **说明**: 最新版本，支持更多特性

### freezed
- **旧版本**: 2.4.7
- **新版本**: 3.2.3
- **发布时间**: 2个月前 (2025-09-10)
- **重要变更**: 
  - 需要 freezed_annotation 3.1.0+
  - 支持 Dart 3 的原生模式匹配
  - 建议使用 `switch` 表达式替代 `when`/`map` 方法

### freezed_annotation
- **旧版本**: 2.4.1 / 2.4.4
- **新版本**: 3.1.0
- **说明**: 必须升级到 3.x 以配合 freezed 3.x

### json_annotation
- **旧版本**: 4.8.1
- **新版本**: 4.9.0
- **说明**: 保持 4.x 版本以确保兼容性

## 版本兼容性矩阵

| 包名 | 版本 | analyzer 依赖 | 兼容性 |
|------|------|--------------|--------|
| freezed 3.2.3 | ✅ | 7.5.9 - 9.0.0 | ✅ |
| json_serializable 6.11.2 | ✅ | 8.x | ✅ |
| json_serializable 6.11.3 | ❌ | 9.0.0+ | ❌ 与 freezed 冲突 |
| build_runner 2.10.4 | ✅ | - | ✅ |
| retrofit_generator 10.2.0 | ✅ | - | ✅ |

## 解决的问题

1. **build_runner 缓存损坏**: 通过升级到最新版本解决
2. **版本冲突**: 
   - freezed 3.x 需要 freezed_annotation 3.x
   - freezed 3.2.3 与 json_serializable 6.11.3 存在 analyzer 版本冲突
   - 使用 json_serializable 6.11.2 解决冲突

## 清理步骤

如果遇到问题，执行以下清理步骤：

```bash
# 1. 清理缓存
rm -rf .dart_tool
rm -rf pubspec.lock

# 2. 重新获取依赖
flutter pub get

# 3. 清理构建文件
flutter clean

# 4. 重新运行 build_runner
flutter pub run build_runner build --delete-conflicting-outputs
```

## 注意事项

1. **Freezed 3.x 迁移**:
   - 建议使用 Dart 3 的原生 `switch` 表达式
   - 旧的 `when`/`map` 方法仍然可用，但已标记为遗留功能

2. **analyzer 版本**:
   - 当前配置使用 analyzer 8.x
   - 避免使用需要 analyzer 9.x 的包版本

3. **pub.dev 镜像**:
   - 如果使用国内镜像 (pub.flutter-io.cn)，可能需要等待同步
   - 建议使用官方源或清华镜像

## 参考链接

- [build_runner](https://pub.dev/packages/build_runner)
- [json_serializable](https://pub.dev/packages/json_serializable)
- [retrofit_generator](https://pub.dev/packages/retrofit_generator)
- [freezed](https://pub.dev/packages/freezed)