FFI

bun:ffi 是实验性的，存在已知的 bug 和限制，不应在生产环境中依赖。从 Bun 与原生代码交互的最稳定方式是编写 Node-API 模块。

使用内置的 bun:ffi 模块高效地从 JavaScript 调用原生库。它适用于任何支持 C ABI 的语言，包括 Zig、Rust、C/C++、C#、Nim 和 Kotlin。

dlopen 用法（`bun:ffi`）

打印 sqlite3 的版本号：

import { dlopen, FFIType, suffix } from "bun:ffi";

// `suffix` 根据平台为 "dylib"、"so" 或 "dll"
// 您不一定要使用 "suffix"，它只是为了方便
const path = `libsqlite3.${suffix}`;

const {
  symbols: {
    sqlite3_libversion, // 要调用的函数
  },
} = dlopen(
  path, // 库名称或文件路径
  {
    sqlite3_libversion: {
      // 无参数，返回字符串
      args: [],
      returns: FFIType.cstring,
    },
  },
);

console.log(`SQLite 3 version: ${sqlite3_libversion()}`);

性能

根据我们的基准测试，bun:ffi 的速度大约是 Node.js 通过 Node-API 进行 FFI 的 2-6 倍。 Bun 生成并即时编译 C 绑定，高效地在 JavaScript 类型和原生类型之间转换值。为了编译 C，Bun 嵌入了 TinyCC，一个小型且快速的 C 编译器。

用法

Zig

add.zig

pub export fn add(a: i32, b: i32) i32 {
  return a + b;
}

要编译：

terminal

zig build-lib add.zig -dynamic -OReleaseFast

将共享库的路径和要导入的符号映射传递给 dlopen：

import { dlopen, FFIType, suffix } from "bun:ffi";
const { i32 } = FFIType;

const path = `libadd.${suffix}`;

const lib = dlopen(path, {
  add: {
    args: [i32, i32],
    returns: i32,
  },
});

console.log(lib.symbols.add(1, 2));

Rust

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

要编译：

rustc --crate-type cdylib add.rs

C++

#include <cstdint>

extern "C" int32_t add(int32_t a, int32_t b) {
    return a + b;
}

要编译：

# Linux
clang++ -shared -fPIC add.cpp -o libadd.so

# macOS
clang++ -dynamiclib add.cpp -o libadd.dylib

FFI 类型

支持以下 FFIType 值。

`FFIType`	C 类型	别名
buffer	`char*`
cstring	`char*`
function	`(void)()()`	`fn`、`callback`
ptr	`void*`	`pointer`、`void`、`char`
i8	`int8_t`	`int8_t`
i16	`int16_t`	`int16_t`
i32	`int32_t`	`int32_t`、`int`
i64	`int64_t`	`int64_t`
i64_fast	`int64_t`
u8	`uint8_t`	`uint8_t`
u16	`uint16_t`	`uint16_t`
u32	`uint32_t`	`uint32_t`
u64	`uint64_t`	`uint64_t`
u64_fast	`uint64_t`
f32	`float`	`float`
f64	`double`	`double`
bool	`bool`
char	`char`
napi_env	`napi_env`
napi_value	`napi_value`

buffer 参数必须是 TypedArray 或 DataView。

字符串

JavaScript 字符串和类 C 字符串是不同的，这给使用字符串与原生库交互带来了复杂性。

JavaScript 字符串和 C 字符串有何不同？

JavaScript 字符串：

UTF16（每个字母 2 字节）或可能的 latin1，取决于 JavaScript 引擎和使用的是什么字符
length 单独存储
不可变

C 字符串：

UTF8（每个字母 1 字节），通常
不存储长度。相反，字符串以 null 结尾：其长度是第一个 \0 的索引
可变

为了解决这个问题，bun:ffi 导出了 CString，它扩展了 JavaScript 内置的 String 以支持 null 结尾的字符串并添加了一些额外功能：

class CString extends String {
  /**
   * 给定一个 `ptr`，它会自动搜索结束的 `\0` 字符，
   * 并在必要时从 UTF-8 转码为 UTF-16。
   */
  constructor(ptr: number, byteOffset?: number, byteLength?: number): string;

  /**
   * C 字符串的指针
   *
   * 此 `CString` 实例是字符串的克隆，因此在 `ptr` 被释放后
   * 继续使用此实例是安全的。
   */
  ptr: number;
  byteOffset?: number;
  byteLength?: number;
}

从 null 结尾的字符串指针转换为 JavaScript 字符串：

const myString = new CString(ptr);

从具有已知长度的指针转换为 JavaScript 字符串：

const myString = new CString(ptr, 0, byteLength);

new CString() 构造器会克隆 C 字符串，因此在 ptr 被释放后继续使用 myString 是安全的。

my_library_free(myString.ptr);

// 这是安全的，因为 myString 是克隆体
console.log(myString);

当用于 returns 时，FFIType.cstring 将指针强制转换为 JavaScript string。当用于 args 时，FFIType.cstring 与 ptr 相同。

