企业官网建设流程全解析

你写了不少 Rust 代码，多少都会碰到extern "C"这个关键字。我第一次见它是在试着把 Rust 编译成动态库给别的语言调用时，当时只照着文档抄，抄完能跑，但完全不明白为什么要写这一句。直到后来遇到一个莫名其妙的崩溃，排查了半天才发现是调用约定对不上。这篇文章就围绕extern "C"把 ABI、类型映射、内存安全、链接器行为这些底层逻辑一次讲透，适合对 FFI 有基础了解但想深入理解原理的读者，也适合准备用 Rust 做跨语言模块的人。

1. extern "C" 到底在声明什么：从一次跨语言调用的困惑说起

先说一个我真实踩过的坑。当时我用 Rust 编译了一个静态库，然后在 C++ 工程里链接调用。函数声明得很正常：

extern int add(int a, int b);

Rust 那边写的是：

#[no_mangle] pub extern "C" fn add(a: i32, b: i32) -> i32 { a + b }

编译、链接、运行，一切正常。我当时以为extern "C"只是“声明这是个 C 函数”的意思，直到某天我把一个函数签名从fn process(data: *mut u8, len: usize)改成了fn process(data: *mut u8, len: i32)，结果在 C 侧传了一个超过 2 的 31 次方的长度值，函数直接拿到了错误的长度，内存越界读，程序崩溃。

排查了很久，最后发现问题的根源不是类型本身，而是调用约定。

1.1 从 ABI 说起：函数调用背后的约定

ABI（Application Binary Interface）这个词听起来很高端，说白了就是二进制层面的一套规矩。它包括参数怎么传（寄存器还是栈）、返回值放哪里、栈由谁清理、结构体怎么对齐、符号怎么命名等等。CPU 只是个执行机器，它不关心你调用的函数叫add还是add_rs，它只关心调用指令执行后，参数是否出现在它期望的位置。

不同语言、不同编译器对“参数放在哪里”有不同的习惯。比如在 x86-64 平台上，C 语言的调用约定是 System V AMD64：前六个整数参数依次放在rdi、rsi、rdx、rcx、r8、r9寄存器里，多余的参数才压栈。而 Rust 默认的调用约定是它自己定义的，不完全等同于 C 的约定，甚至在整数参数传递上也有自己的优化规则。

如果你用 Rust 默认约定写了一个函数，然后在 C 侧用 C 的约定去调用，双方对“参数应该放在哪个寄存器”的理解不一致，函数拿到的参数就是乱的。这就是我当时那个崩溃的深层原因——不是类型错了，而是调用约定错位。

1.2 "C" 不是指 C 语言，而是 C ABI

extern "C"里的"C"指的是C 语言定义的 ABI 规范，不是说要跟 C 语言有什么绑定关系。只要你愿意，完全可以在 Rust 里用extern "C"声明一个函数，然后在 Go、Python、C++、Zig 等其他语言里调用它，只要那个语言也遵循 C ABI。

C ABI 之所以成为事实标准，是因为几乎所有主流语言都提供了与 C 交互的能力，而 C 的 ABI 是其中最稳定、最广泛支持的二进制接口。你调用操作系统 API（比如 Windows 的Win32API）、调用数据库客户端库、调用加密库，本质上都是通过 C ABI 完成的。

用一句话概括：extern "C"就是在告诉 Rust 编译器——“这个函数的二进制交互方式，请按照 C ABI 来安排”。

1.3 Rust 中的两种 extern 用法：声明与定义

很多人会把extern "C"跟extern crate混淆，其实完全是两码事。extern crate是 Rust 2018 之前的模块导入语法，现在已经很少手写了；而extern "C"是 FFI 相关的关键字。在 Rust 里它有两种用法：

第一种，声明外部函数——告诉编译器“这个函数存在于某个外部库中，签名长这样”：

extern "C" { fn strlen(s: *const c_char) -> usize; }

第二种，定义导出函数——把 Rust 函数编译成符合 C ABI 的符号，供外部语言调用：

#[no_mangle] pub extern "C" fn my_exported_function(x: i32) -> i32 { x * 2 }

