WASM + WASI 预览版 2：文件系统和网络的标准化接口深度解析
WASI（WebAssembly System Interface）预览版 2 的发布，是 Wasm 走出浏览器、进入服务端生态的一个里程碑。在预览版 1 中，WASI 只覆盖了最基本的 POSIX 风格文件系统操作；而预览版 2 带来了组件模型（Component Model）、标准化网络接口（wasi:sockets）和全新的"世界"（World）概念。对于做 Wasm 服务端开发的人来说，这意味着终于不用再通过各种 hack 方式调用宿主函数来实现网络通信了。
作为从 WASI Preview 1 一路踩坑过来的自学者，我花了两个周末把 Preview 2 的新能力过了一遍。这篇文章就是我的学习笔记和实践心得。
一、WASI 从 Preview 1 到 Preview 2 的架构跃迁
在 Preview 1 时代，WASI 的接口是 POSIX 风格的 C 函数调用（如 fd_read、fd_write、path_open）。编译器（如 rustc）通过 wasm32-wasi target 生成 Wasm 模块时，会自动将这些 POSIX 调用翻译为 WASI 的 import。
Preview 2 完全抛弃了这种"C 函数风格"，转而采用组件模型（Component Model）和WIT（Wasm Interface Type）。这意味着：
- 接口是强类型的。不再是"传一个 fd 整数过去"，而是通过类型安全的接口定义来声明需要什么能力。
- 能力是声明式的。Wasm 模块的 WIT 文件声明了它需要的接口，宿主在加载时可以精确控制和审计这些能力。
- 组件可组合。不同 Wasm 组件可以通过虚拟化的接口相互通信，而不再只能和宿主通信。
二、WIT 接口定义语言与组件模型实战
WIT 是 Preview 2 的"IDL（接口定义语言）"。每一个 Wasm 组件通过 WIT 向外部声明："我需要什么能力"和"我能提供什么能力"。
2.1 基础 WIT 接口定义
// =========================================================================
// 文件: calculator.wit —— 定义一个计算器组件的接口
// =========================================================================
/// 计算器组件向外界暴露的接口
interface calculator {
/// 数学操作枚举
enum operation {
add,
subtract,
multiply,
divide,
}
/// 计算请求
record calc-request {
op: operation,
/// 左操作数
left: float64,
/// 右操作数
right: float64,
}
/// 计算结果
record calc-response {
/// 计算结果
result: float64,
/// 可能的错误信息（如除以零）
error: option<string>,
}
/// 执行计算的入口函数
calculate: func(req: calc-request) -> calc-response;
}
/// 组件声明：定义整个组件的"世界"
/// guest 部分描述本组件对外暴露的功能
/// host 部分描述本组件依赖的宿主能力
default world calculator-world {
/// 本组件导出的接口
export calculator;
/// 本组件依赖的 WASI 标准接口
import wasi:filesystem/types@0.2.0;
import wasi:io/streams@0.2.0;
}
2.2 Rust 侧实现 WIT 定义的组件
// =========================================================================
// Rust 实现：将 calculator.wit 编译为 Rust trait 并实现
// Cargo.toml 中添加:
// [package.metadata.component]
// package = "component:calculator"
// [package.metadata.component.dependencies]
// "wasi:filesystem" = { path = "../wit/deps/filesystem" }
// =========================================================================
// 使用 wit-bindgen 宏将 WIT 接口生成为 Rust trait
wit_bindgen::generate!({
// 指定当前组件实现的世界
world: "calculator-world",
// 生成异步风格的接口（使用 async/await）
exports: {
"component:calculator/calculator": CalculatorImpl,
},
});
/// 计算器组件的具体实现
struct CalculatorImpl;
/// 实现 generated trait —— Guest 是 wit-bindgen 自动生成的特征名
impl Guest for CalculatorImpl {
fn calculate(req: CalcRequest) -> CalcResponse {
println!(
"[计算器] 收到请求: {:?} {} {:?}",
req.left,
match req.op {
Operation::Add => "+",
Operation::Subtract => "-",
Operation::Multiply => "×",
Operation::Divide => "÷",
},
req.right
);
let result = match req.op {
Operation::Add => req.left + req.right,
Operation::Subtract => req.left - req.right,
Operation::Multiply => req.left * req.right,
Operation::Divide => {
// 检查除零错误
if req.right.abs() < f64::EPSILON {
return CalcResponse {
result: 0.0,
error: Some("除数不能为零".to_string()),
};
}
req.left / req.right
}
};
CalcResponse {
result,
error: None,
}
}
}
三、文件系统接口：wasi:filesystem 的实战应用
Preview 2 的文件系统接口不再是裸露的 fd 操作，而是结构化、类型安全的资源（Resource）模型：
// =========================================================================
// 使用 WASI Preview 2 文件系统接口的文件处理器组件
// =========================================================================
wit_bindgen::generate!({
world: "file-processor",
exports: {
"component:file-processor/processor": FileProcessor,
},
});
use wasi::filesystem::preopens;
use wasi::filesystem::types::{
Descriptor, DescriptorFlags, OpenFlags, PathFlags,
};
struct FileProcessor;
impl Guest for FileProcessor {
/// 读取指定目录下的所有 .log 文件并汇总行数
fn count_log_lines(dir_name: String) -> Result<u64, String> {
// 步骤1：获取 WASI 预打开的目录列表
let dirs = preopens::get_directories()
.map_err(|e| format!("无法获取预打开目录: {:?}", e))?;
// 步骤2：找到目标目录的句柄
let target_dir = dirs
.into_iter()
.find(|(_, name)| name == &dir_name)
.map(|(desc, _)| desc)
.ok_or_else(|| format!("未找到目录: {}", dir_name))?;
// 步骤3：以只读方式打开目标目录
let dir_entry = target_dir
.open_at(
PathFlags::DIRECTORY,
".", // 相对路径
OpenFlags::DIRECTORY,
DescriptorFlags::READ,
)
.map_err(|e| format!("打开目录失败: {:?}", e))?;
// 步骤4：遍历目录条目
let entries = dir_entry
.read_directory()
.map_err(|e| format!("读取目录失败: {:?}", e))?;
let mut total_lines: u64 = 0;
let mut file_count: u64 = 0;
for entry in entries {
match entry {
Ok(entry) => {
// 只处理 .log 后缀的文件
if entry.name.ends_with(".log") {
// 获取类型信息（跳过子目录）
if let Some(meta) = entry.metadata() {
if meta.is_file() {
// 打开文件并读取内容
let file = target_dir
.open_at(
PathFlags::empty(),
&entry.name,
OpenFlags::empty(),
DescriptorFlags::READ,
)
.map_err(|e| format!("打开文件 {} 失败: {:?}", entry.name, e))?;
// 读取文件内容（通过 wasi:io/streams）
let data = read_file_to_string(&file)
.map_err(|e| format!("读取文件 {} 失败: {:?}", entry.name, e))?;
// 计算行数
let lines = data.lines().count() as u64;
total_lines += lines;
file_count += 1;
println!(
"[处理器] 文件: {} | 行数: {}",
entry.name, lines
);
}
}
}
}
Err(e) => eprintln!("[处理器] 遍历错误: {:?}", e),
}
}
println!(
"[处理器] 处理完成: {} 个 .log 文件, 共 {} 行",
file_count, total_lines
);
Ok(total_lines)
}
}
/// 辅助函数：将文件内容读取为字符串
fn read_file_to_string(file: &Descriptor) -> Result<String, String> {
use wasi::io::streams;
// 通过文件描述符获取流
let stream = file
.read_via_stream(0) // 从文件开头偏移 0 处读取
.map_err(|e| format!("获取文件流失败: {:?}", e))?;
let mut buffer = Vec::new();
// 循环读取直到 EOF
loop {
let chunk = stream
.read(8192) // 每次读取 8KB 块
.map_err(|e| format!("读取流失败: {:?}", e))?;
if chunk.is_empty() {
break; // 到达文件末尾
}
buffer.extend_from_slice(&chunk);
}
String::from_utf8(buffer)
.map_err(|e| format!("UTF-8 解码失败: {}", e))
}
四、网络接口：wasi:sockets 的时代来了
Preview 2 中最大的变化之一就是将网络通信标准化。以前在 Wasm 中做 HTTP 请求，要么依赖宿主 JS 的 fetch，要么用各种自制的 WIT 扩展。现在有了官方的 wasi:sockets：
// =========================================================================
// 使用 WASI Preview 2 wasi:sockets 接口发送 HTTP 请求的示例
// =========================================================================
wit_bindgen::generate!({
world: "http-client",
exports: {
"component:http-client/client": HttpClientImpl,
},
});
use wasi::sockets::network::{self, Network};
use wasi::sockets::tcp::{self, TcpSocket};
use wasi::sockets::tcp_create_socket;
use wasi::sockets::ip_name_lookup;
use wasi::sockets::instance_network;
struct HttpClientImpl;
impl Guest for HttpClientImpl {
/// 向指定 host 发送一个简单的 HTTP GET 请求
fn http_get(host: String, port: u16, path: String) -> Result<String, String> {
// 步骤1：获取默认网络实例
let network = instance_network::instance_network()
.map_err(|e| format!("获取网络实例失败: {:?}", e))?;
// 步骤2：解析域名到 IP 地址
let addresses = network
.resolve_addresses(
&network,
&host,
port,
None, // 不指定地址族，IPv4/IPv6 都接受
false, // 不等待 DNS 更新
false, // 不请求快速超时
)
.map_err(|e| format!("DNS 解析失败: {:?}", e))?;
// 步骤3：创建 TCP socket
let tcp_socket = tcp_create_socket::create_tcp_socket(
network::IpAddressFamily::Ipv4,
)
.map_err(|e| format!("创建 TCP socket 失败: {:?}", e))?;
// 步骤4：连接到第一个解析出的地址（生产环境应遍历重试）
let first_addr = addresses
.first()
.ok_or_else(|| "DNS 未返回任何地址".to_string())?;
let remote_addr = first_addr
.ip_address()
.ok_or_else(|| "地址没有 IP 信息".to_string())?;
tcp_socket
.start_connect(network, remote_addr, port)
.map_err(|e| format!("发起连接失败: {:?}", e))?;
// 等待连接建立
let (send_stream, recv_stream) = tcp_socket
.finish_connect()
.map_err(|e| format!("连接建立失败: {:?}", e))?;
// 步骤5：构造并发送 HTTP 请求
let request = format!(
"GET {} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n\r\n",
path, host
);
send_stream
.blocking_write_and_flush(request.as_bytes())
.map_err(|e| format!("发送请求失败: {:?}", e))?;
// 步骤6：读取 HTTP 响应
let mut response = Vec::new();
let mut buf = [0u8; 4096];
loop {
let n = recv_stream
.blocking_read(&mut buf)
.map_err(|e| format!("读取响应失败: {:?}", e))?;
if n == 0 {
break; // 对端关闭连接
}
response.extend_from_slice(&buf[..n]);
}
let response_str = String::from_utf8_lossy(&response).to_string();
Ok(response_str)
}
}
实战踩坑：从 Preview 1 迁移到 Preview 2 的痛
wasm32-wasi target 不再适用。 Preview 2 需要
wasm32-wasip2target，不是 Preview 1 的wasm32-wasi。如果rustup target add错了，cargo 会报"unknown target"而非"wrong wasi version"，排查了半小时。wit-bindgen 版本碎片化。
wit-bindgen0.26 和 0.30 生成的 Rust 代码结构完全不同。我在示例里用了 0.30 的Guesttrait 写法，但项目中某个间接依赖锁定了 0.26，导致编译错误——两套生成代码的 trait 名称和模块路径都对不上。解决：在Cargo.toml里精确锁定wit-bindgen = "=0.30.0"。sockets 接口的可用性严重依赖 runtime。
wasi:sockets在 Wasmtime 18+ 可以跑，但在jco（Node.js 的 WASI runtime）上还没实现。代码里 import 了wasi:sockets后，用 jco 跑会报 "unknown import"。如果要保证跨运行时兼容，需要根据 target runtime 条件编译不同的网络实现。构建产物体积增加。 Preview 2 的组件模型生成的
.wasm比 Preview 1 大约 15-20%。对于需要通过网络分发 Wasm 组件的场景，这个体积增长值得关注。
五、总结
WASI Preview 2 的核心价值在于：将 Wasm 从浏览器技术变成了通用计算平台的运行时。文件系统和网络的标准化接口，让 Rust 编写的服务端应用可以编译为 .wasm 组件，在任何支持 WASI Preview 2 的 runtime（Wasmtime 18+、WasmEdge、jco）上运行。
当前各 runtime 的 WASI Preview 2 支持情况（截至 2026 年 6 月）：
| Runtime | wasi:filesystem | wasi:sockets | wasi:http | 组件模型 |
|---|---|---|---|---|
| Wasmtime 19 | 完整 | 完整 | 完整 | 完整 |
| WasmEdge 0.14 | 完整 | 部分 | 实验 | 部分 |
| jco (Node.js) | 完整 | 未实现 | 未实现 | 基本 |
| wasmCloud | 完整 | 完整 | 规划中 | 完整 |
选型时先确认目标 platform 的支持矩阵，避免写了 wasi:sockets 后在 Node.js 环境跑不了。
几个关键变化：
- WIT 替代了 C 函数风格的 import/export，接口变得类型安全。
- 组件模型允许不同 Wasm 模块在沙箱内部互相通信，形成真正的微服务组合。
- wasi:filesystem 和 wasi:sockets 让文件 I/O 和网络编程不再依赖特定宿主。
对于像我这样的 Rust 开发者来说，Preview 2 意味着：你的代码写一次，就能以 Wasm 组件形式部署到任何支持者 runtime——这有点像 Java 当年的"一次编写到处运行"，但不需要 JVM 的重量级运行时。
下一篇是本系列的最后一篇：浏览器端模型预加载策略——用户还没点按钮，推理已经准备好了。欢迎在评论区讨论你的 WASI 使用体验！
扫一扫
689
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