函数指针

不支持异步函数

要从 JavaScript 调用函数指针，请使用 CFunction，例如配合您从已加载的 Node-API（napi）模块获得的指针。

import { CFunction } from "bun:ffi";

let myNativeLibraryGetVersion = /* 不知何故，您获得了这个指针 */

const getVersion = new CFunction({
  returns: "cstring",
  args: [],
  ptr: myNativeLibraryGetVersion,
});
getVersion();

要一次定义多个函数指针，请使用 linkSymbols：

import { linkSymbols } from "bun:ffi";

// getVersionPtrs 在其他地方定义
const [majorPtr, minorPtr, patchPtr] = getVersionPtrs();

const lib = linkSymbols({
  // 与 dlopen() 不同，此处的名称可以是任何内容
  getMajor: {
    returns: "cstring",
    args: [],

    // 由于这不使用 dlsym()，您必须提供有效的 ptr
    // 该 ptr 可以是数字或 bigint
    // 无效的指针会使程序崩溃。
    ptr: majorPtr,
  },
  getMinor: {
    returns: "cstring",
    args: [],
    ptr: minorPtr,
  },
  getPatch: {
    returns: "cstring",
    args: [],
    ptr: patchPtr,
  },
});

const [major, minor, patch] = [lib.symbols.getMajor(), lib.symbols.getMinor(), lib.symbols.getPatch()];

回调

使用 JSCallback 创建可传递给 C/FFI 函数的 JavaScript 回调函数，使原生代码可以回调您的 JavaScript 或 TypeScript。这对于异步代码非常有用。

import { dlopen, JSCallback, ptr, CString } from "bun:ffi";

const {
  symbols: { search },
  close,
} = dlopen("libmylib", {
  search: {
    returns: "usize",
    args: ["cstring", "callback"],
  },
});

const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
  returns: "bool",
  args: ["ptr", "usize"],
});

const str = Buffer.from("wwutwutwutwutwutwutwutwutwutwutut\0", "utf8");
if (search(ptr(str), searchIterator)) {
  // 找到了匹配！
}

// 稍后：
setTimeout(() => {
  searchIterator.close();
  close();
}, 5000);

当您完成 JSCallback 的使用后，调用 close() 以释放内存。

实验性线程安全回调

JSCallback 具有实验性的线程安全回调支持。如果您将回调函数传递到创建它的线程之外的其他线程，则需要此功能。通过可选的 threadsafe 参数启用它。线程安全回调在从运行 JavaScript 代码的另一个线程（即 Worker）调用时效果最佳。未来的 Bun 版本将支持从任何线程调用它们，例如由 Bun 不知晓的原生库生成的新线程。

const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), {
  returns: "bool",
  args: ["ptr", "usize"],
  threadsafe: true, // 可选。默认为 `false`
});

⚡️ 性能提示：为获得轻微的性能提升，直接传递 JSCallback.prototype.ptr 而不是 JSCallback 对象：

const onResolve = new JSCallback(arg => arg === 42, {
  returns: "bool",
  args: ["i32"],
});
const setOnResolve = new CFunction({
  returns: "bool",
  args: ["function"],
  ptr: myNativeLibrarySetOnResolve,
});

// 这段代码运行稍快：
setOnResolve(onResolve.ptr);

// 相比：
setOnResolve(onResolve);

指针

Bun 将指针表示为 JavaScript 中的 number。

64 位指针如何适合 JavaScript 数值？

64 位处理器支持多达 52 位的可寻址空间。JavaScript 数值支持 53 位的可用空间，这留下了约 11 位的额外空间。为什么不用 BigInt？ BigInt 更慢。JavaScript 引擎单独分配 BigInt，因此它们不能放入常规的 JavaScript 值中。如果您将 BigInt 传递给函数，它会被转换为 number。Windows 注意：Windows API 类型 HANDLE 不表示虚拟地址，将其用于 ptr 不会按预期工作。请使用 u64 安全地表示 HANDLE 值。

从 TypedArray 转换为指针：

import { ptr } from "bun:ffi";
let myTypedArray = new Uint8Array(32);
const myPtr = ptr(myTypedArray);

从指针转换为 ArrayBuffer：

import { ptr, toArrayBuffer } from "bun:ffi";
let myTypedArray = new Uint8Array(32);
const myPtr = ptr(myTypedArray);

// toArrayBuffer 接受 `byteOffset` 和 `byteLength`
// 如果未提供 `byteLength`，则假定为 null 结尾的指针
myTypedArray = new Uint8Array(toArrayBuffer(myPtr, 0, 32), 0, 32);

要读取指针中的数据，您有两种选择。对于长期存在的指针，使用 DataView：

import { toArrayBuffer } from "bun:ffi";
let myDataView = new DataView(toArrayBuffer(myPtr, 0, 32));

console.log(
  myDataView.getUint8(0, true),
  myDataView.getUint8(1, true),
  myDataView.getUint8(2, true),
  myDataView.getUint8(3, true),
);

