用途:该技能面向需要在 Bun 运行时中调用原生 C/C++ 共享库的场景,通过内置模块 bun:ffi 实现外部函数接口(FFI),无需编写原生插件即可访问系统库或自定义动态库。
主要能力:使用 dlopen 加载库并声明函数签名;通过 FFIType 映射整数、无符号整数、浮点、指针、cstring、bool、void 等类型;支持平台后缀 suffix(macOS 为 dylib、Linux 为 so、Windows 为 dll)与跨平台路径处理;支持字符串传入传出(需以 \0 结尾,用 CString 转换返回值);支持指针与 ArrayBuffer 互转(ptr、toArrayBuffer);支持手动构造结构体内存布局;支持 callback 创建回调并在用完后 close;提供 SQLite 调用示例;说明内存管理与线程安全注意事项。
使用方式:从 "bun:ffi" 导入 dlopen、suffix、FFIType、ptr、CString、toArrayBuffer、callback 等,先 dlopen 库并定义各函数的 args 与 returns,再通过 lib.symbols.函数名 调用。示例:const lib = dlopen(libc.${suffix}, { printf: { args: [FFIType.cstring], returns: FFIType.int } }); lib.symbols.printf("Hello from C!\n");
适用场景:调用系统库或第三方 C 库、复用已有原生代码、访问底层 API、在 Bun 中集成 SQLite 等原生依赖。
限制:FFI 调用为同步操作,会阻塞主线程,长时间运行的操作建议放入 Web Worker;需保证指针有效性与类型精确匹配,否则可能出现库未找到、符号未找到、类型不匹配或段错误;C 分配的内存需调用对应释放函数。更复杂的类型转换、结构体布局、联合类型及性能优化可参考技能内的 references/type-mappings.md 与 references/performance.md。