这两种用法看似方向相反，但都指向同一个底层事实：Rust 编译器需要知道函数在二进制层面的交互规则。

2. 声明与导出：一个关键字的两幅面孔

这一节我们把两种用法分别拆开看，每个都给出完整可运行的示例，并解释背后的编译器行为。

2.1 在 Rust 中声明 C 函数：extern 块的作用

在 Rust 中调用 C 函数，第一步是写一个extern块。这里有几个关键点需要说清楚。

第一，extern块内部的函数默认是 unsafe 的。原因是 Rust 无法验证外部函数的行为是否符合 Rust 的安全假设。比如它可能会解引用空指针、可能返回无效数据、可能破坏栈。所以在 Rust 2015 中调用extern块内的函数直接就是 unsafe；在 Rust 2021 及以后，extern块本身需要标记为unsafe：

unsafe extern "C" { fn malloc(size: usize) -> *mut c_void; fn free(ptr: *mut c_void); fn printf(format: *const c_char, ...) -> i32; }

关于这个变化，有一个实用的迁移建议：如果你的项目还停留在 Rust 2018 或者更早版本，并且extern块没有标unsafe，升级到 2021 之后编译器会提示你把extern改成unsafe extern。我建议一开始就写成unsafe extern，因为这样更清楚地表达了“外部代码不受到 Rust 安全性保证”这个事实。

第二，extern块内只写函数签名，不写函数体。链接器在最终链接阶段会把符号解析到实际的库或者目标文件里。这里的“链接”是二进制层面的连接，和你是不是用 C 编译器生成的.o文件没有必然关系，只要最终符号对齐即可。

第三，如何在链接层面上找到这些函数。常用的方式是配合#[link(name = "xxx")]属性告诉链接器去链接某个库：

#[link(name = "m")] unsafe extern "C" { fn sqrt(x: f64) -> f64; }

这个例子链接的是数学库libm。在 Linux 上，sqrt的实现在libm.so里；在 Windows 上，可能就在系统 DLL 里。#[link]属性是平台相关的，跨平台工程建议用构建系统的links配置或build.rs来处理更复杂的链接需求。

2.2 把 Rust 函数暴露给 C 侧：#[no_mangle] 与 pub extern

反过来，当你希望 Rust 函数能够被 C 代码调用时，需要做三件事：

• 给函数加pub可见性
• 标记extern "C"以采用 C ABI
• 加#[no_mangle]关闭 Rust 的名称修饰

前两点前面都说了，重点讲#[no_mangle]。

Rust 编译器默认会对函数符号做名称修饰（name mangling），也就是把函数名加上模块路径、类型信息等编码，变成一个类似_ZN4test3add17h3b7b3b1c0d3b7b3bE的符号。这个符号人类看不懂，C 侧也无法直接通过add这个名字找到它。#[no_mangle]的意思就是告诉编译器：“别修饰，直接用函数名作为符号名。”

这里有一个我见过无数人踩的坑：#[no_mangle]和extern "C"是两个独立属性，#[no_mangle]管的是符号名，extern "C"管的是调用约定。只加#[no_mangle]不加extern "C"，符号名对了但调用约定还是 Rust 默认的，C 侧调用依然会出错。只加extern "C"不加#[no_mangle]，调用约定对了但符号名被修饰，C 侧链接失败。两者必须同时使用，缺一不可。

完整的最小导出示例：

#[no_mangle] pub extern "C" fn add_i32(a: i32, b: i32) -> i32 { a + b }

编译成动态库：

rustc --crate-type cdylib add.rs

注意cdylib这个 crate 类型，它表示“编译成供其他语言调用的动态库”。和dylib的区别在于，cdylib会尽量少暴露 Rust 内部符号，只保留你标记导出的符号，产物体积更小，也更干净。

2.3 一个最小的完整示例：Rust 静态库 + C 主程序

下面是一个可以完整跑通的最小示例。先看 Rust 侧，我们写三个导出函数：

