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 代码无缝交互。但在实际开发过程中，开发者可能会遇到各种问题。本文将系统性地梳理常见问题及其解决方案，帮助开发者快速定位和解决问题。

环境配置问题

Linux 环境下头文件缺失问题

在 Linux 系统上运行时，可能会遇到 'stdarg.h' file not found 或 stdbool.h 缺失的错误。这是因为 Rust 的 Command 在查找系统头文件时可能出现问题。

解决方案：

1. 尝试在根目录 / 下运行代码生成器
2. 或者设置环境变量：

export CPATH="$(clang -v 2>&1 | grep "Selected GCC installation" | rev | cut -d' ' -f1 | rev)/include"

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/

构建相关问题

store_dart_post_cobject 符号未定义

当调用 Rust 函数时出现 undefined symbol: store_dart_post_cobject 错误，这通常是因为生成的 Rust 文件没有被正确包含在构建过程中。

解决方案：

1. 重新运行 cargo build
2. 确保生成的 Rust 文件被正确包含在构建系统中

Android NDK 版本兼容性问题

使用 cargo ndk 构建时遇到 ld: error: unable to find library -lgcc 错误。

解决方案： 降级到 Android NDK 版本 22，这是 cargo-ndk 的一个已知问题。

代码生成问题

Freezed 文件未生成

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

解决方案： 确保已经运行了 build_runner：

flutter pub run build_runner build

类型定义冲突

如果遇到 Imported from both bridge_definitions.dart and bridge_generated.io.dart 错误，可能是因为在 Rust 中使用了 Kind 作为类型名后缀。

解决方案： 避免在 Rust 类型名称中使用 Kind 作为后缀。

平台特定问题

iOS TestFlight 符号剥离问题

在 iOS TestFlight 上运行时出现 store_dart_post_cobject 错误。

解决方案：

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

Android 上下文未初始化

在 Android 上使用某些 Rust crate 时出现 android context was not initialized 错误。

解决方案：

1. 在 MainActivity.kt 中添加：

init {
    System.loadLibrary("你的库名")
}

2. 在 Rust 中添加 JNI 初始化代码：

#[cfg(target_os = "android")]
#[no_mangle]
pub extern "C" fn JNI_OnLoad(vm: jni::JavaVM, res: *mut std::os::raw::c_void) -> jni::sys::jint {
    // 初始化代码
}

libc++_shared 问题

遇到 Could not resolve symbol __cxa_pure_virtual 错误。

解决方案：

1. 创建 build.rs 文件：

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

2. 将对应架构的 libc++_shared.so 放入 jniLibs 目录

版本要求

Dart SDK 版本

虽然 Flutter Rust Bridge 支持 Dart SDK >=2.15.0，但最新的 ffigen 工具需要 >=2.17.0。

解决方案： 在 pubspec.yaml 中指定：

environment:
  sdk: ">=2.17.0 <3.0.0"

Web 相关问题

Web 平台有其独特的限制和问题，建议参考专门的 WASM 限制文档了解常见问题和解决方案。

结语

本文涵盖了 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