对于短期存在的指针，使用 read：

import { read } from "bun:ffi";

console.log(
  // ptr, byteOffset
  read.u8(myPtr, 0),
  read.u8(myPtr, 1),
  read.u8(myPtr, 2),
  read.u8(myPtr, 3),
);

read 函数的行为类似于 DataView，但通常更快，因为它不需要创建 DataView 或 ArrayBuffer。

`FFIType`	`read` 函数
ptr	`read.ptr`
i8	`read.i8`
i16	`read.i16`
i32	`read.i32`
i64	`read.i64`
u8	`read.u8`
u16	`read.u16`
u32	`read.u32`
u64	`read.u64`
f32	`read.f32`
f64	`read.f64`

内存管理

bun:ffi 不会为您管理内存。当您使用完内存后，必须自行释放。

从 JavaScript

要跟踪 TypedArray 何时不再从 JavaScript 使用，请使用 FinalizationRegistry。

从 C、Rust、Zig 等

要跟踪 TypedArray 何时不再从 C 或 FFI 使用，请向 toArrayBuffer 或 toBuffer 传递一个回调和可选上下文的指针。回调会在垃圾收集器释放底层 ArrayBuffer JavaScript 对象时稍后调用。期望的签名与 JavaScriptCore 的 C API 相同：

typedef void (*JSTypedArrayBytesDeallocator)(void *bytes, void *deallocatorContext);

import { toArrayBuffer } from "bun:ffi";

// 带有 deallocatorContext：
toArrayBuffer(
  bytes,
  byteOffset,

  byteLength,

  // 这是指向回调的可选指针
  deallocatorContext,

  // 这是指向函数的指针
  jsTypedArrayBytesDeallocator,
);

// 不带 deallocatorContext：
toArrayBuffer(
  bytes,
  byteOffset,

  byteLength,

  // 这是指向函数的指针
  jsTypedArrayBytesDeallocator,
);

内存安全

不要在 FFI 之外使用原始指针。未来的 Bun 版本可能会添加 CLI 标志来禁用 bun:ffi。

指针对齐

如果 API 期望的指针大小不是 char 或 u8，请确保 TypedArray 也是该大小。由于对齐原因，u64* 与 [8]u8* 并不完全相同。

传递指针

在 FFI 函数期望指针的地方，传递同等大小的 TypedArray：

import { dlopen, FFIType } from "bun:ffi";

const {
  symbols: { encode_png },
} = dlopen(myLibraryPath, {
  encode_png: {
    // FFIType 也可以指定为字符串
    args: ["ptr", "u32", "u32"],
    returns: FFIType.ptr,
  },
});

const pixels = new Uint8ClampedArray(128 * 128 * 4);
pixels.fill(254);
pixels.subarray(0, 32 * 32 * 2).fill(0);

const out = encode_png(
  // pixels 将作为指针传递
  pixels,

  128,
  128,
);

自动生成的包装器会将 TypedArray 转换为指针。

硬核模式

如果您不想要自动转换，或者想要指向 TypedArray 内特定字节偏移量的指针，请直接获取 TypedArray 的指针：

import { dlopen, FFIType, ptr } from "bun:ffi";

const {
  symbols: { encode_png },
} = dlopen(myLibraryPath, {
  encode_png: {
    // FFIType 也可以指定为字符串
    args: ["ptr", "u32", "u32"],
    returns: FFIType.ptr,
  },
});

const pixels = new Uint8ClampedArray(128 * 128 * 4);
pixels.fill(254);

// 这返回一个 number！不是 BigInt！
const myPtr = ptr(pixels);

const out = encode_png(
  myPtr,

  // 尺寸：
  128,
  128,
);

读取指针

const out = encode_png(
  // pixels 将作为指针传递
  pixels,

  // 尺寸：
  128,
  128,
);

// 假设它是 0 结尾的，可以这样读取：
let png = new Uint8Array(toArrayBuffer(out));

// 保存到磁盘：
await Bun.write("out.png", png);

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

dlopen 用法（`bun:ffi`）

性能

用法

Zig

Rust

C++

FFI 类型

字符串

函数指针

回调

实验性线程安全回调

指针

内存管理

从 JavaScript

从 C、Rust、Zig 等

内存安全

指针对齐

传递指针

读取指针

​dlopen 用法（bun:ffi）

​性能

​用法

​Zig

​Rust

​C++

​FFI 类型

​字符串

​函数指针

​回调

​实验性线程安全回调

​指针

​内存管理

​从 JavaScript

​从 C、Rust、Zig 等

​内存安全

​指针对齐

​传递指针

​读取指针

dlopen 用法（`bun:ffi`）

性能

用法

Zig

Rust

C++

FFI 类型

字符串

函数指针

回调

实验性线程安全回调

指针

内存管理

从 JavaScript

从 C、Rust、Zig 等

内存安全

指针对齐

传递指针

读取指针