// math.rs #[no_mangle] pub extern "C" fn add_f64(a: f64, b: f64) -> f64 { a + b } #[no_mangle] pub extern "C" fn mul_f64(a: f64, b: f64) -> f64 { a * b } #[no_mangle] pub extern "C" fn greet(name: *const u8, len: usize) -> i32 { if name.is_null() { return -1; } let slice = unsafe { std::slice::from_raw_parts(name, len) }; match std::str::from_utf8(slice) { Ok(s) => { println!("Hello, {}!", s); 0 } Err(_) => -2, } }

编译成静态库：

rustc --crate-type staticlib math.rs -o libmath.a

然后写 C 侧程序：

// main.c #include <stdio.h> #include <stdint.h> extern double add_f64(double a, double b); extern double mul_f64(double a, double b); extern int32_t greet(const uint8_t *name, size_t len); int main() { printf("add: %f\n", add_f64(2.5, 3.7)); printf("mul: %f\n", mul_f64(2.5, 3.7)); const char *name = "world"; int result = greet((const uint8_t *)name, 5); printf("greet result: %d\n", result); return 0; }

编译并链接：

gcc main.c -L. -lmath -o demo ./demo

能看到类似输出：

add: 6.200000 mul: 9.250000 Hello, world! greet result: 0

这个例子别看简单，它已经包含了字节指针传参、长度传参、Rust 侧解析 UTF-8 字符串这些典型模式。greet函数接收的不是char*，而是const uint8_t*和长度，这种“指针 + 长度”的组合是 FFI 里最安全的字符串传递方式，后面会详细讲为什么。

3. 类型与内存：穿过 FFI 边界的数据如何存活

调用约定解决的是“参数怎么传”，但参数本身是什么、怎么构造、谁来释放，是另一组完全独立的难题。这一节重点讨论跨 FFI 边界时类型和内存的映射关系。

3.1 基础类型映射：i32、f64 就够了吗？

在 x86-64 平台上，Rust 的基础类型和 C 的对应关系如下：

注意，i32对应 C 的int，这里有一个常见的误区：C 标准并没有规定int一定是 32 位，在有些嵌入式平台上int是 16 位，在少数古老平台上甚至可能不同。不过在现代主流桌面、服务器和移动平台上，int基本都是 32 位。如果追求绝对严谨，在头文件里使用stdint.h定义的类型（int32_t、uint64_t之类），才是跨平台最稳妥的做法。

bool类型要特别小心。Rust 的bool是一个字节，值只能是 0 或 1；而 C 的bool（_Bool）虽然也是一字节，但某些老代码会用int作为布尔返回值，这种约定差异容易产生隐患。我的建议是：FFI 边界上尽量避免使用布尔类型，用i32作为状态码（0 表示成功，非 0 表示各种错误），这个模式在 C 的世界里非常普遍，也少了很多歧义。

3.2 指针、引用与所有权：谁拥有这块内存

跨 FFI 传递指针是不可避免的，但指针一来一回，问题就复杂了。核心问题是：这块内存归谁管？

先看一个我实际用过的模式。假设 C 侧想要 Rust 帮忙处理一块数据，Rust 侧返回一个处理结果：

#[no_mangle] pub extern "C" fn sum_slice(data: *const i32, len: usize) -> i32 { if data.is_null() { return 0; } let slice = unsafe { std::slice::from_raw_parts(data, len) }; slice.iter().sum() }

这个函数接收一个i32数组的指针和长度，求和并返回。关键点是，Rust 侧只是借用了这块内存，没有拥有它，所以函数结束后不会去释放它。这是正确的方式。

但如果 Rust 侧分配了内存并把指针传回给 C 侧，事情就变得微妙了：

#[no_mangle] pub extern "C" fn create_buffer(size: usize) -> *mut u8 { let buf = vec![0u8; size]; // 泄漏掉 Vec 的缓冲区，把裸指针传出去 let ptr = buf.as_mut_ptr(); std::mem::forget(buf); ptr }

这里std::mem::forget阻止了Vec在函数结束时被析构，从而让底层缓冲区“存活”下来，可以把裸指针传给 C 侧。但这只是完成了一半，C 侧用完这块内存之后，谁来释放？

