WebAssembly 与 Rust 字符串传递:跨边界之前先想清内存所有权
把 Rust 编译成 WebAssembly 后做的第一件事通常是"传个字符串试试"。我当时的做法特别粗暴:在导出的函数里写死一个 &str 的返回值,然后满怀期待地在 JavaScript 侧调用——结果拿到的是一串看不懂的数字。那一刻我才意识到,WASM 边界上只有线性内存和整数,字符串这个概念在跨边界时是不存在的。
作为自学 Rust 的人,Rust 内部的所有权机制已经让我花了不少时间适应。当涉及到 WASM 跨语言边界时,所有权问题从"编译器帮你管"变成了"你自己写协议来管"——宿主和 WASM 之间,谁分配内存、谁写入数据、谁负责释放,每一步都要在代码里显式约定。 今天这篇是我在折腾 WASM 字符串传递时的学习笔记,希望对正在入坑的朋友有帮助。
一、理解 WASM 边界:只有整数,没有字符串
先看一眼宿主(JS/其他运行时)和 WASM 模块之间传递数据的真实路径:
flowchart TD
A[宿主侧字符串 Host String] --> B[编码为 UTF-8 字节 UTF-8 Encode]
B --> C[调用 WASM alloc 分配内存 Call alloc]
C --> D[将字节写入 WASM 线性内存 Write Bytes]
D --> E[传递指针+长度给 WASM 函数 Pass ptr+len]
E --> F[WASM 函数读取字节 Read Bytes from Memory]
F --> G[解码为 Rust String Decode to String]
G --> H[执行核心逻辑 Core Logic]
H --> I[结果编码为 UTF-8 Encode Result]
I --> J[WASM 分配新内存 alloc for Result]
J --> K[返回指针+长度给宿主 Return ptr+len]
K --> L[宿主读取字节 Read Bytes]
L --> M{宿主调用 dealloc 释放 Release Memory}
M -->|已释放 Freed| N[完成 Done]
M -->|忘记释放 Leak| O[内存泄漏 Memory Leak]
style E fill:#bbf,stroke:#333
style K fill:#bbf,stroke:#333
style O fill:#f66,stroke:#333
整个流程里,字符串在两边都是自然的类型,在边界上却变成了 (ptr, len) 两个数字。 每一步的"谁分配、谁释放"都不能靠编译器检查,全凭开发者写清楚协议。
二、导出分配和释放函数 — 把内存协议交给调用方
要让宿主能把字符串传进 WASM,WASM 侧必须先提供一个分配内存的函数:
use std::alloc::{alloc, Layout};
/// 暴露给宿主的内存分配函数
/// 宿主调用此函数获取 WASM 内存中的一段空白区域
#[no_mangle]
pub extern "C" fn alloc(len: usize) -> *mut u8 {
// 按指定长度用系统分配器分配对齐内存
let layout = Layout::from_size_align(len, 1).expect("无法创建内存布局");
unsafe { alloc(layout) }
// 注意:这里不释放,由宿主负责后续调用 dealloc
}
更简单的做法是用 Vec 来借它的分配能力,然后用 forget 防止自动释放:
/// 简化版:利用 Vec 自动分配,但 forget 掉防止 Drop
#[no_mangle]
pub extern "C" fn alloc_simple(len: usize) -> *mut u8 {
let mut buf: Vec<u8> = Vec::with_capacity(len);
let ptr = buf.as_mut_ptr();
// forget 阻止 Vec 在函数返回时自动释放内存
// 所有权转移给调用方
std::mem::forget(buf);
ptr
}
光分配不释放是内存泄漏。所以对应地,还要导出一个释放函数:
/// 释放由 alloc 分配的内存
/// 安全前提:调用方必须传回 alloc 返回的指针和原始长度
#[no_mangle]
pub unsafe extern "C" fn dealloc(ptr: *mut u8, len: usize) {
if ptr.is_null() {
return; // 空指针不需要释放
}
// 用 Vec::from_raw_parts 重新接管所有权,让 Drop 自动释放
let _ = Vec::from_raw_parts(ptr, len, len);
// _ 离开作用域后自动调用 Drop,释放内存
}
这里有一个非常危险的隐藏约束:调用方必须对每个 alloc 返回的指针恰好调用一次 dealloc,而且长度必须一致。 如果宿主传错了长度,或者在同一个指针上调用了两次 dealloc,就可能导致未定义行为——程序不会 panic,而是静默地损坏内存。我在测试时就用一个错误的长度参数把 dev server 搞崩过,排查了半天。
三、读入和输出都要有明确的协议
当字符串从宿主传入时,WASM 侧用指针和长度读取:
/// 从 WASM 线性内存中读取宿主传入的字符串
/// # 安全
/// 调用者必须保证 ptr 和 len 指向合法的 UTF-8 字节
unsafe fn read_host_string(ptr: *const u8, len: usize) -> Result<String, String> {
if ptr.is_null() || len == 0 {
return Err("输入指针为空或长度为零".to_string());
}
// 从原始指针创建字节切片
let bytes = std::slice::from_raw_parts(ptr, len);
// 尝试解码为 UTF-8
String::from_utf8(bytes.to_vec())
.map_err(|e| format!("输入不是有效的 UTF-8 编码: {}", e))
}
返回值的处理更复杂一些。WASM 不能直接返回一个 Rust String,需要把结果编码后放在线性内存里,然后告诉宿主"结果在地址 X,长度 Y,你读完后记得调用 dealloc":
/// 一个完整的往返调用示例
#[no_mangle]
pub unsafe extern "C" fn process(ptr: u32, len: u32) -> u64 {
// 1. 从宿主读入字符串
let input = read_host_string(ptr as *const u8, len as usize)
.unwrap_or_else(|e| format!("[错误] {}", e));
// 2. 执行业务逻辑
let output = format!("WASM 收到: {}", input);
// 3. 分配输出内存
let out_bytes = output.into_bytes();
let out_len = out_bytes.len();
let out_ptr = alloc(out_len);
// 4. 把结果写入分配的内存
let out_slice = std::slice::from_raw_parts_mut(out_ptr, out_len);
out_slice.copy_from_slice(&out_bytes);
// 5. 把指针和长度打包进一个 u64 返回
// 高 32 位放长度,低 32 位放指针
((out_len as u64) << 32) | (out_ptr as u64)
}
对于复杂数据(结构化参数、嵌套对象等),我更推荐用 JSON 或 MessagePack 序列化:
use serde::{Serialize, Deserialize};
#[derive(Serialize, Deserialize)]
struct PluginInput {
prompt: String,
max_tokens: u32,
temperature: f32,
}
协议简单、可调试、不容易出错。序列化有性能开销,但在插件场景下通常不是瓶颈。等性能真的不够用了再考虑更紧凑的方案,而不是一开始就把内存布局搞得很复杂。
四、测试先跑一个最小 Roundtrip
跨边界传字符串最容易出问题的是"协议不对齐"。我调试 WASM 字符串问题时的习惯是:先写一个最简单的往返测试:
/// 最小 Roundtrip 测试:验证整条字符串传递链路
#[no_mangle]
pub unsafe extern "C" fn echo(ptr: u32, len: u32) -> u64 {
// 读入 → 原样返回
let input = read_host_string(ptr as *const u8, len as usize)
.unwrap_or_else(|_| String::new());
// 分配并返回同样内容
let bytes = input.into_bytes();
let out_len = bytes.len();
let out_ptr = alloc(out_len);
std::slice::from_raw_parts_mut(out_ptr, out_len)
.copy_from_slice(&bytes);
((out_len as u64) << 32) | (out_ptr as u64)
}
这个测试虽然简单,但能验证 UTF-8 编解码、内存分配/释放、指针传递和长度计算四条链路。如果 echo("hello") 都跑不稳,就不要继续堆 AI 插件逻辑了——边界协议不稳,业务代码越多越难排查。
五、总结
WebAssembly 与 Rust 传递字符串的核心不是"传个 String 就行",而是要在跨边界之前先定义清楚内存所有权协议:谁分配、谁写入、谁读取、谁释放,每一步都要有对应的代码约束。 导出的 alloc/dealloc 函数是协议的骨架,UTF-8 编解码和序列化方案是通道里的翻译层。
作为自学者,WASM 的字符串传递让我真正理解了"所有权跨越编译器边界时,就变成了程序员自己的责任"。Rust 的 borrow checker 帮我们管住了 Rust 内部的内存安全,但跨语言的桥梁两端,还是要靠我们自己写清楚协议。测试时先跑最小 roundtrip,协议稳了再往上堆功能——这是我在 WASM 上栽过的最管用的教训。
297



被折叠的 条评论
为什么被折叠?



