Flutter Rust Bridge 常见问题排查指南

Flutter Rust Bridge 常见问题排查指南

flutter_rust_bridge High-level memory-safe binding generator for Flutter/Dart <-> Rust 项目地址: https://gitcode.com/gh_mirrors/fl/flutter_rust_bridge

前言

Flutter Rust Bridge 是一个强大的工具，它允许 Flutter 应用与 Rust 代码无缝交互。但在实际开发过程中，开发者可能会遇到各种问题。本文将系统性地梳理常见问题及其解决方案，帮助开发者快速定位和解决问题。

链接器符号未定义问题

问题现象

在 iOS/macOS 平台上构建时，链接器报错提示未定义符号，例如：

ld: Undefined symbols: std::__1::basic_string ...

解决方案

修改 iOS/macOS 的 podspec 文件中的链接器标志：

'OTHER_LDFLAGS' => '-force_load ${BUILT_PRODUCTS_DIR}/librust_lib.a -lc++',

根据实际需要，可能还需要添加其他库，如：

• -framework SystemConfiguration
• -framework AudioToolbox

技术背景

这个问题通常发生在 Rust 代码使用了 C++ 标准库功能时。-lc++ 标志告诉链接器链接 C++ 标准库。对于音频处理等特定功能，则需要添加相应的框架。

GLIBC 版本问题

问题现象

在 Linux 环境下，出现类似 version GLIBC_2.33 not found 的错误。

解决方案

1. 避免使用 Flutter Snap 安装方式
2. 改用常规方式安装 Flutter

技术背景

这个问题源于 Flutter Snap 无法进行 LTO (Link Time Optimization) 构建。Snap 是 Canonical 提供的打包格式，有时会限制底层系统库的使用。

store_dart_post_cobject 符号问题

问题现象

调用 Rust 函数时出现错误：

Failed to lookup symbol 'store_dart_post_cobject': undefined symbol

解决方案

重新运行 cargo build 命令。这通常是因为生成的 Rust 文件没有被正确包含在构建过程中。

Android NDK 兼容性问题

问题现象

运行 cargo ndk 时出现错误：

ld: error: unable to find library -lgcc

解决方案

将 Android NDK 降级到版本 22。

技术背景

这是 cargo-ndk 工具与 NDK 23 版本的兼容性问题，与 Flutter Rust Bridge 本身无关。

macOS 环境下的 LLVM 路径问题

问题现象

在 macOS 上运行代码生成器时提示：

Please supply one or more path/to/llvm...

解决方案

1. 使用 Homebrew 安装 LLVM：brew install llvm
2. 指定 LLVM 路径：

flutter_rust_bridge_codegen --llvm-path /usr/local/homebrew/opt/llvm/

Freezed 文件未生成问题

问题现象

.freezed.dart 或 .g.dart 文件看起来没有更新。

解决方案

确保已经运行了 build_runner：

flutter pub run build_runner build

类型定义错误

问题现象

出现错误：Can't create typedef from non-function type.

解决方案

确保 Flutter 项目的 pubspec.yaml 中最低 SDK 版本至少为 2.17.0：

environment:
  sdk: ">=2.17.0 <3.0.0"

技术背景

这是 ffigen 工具的要求，它需要较新版本的 Dart SDK 支持。

类型名称冲突问题

问题现象

出现重复导入错误，提示从 bridge_definitions.dart 和 bridge_generated.io.dart 同时导入。

解决方案

避免在 Rust 类型名称中使用 Kind 作为后缀。

iOS TestFlight 专属问题

问题现象

应用在本地 Debug 和 Release 模式下工作正常，但在 TestFlight 上部署时出现 store_dart_post_cobject 错误。

解决方案

1. 在 Xcode 中选择 native-staticlib scheme
2. 在 Build Settings 中：
   • 将 Strip Linked Product 设为 No
   • 将 Strip Style 设为 Debugging Symbols

技术背景

这是符号剥离设置导致的问题，TestFlight 的构建过程可能会剥离必要的符号。

Web 平台特殊问题

常见问题

1. 跨域请求限制（特别是 Firefox）
2. WASM 兼容性问题

解决方案

1. 开发时使用 Chromium 浏览器测试
2. 生产环境配置 crossOriginIsolated
3. 参考 WASM 限制文档调整代码

Android 平台 C++ 库问题

问题现象

出现 Could not resolve symbol __cxa_pure_virtual 或 libc++_shared 相关问题。

解决方案

1. 在 Rust 项目的 build.rs 中添加：

fn main() {
    #[cfg(target_os = "android")]
    println!("cargo:rustc-link-lib=c++_shared");
}

2. 从 Android NDK 中复制对应的 libc++_shared.so 到各架构的 jniLibs 目录

代码生成器卡住问题

问题现象

flutter_rust_bridge_codegen 命令长时间无响应。

调试方法

使用调试日志运行：

RUST_LOG=debug flutter_rust_bridge_codegen your_args

检查卡住的子命令（如 fvm flutter pub get）并单独执行以定位问题。

总结

本文涵盖了 Flutter Rust Bridge 开发中最常见的各类问题及其解决方案。遇到问题时，建议：

1. 仔细阅读错误信息
2. 根据错误类型查找对应的解决方案
3. 必要时启用调试日志获取更多信息
4. 检查相关工具的版本兼容性

通过系统性地排查，大多数问题都能找到解决方案。对于本文未涵盖的特殊问题，建议查阅项目文档或提交详细的错误报告。

flutter_rust_bridge High-level memory-safe binding generator for Flutter/Dart <-> Rust 项目地址: https://gitcode.com/gh_mirrors/fl/flutter_rust_bridge