如果是 Rust 分配的内存，就应该由 Rust 来释放，所以你需要同时导出一个释放函数：

#[no_mangle] pub extern "C" fn free_buffer(ptr: *mut u8, capacity: usize) { if ptr.is_null() { return; } // 用 capacity 和 1 重新构造 Vec，触发析构释放内存 unsafe { let _ = Vec::from_raw_parts(ptr, 0, capacity); } }

这里有个细节：Vec::from_raw_parts需要三个参数——指针、长度、容量。我们需要把 capacity 也传给释放函数，否则无法安全地重建Vec。

如果你嫌这个模式繁琐，更简单的办法是：Rust 侧分配内存后，直接让 C 侧调用标准库的free来释放。但要满足一个前提：Rust 的内存分配器和 C 的free必须来自同一个分配器。在大多数桌面平台上，Rust 默认使用系统的 malloc/free，所以这个方案可行；但在某些场景（比如 Windows 上使用不同的 CRT 库），两个分配器可能不一致，就会导致崩溃。最稳妥的方案是谁分配，谁释放——无论哪一边，都要遵守这个原则。

3.3 字符串在边界两侧的真实姿态

字符串是 FFI 里最容易出错的类型。C 的字符串是char*，以 null 结尾；Rust 的String和&str则包含显式的长度字段。直接把 Rust 的String转成char*传出去，有两个问题：一是字符串可能包含内部 null 字节，C 侧读到 null 就停了；二是String的缓冲区不保证以 null 结尾，C 侧用strlen会越界读取。

我推荐的安全字符串传参方式是“指针 + 长度”，上面的greet例子已经展示了。接收 C 传入的字符串时，我们先用from_raw_parts构造字节切片，再用from_utf8尝试解析成 UTF-8：

unsafe extern "C" { fn some_c_function(name: *const u8, len: usize); }

之所以要传长度，是因为 FFI 参数传递时，Rust 侧并没有一个可靠的方法去推断 C 侧缓冲区到底有多长。如果 C 侧传一个以 null 结尾的字符串，Rust 侧可以用CStr来处理：

use std::ffi::CStr; use std::os::raw::c_char; #[no_mangle] pub extern "C" fn handle_c_string(ptr: *const c_char) -> i32 { if ptr.is_null() { return -1; } let c_str = unsafe { CStr::from_ptr(ptr) }; match c_str.to_str() { Ok(s) => { println!("received: {}", s); 0 } Err(_) => -2, } }

反过来，如果 Rust 要返回字符串给 C 侧，返回String类型是不行的。Rust 返回String会把所有权转移到调用者，但 C 侧根本不知道如何正确析构一个String。正确做法是返回一个以 null 结尾的 C 字符串指针，并且提供配套的释放函数：

use std::ffi::CString; use std::os::raw::c_char; #[no_mangle] pub extern "C" fn get_message() -> *mut c_char { let msg = CString::new("hello from rust").unwrap(); msg.into_raw() // 返回裸指针，所有权转移给调用者 } #[no_mangle] pub extern "C" fn free_message(ptr: *mut c_char) { if ptr.is_null() { return; } unsafe { // 用 CString::from_raw 回收所有权，触发析构 drop(CString::from_raw(ptr)); } }

CString::into_raw会“泄漏”字符串并返回裸指针，相当于把所有权交出去；CString::from_raw则重新拿回所有权并触发析构。这一对方法是完整的“Rust 分配、Rust 释放”闭环。

4. 实战中躲不开的坑：链接器、命名修饰与布局对齐

很多 FFI 问题不是在编译阶段暴露的，而是在链接或者运行时才出现。这一节整理我在实际项目中遇到的几个高频问题，希望帮你节省排查时间。

4.1 链接器报错：undefined reference 的排查链路

用 Rust 编译静态库给 C 链接时，我最常碰到的错误是undefined reference to 'xxx'。这个错误的本意是：链接器在整个符号表中找不到xxx的定义。常见原因有四种：

