根本原因是vscode图形界面启动未继承动态库路径：macos/linux需终端执行code .启动以继承ld_library_path，windows需将库目录加入系统path并在launch.json中显式配置env字段。
rustc/cargo 找不到 libxxx.so 或 xxx.dll
根本不是 Rust 代码写错了，而是 VSCode 启动时没继承你的动态库搜索路径。图形界面双击打开的 VSCode 不加载 ~/.zshrc（macOS/Linux）或系统 PATH 中的用户级路径（Windows），所以即使终端里 cargo run 成功，F5 调试就报 error while loading shared libraries: libxxx.so: cannot open shared object file。
解决方法只有两个：
- macOS/Linux：关掉所有 VSCode 窗口，从终端进入项目根目录，执行
code .—— 它会完整继承当前 shell 的LD_LIBRARY_PATH和PATH - Windows：把动态库所在目录（如
C:mylibin）加进**系统级**环境变量PATH，不能只设在 CMD 或 PowerShell 里；验证方式是重启 VSCode 后，在内置终端运行echo %PATH%，确认输出含该路径
cargo build 链接时报 cannot find -lxxx
这说明编译阶段找不到库文件，常见原因不是配置漏了，而是路径或命名不匹配。
检查要点：
-
ls -l /path/to/lib/libxxx.so必须能列出文件；如果只有libxxx.a，链接时得加-static，否则-lxxx默认找动态库 -
-lxxx对应的是libxxx.so，不是xxx.so或libxxx.so.2；若版本后缀存在（如libxxx.so.2），需用ln -s libxxx.so.2 libxxx.so创建软链 -
CGO_LDFLAGS="-L/path/to/lib -lxxx"中的路径不能含空格或中文；CGO_LDFLAGS不支持引号包裹，遇到空格就截断
运行时报 undefined symbol: xxx_function
动态库找到了，但某个 C 函数在运行时解析失败 —— 这是 ABI 层问题，不是编译错误。
分三步排查：
- 用
ldd ./target/debug/your_binary看是否所有依赖都 resolve 到真实路径；某行显示not found，说明它依赖的另一个库没被LD_LIBRARY_PATH覆盖到 - 用
nm -D /path/to/libxxx.so | grep xxx_function确认符号确实导出；没结果，说明该库编译时漏了-fPIC，或函数声明没加extern "C"导出修饰 - 检查 Rust FFI 声明是否与 C 头文件一致：函数签名、调用约定（
extern "C"）、参数类型（如c_intvsi32）必须严格匹配
VSCode 内置终端里 cargo run 成功，但 F5 调试失败
调试器（lldb 或 gdb）启动时环境变量是独立继承的，不会自动复用你终端里设置的 LD_LIBRARY_PATH。
必须显式配置：
- 在项目根目录下创建
.vscode/launch.json - 在
configurations里补上"env": {"LD_LIBRARY_PATH": "/path/to/lib"}（Linux/macOS）或"env": {"PATH": "C:\mylib\bin;%PATH%"}（Windows） - 注意：Windows 上不要用
LD_LIBRARY_PATH，那是 Linux/macOS 专用；Windows 下 DLL 搜索路径由PATH决定
最常被忽略的一点：launch.json 里的 env 只影响调试进程，不影响 cargo check 或 IntelliSense —— 它们走的是 rust-analyzer 的独立环境，仍需靠 code . 启动来继承 shell 变量。
