Flutter Rust Bridge 升级指南：从 v1 迁移到 v2

概述

Flutter Rust Bridge 是一个强大的工具，用于在 Flutter 和 Rust 之间建立桥梁。随着项目的不断发展，v2 版本带来了许多改进和变化。本文将详细介绍如何从 v1 版本升级到 v2 版本，特别是针对代码生成命令的变更。

主要变更点

1. 命令结构变化

v1 版本直接使用 flutter_rust_bridge_codegen 命令，而 v2 版本引入了子命令结构：

# v1 版本
flutter_rust_bridge_codegen --rust-input ...

# v2 版本
flutter_rust_bridge_codegen generate --rust-input ...

2. 参数重命名

多个参数在 v2 版本中进行了重命名：

• --extra-c-output-path 改为 --duplicated-c-output
• --rust-input 的格式也发生了变化，现在需要指定 crate 路径

3. 移除的参数

v2 版本移除了以下参数：

• --dart-decl-output
• --wasm

4. 生命周期处理

v2 版本默认不启用生命周期支持，需要显式添加 --enable-lifetime 参数。

常见升级问题解决方案

文件存在错误

当遇到 "File exists (os error 17)" 错误时，通常是因为：

1. 输出目录权限问题
2. 文件被其他进程锁定
3. 路径配置不正确

解决方案：

• 检查输出目录是否存在且可写
• 确保没有其他进程正在使用目标文件
• 验证路径配置是否正确

结构体处理变化

v2 版本对空结构体的处理更加严格。对于以下情况：

struct C;
struct EntityState;
struct ProcessState;

现在需要明确指定结构体形式：

struct C {}
// 或者
#[frb(opaque)] struct C;

最佳实践建议

1. 逐步迁移：先在一个测试项目中尝试升级，验证无误后再应用到主项目
2. 版本控制：在升级前确保代码已提交，方便回滚
3. 文档参考：仔细阅读新版本文档，了解所有变更点
4. 错误处理：遇到错误时，先检查参数是否正确，再查看错误日志

总结

从 Flutter Rust Bridge v1 升级到 v2 需要关注命令结构、参数变更和功能调整。通过理解这些变化并遵循本文指南，开发者可以顺利完成升级过程，享受新版本带来的改进和性能提升。

对于更复杂的升级场景，建议参考官方文档或社区讨论，获取更多针对性的解决方案。