第一，Rust 函数没有#[no_mangle]。就像前面说的，函数符号被修饰成了别的名字，C 侧用原名找不到。解决办法是在 Rust 侧加#[no_mangle]后用nm工具确认符号名：

nm libmath.a | grep add

正常会看到类似T add_f64的符号，如果看到_ZN...开头的一串乱码，那多半就是没加#[no_mangle]。

第二，函数不是pub。Rust 默认的可见性是私有，即使你加了#[no_mangle]，如果模块内部的函数不是pub，它也不会被导出到最终产物里。这个坑我踩过一次，代码里函数签名单独看不觉得有问题，一链接就报错。

第三，crate 类型不对。如果你编译的是bin而不是staticlib/cdylib，生成的产物里不会导出你想要的外部符号。更常见的是，你编译成了rlib——Rust 内部用的库格式，C 链接器根本不认识。检查一下编译命令，确认--crate-type staticlib或--crate-type cdylib。

第四，C 侧声明与 Rust 侧签名不一致。比如 C 侧声明add_f64(double, double)，Rust 侧定义add_f64(usize, usize)，链接器只看符号名，不看参数类型，所以链接会成功，运行时结果就是错的。这种问题比链接失败更危险，因为它不报错，只有跑到那一步才会出现诡异数据。

我常用的排查命令组合是：

nm -C libmath.a | grep add_f64 # 看符号名是否带修饰 file libmath.a # 确认库格式 readelf -s libmath.a | grep add_f64 # 看符号表详情

4.2 结构体布局不可靠：repr(C) 为什么是必须的

Rust 结构体的默认内存布局是不稳定的，编译器为了优化字段顺序、内存对齐，可能对结构体内部字段重新排列。这在 Rust 单侧使用没问题，但一旦要从 C 侧访问一个 Rust 结构体，C 代码是按声明顺序假设字段偏移的，两边一旦不一致，就是灾难。

解决方案是加#[repr(C)]：

#[repr(C)] pub struct Point { pub x: f64, pub y: f64, }

#[repr(C)]告诉 Rust 编译器：按照 C 语言的内存布局规则来安排结构体字段。这有几个含义：

• 字段顺序和声明顺序一致
• 字段对齐方式遵循 C 的规则
• 结构体整体大小由 C 的 padding 规则决定

我遇到过的一个真实案例：一个坐标结构体在 Rust 里定义成(f64, f64)，没有加repr(C)，Rust 侧测试一切正常。但 C 侧用联合体去解析这块内存时，第二个字段的偏移对不上，导致所有坐标值都是错的。加上#[repr(C)]之后问题消失。

另一个需要留意的点是#[repr(C)]与枚举的配合。Rust 的默认枚举是一个 tag + payload 的复杂结构，而 C 的枚举只是int。如果要在 FFI 边界上传枚举值，推荐用#[repr(u8)]或#[repr(i32)]显式指定底层的整数类型：

#[repr(u8)] pub enum Color { Red = 0, Green = 1, Blue = 2, }

这样Color::Red在二进制层面就是一个u8值 0，C 侧可以直接用整数接收。需要强调：不要对 FFI 枚举依赖 Rust 的as转换之外的任何自动行为，显式指定判别值永远是对的。

4.3 对齐问题的一个实战教训

还有一个跟结构体相关的坑：复合类型传参时，C 侧会假设结构体是按某种对齐规则打包的。如果你定义了一个包含u8和u64的结构体：

#[repr(C)] pub struct Mixed { pub a: u8, pub b: u64, }

C 语言里这种结构体的大小是 16 字节，因为b需要 8 字节对齐，a后面会补齐 7 个字节。Rust 加#[repr(C)]之后也会遵循同样的填充规则，所以两边一致。

但如果你的 Rust 侧用了#[repr(packed)]来消除填充，C 侧就必须在结构体上显式加上#pragma pack(push, 1)，否则两边布局又对不上。这种 packed 结构体在嵌入式场景很常见，建议在 FFI 头文件里用static_assert或运行时校验去兜底：

_Static_assert(sizeof(Mixed) == 16, "Layout mismatch");

双方各加一个断言，布局问题在编译/测试阶段就能暴露出来，不用等运行时数据全错。

5. 让 C 调用 Rust 闭包：函数指针与回调的进阶玩法

基础 FFI 能解决 80% 的问题，但有些场景需要反方向的调用——Rust 调用 C 库，C 库又回调 Rust 的函数。典型的场景包括：C 库的日志回调、事件通知、迭代器接口等。这一节讲的是如何安全地处理这类双向交互。

5.1 函数指针作为参数：C 侧回调 Rust

假设 C 库提供了这样一个接口，用于注册一个回调函数：

typedef void (*callback_t)(int event_id, void *user_data); void register_callback(callback_t cb, void *user_data);

Rust 侧需要定义一个匹配 C 函数指针签名的函数，然后传给 C 库：

unsafe extern "C" { fn register_callback(cb: Option<extern "C" fn(i32, *mut c_void)>, user_data: *mut c_void); } extern "C" fn on_event(event_id: i32, user_data: *mut c_void) { println!("event: {}", event_id); // 这里可以通过 user_data 访问上下文 } // 注册回调 fn main() { unsafe { register_callback(Some(on_event), std::ptr::null_mut()); } }

这里有几个值得注意的点。Option<extern "C" fn(...)>在 ABI 层面和“函数指针可以为 null”的 C 语义兼容——None对应 NULL，Some(f)对应函数指针。这比直接传裸函数指针安全得多，因为 Rust 编译器会强制你处理“可能为 null”的情况。

第二个点：extern "C" fn和普通fn是不同的类型。普通fn在 Rust 中通常是函数指针，但它的 ABI 是 Rust 默认的，不能直接传给 C。你需要显式用extern "C" fn声明回调函数的签名。

5.2 在回调中安全携带 Rust 数据：user_data 的正确用法

C 回调接口通常提供一个void *user_data参数，目的就是让你传递一个上下文指针给回调函数。在 Rust 里，user_data最常见的用法是把一个Box<T>转换成一个裸指针传过去，然后再在回调里转换回来。

注册时：

struct Context { counter: u32, prefix: String, } let ctx = Box::new(Context { counter: 0, prefix: "rust".to_string(), }); // Box 转换成裸指针，'static 生命周期 let raw = Box::into_raw(ctx) as *mut c_void; unsafe { register_callback(Some(on_event_ctx), raw); }

回调时：

extern "C" fn on_event_ctx(event_id: i32, user_data: *mut c_void) { if user_data.is_null() { return; } // 将裸指针转回 Box 的引用，注意这里用的是 &mut，不是把所有权拿回来 let ctx = unsafe { &mut *(user_data as *mut Context) }; ctx.counter += 1; println!("{} event {}", ctx.prefix, event_id); }

关键点：这里只是临时借用了Box里的数据，没有把 Box 拿回来，所以回调函数结束后，Context的内存依然由 Box 持有，不会发生重复释放。

注销回调时再拿回所有权：

unsafe { // 如果 C 库提供了注销接口，先调用注销 // unregister_callback(); drop(Box::from_raw(raw as *mut Context)); }

如果 C 库不提供注销接口，还存在一个隐患：库可能在内部持有你的 user_data 指针，如果你直接 drop 了 Box，库后续回调就会访问已释放的内存。遇到这种情况，你只能选择“永远不释放”或者“在程序退出前最后处理”，但我的建议是：第一优先是找一个提供注销接口的库；实在没有，就考虑用全局生命周期管理器来持有 Box，让它在整个程序生命周期内有效。

5.3 回调中的 panic 是致命错误：跨 FFI 边界不允许 unwind

这是 FFI 里特别容易被忽略的规则：Rust 的 panic 不能跨过extern "C"边界。你写一个extern "C" fn，里面如果触发了 panic，按默认设置，Rust 会尝试 unwinding 栈，但 C 编译器生成的目标代码并不理解 Rust 的 unwinding 机制，结果就是进程直接 abort，或者更糟——未定义行为。

一个最典型的错误写法：

#[no_mangle] pub extern "C" fn process(data: *const u8, len: usize) -> i32 { // 这里如果 from_utf8 失败，unwrap 会 panic let s = std::str::from_utf8(unsafe { std::slice::from_raw_parts(data, len) }).unwrap(); handle(s); 0 }

如果传入的字节不是合法 UTF-8，unwrap就会 panic，panic 穿过 extern "C" 边界，整个进程基本就崩了。

正确的做法是：在extern "C"函数内部捕获所有可能的 panic。从 Rust 1.71 开始，extern "C"默认行为是 panic 时调用 abort，不会尝试 unwind。但这仍然不是一个理想状态——调用方会看到进程突然退出。更稳妥的方案是手动包一层：

use std::panic::{catch_unwind, AssertUnwindSafe}; #[no_mangle] pub extern "C" fn process(data: *const u8, len: usize) -> i32 { let result = catch_unwind(AssertUnwindSafe(|| { let slice = unsafe { std::slice::from_raw_parts(data, len) }; let s = std::str::from_utf8(slice)?; handle(s) })); match result { Ok(Ok(code)) => code, Ok(Err(_)) => -2, // UTF-8 错误 Err(_) => -1, // panic 发生了 } }

抑制 panic 的另一种通用手段是在编译配置层面统一设置：

[profile.release] panic = "abort"

这样整个 crate 在 release 模式下所有 panic 都直接 abort，不会有 unwind 穿边界的情况。但它仍不能阻止 panic 的发生，只是让崩溃行为更可控。对于库代码，我建议两手抓：在边界函数内部用 catch_unwind 兜底，同时对外保证“边界函数本身不会 panic”。

5.4 闭包捕获与 extern "C" 的不兼容

还有一个很多人会踩的坑：Rust 的闭包默认不是extern "C"函数指针。闭包可以捕获环境变量，而函数指针不能。你写的move |x| x + 1的类型是一个实现了Fntrait 的匿名类型，不是extern "C" fn(i32) -> i32，所以你不能直接把它传给 C 库。

如果 C 库只接受普通的函数指针，没有 user_data 参数，那你基本没办法把捕获了上下文的闭包传过去。这也是为什么 C 库在设计回调接口时必须提供void *user_data，否则调用者根本无法安全地传递上下文。

如果你的场景绕不开闭包，还有一个变通方案：用一个extern "C" fn静态函数作为“跳板”，通过 user_data 把闭包指针传进去：

type Callback = Box<dyn FnMut(i32)>; extern "C" fn trampoline(event: i32, data: *mut c_void) { let cb = unsafe { &mut *(data as *mut Callback) }; cb(event); }

注册时把Box<Callback>作为 user_data 传入，这样闭包就可以在回调中被间接调用。这个模式把“不可穿越的 ABI 边界”和“灵活的闭包”结合了起来，是实际工程中最常用的手段。

6. 工具链与跨平台思维：写好 extern "C" 的最终章

光会用关键字还不够，真正的工程落地还涉及构建工具、平台差异、代码组织这些“看不见”的部分。

6.1 用 build.rs 处理平台相关的链接与头文件

当一个项目需要在多个平台上链接不同名称的库时，直接在源码里写多个#[link]是很笨拙的。更灵活的做法是使用build.rs，它会在编译前执行，可以运行任意代码来决定如何链接。

一个简单的build.rs示例：

fn main() { let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap(); match target_os.as_str() { "linux" => { println!("cargo:rustc-link-lib=dylib=some_c_lib"); println!("cargo:rustc-link-search=native=/usr/local/lib"); } "windows" => { println!("cargo:rustc-link-lib=dylib=some_c_lib"); println!("cargo:rustc-link-search=native=C:\\libs\\some_c_lib"); } "macos" => { println!("cargo:rustc-link-lib=framework=SomeFramework"); } _ => {} } }

build.rs还有一个职责是生成 bindings。如果你用bindgen自动从 C 头文件生成 Rust FFI 绑定，通常也是在build.rs里完成的。这个工具能显著减少手写extern "C"声明的工作量和出错概率，推荐在大型项目里使用。

6.2 手工声明 vs bindgen：什么时候该用哪个

对于小规模调用，手工声明extern "C"完全够用。但如果 C 侧的 API 很多、结构体很多，手写就容易出错，这时用bindgen自动生成绑定更靠谱。

bindgen 生成的头文件里，典型的输出长这样：

#[repr(C)] pub struct MyStruct { pub field_a: i32, pub field_b: *mut c_char, } extern "C" { pub fn my_function(arg1: MyStruct) -> i32; }

各种#[repr(C)]、extern "C"它都会自动处理好。但这不代表你可以完全撒手不管，bindgen 对某些宏、联合体、位域的处理并不完美，生成后还是要人工检查一遍。

我实际工作中的经验是：API 少于 20 个函数时手写；超过这个量或者头文件经常变化，就上 bindgen。另外，bindgen 生成的绑定默认是 unsafe extern 块的风格，在 Rust 2021 里也能直接编译，比较省心。

6.3 导出符号的可见性：隐藏不需要暴露的符号

当你编译cdylib时，默认行为可能比你期望的暴露更多符号。为了让最终动态库里只保留真正需要导出的符号，最佳实践是在 Rust 侧限制符号可见性。

以 Linux 为例，一个简单的做法是在编译时加-C link-arg=-Wl,--exclude-libs,ALL或者使用版本脚本控制导出。但更干净的方式是用#[export_name]和#[no_mangle]精确控制，同时确保其他函数不添加这些属性。

如果你想用更工程化的方式控制符号，可以考虑在build.rs里生成链接器版本脚本：

// mylib.map LIBMYLIB { global: add_f64; mul_f64; greet; local: *; };

然后通过cargo:rustc-link-arg=-Wl,--version-script=mylib.map传入。这样，最终动态库的导出符号表就只剩下你明确指定的几个函数，对生产环境来说更安全、更干净。

6.4 一个宏：减少重复的 extern 声明模板

遇到大量重复的 FFI 声明时，我会用宏来减少样板代码。比如下面这个宏，可以同时声明 Rust 侧的外部函数，并自动生成对应的安全包装：

macro_rules! ffi_wrap { ($(fn $name:ident($($arg:ident: $arg_ty:ty),*) -> $ret:ty;)+) => { unsafe extern "C" { $(fn $name($($arg: $arg_ty),*) -> $ret;)+ } $(pub fn $name($($arg: $arg_ty),*) -> $ret { unsafe { $name($($arg),*) } })+ }; } ffi_wrap! { fn sqrt(x: f64) -> f64; fn abs(x: i32) -> i32; }

这样既保留了extern "C"的精确控制，又让安全包装层的维护变得很集中。当然，宏也不是越多越好，如果函数名冲突较多，宏展开的结果反而不直观。这个模式仅供参考，核心思路是把所有 unsafe 的声明和调用收拢到一个小范围内，业务代码不直接接触裸指针。

写在最后的一些实操心得

回到开头那个崩溃问题。最终排查出来的根因确实是调用约定错位，但导致我浪费了几个小时的原因，不是不知道extern "C"，而是没有意识到它影响的层面有多底层——它不改变你 Rust 代码里的函数行为，只改变函数在二进制层面的交互方式。这种“表面没变化、底层大变样”的特性，让很多问题很难从代码层面发现。

我现在的习惯是：所有 FFI 边界的函数，无论导出还是导入，统一做这样几件事——显式标记extern "C"和#[no_mangle]；用catch_unwind或panic = "abort"保证 panic 不穿边界；基础类型尽量用定宽整数和浮点；结构体必加#[repr(C)]；字符串用“指针 + 长度”或CString并配套释放函数；在 C 和 Rust 两侧都写布局断言。

这些习惯看起来繁琐，但每一条都是真实崩溃时间换来的。如果你刚接触 FFI，可以先把前面 2.3 节的例子跑通，再逐步加入回调、结构体、跨平台链接这些维度。等你把这几块都打通，extern "C"对你就不再是一个“照着抄的魔法咒语”，而是一套你能清晰描述的二进制约定。