在 VS Code for the Web 中运行 WebAssembly:WASI 执行引擎原理与扩展开发实战
在 VS Code for the Web 中运行 WebAssembly:WASI 执行引擎原理与扩展开发实战
VS Code for the Web(vscode.dev)自发布以来,其目标始终是在浏览器中完成完整的"编辑—编译—调试"开发闭环。本篇技术指南基于 VS Code 官方 2023 年 6 月的博客文章 vscode-wasm-wasi.md,深入讲解 VS Code 团队如何将 CPython 解释器编译为 WebAssembly(WASM)并在浏览器中直接运行,剖析其基于 WASI 规范的执行引擎实现原理,并给出从 C 源码编译、扩展清单配置到 TypeScript 加载运行的完整实战方案。读完本文,你将掌握如何在 VS Code 的扩展宿主中以 WASI 方式加载并运行任意可编译为 wasm32-wasi 的代码,以及 WASM 同步执行模型与 VS Code 异步 API 之间的桥接机制。
背景:在浏览器中补齐"编辑—编译—调试"闭环
JavaScript 与 TypeScript 之所以能在浏览器中直接运行,是因为浏览器本身就内置了 JavaScript 执行引擎。但对于 Python 这类语言,要在浏览器中执行源码,就必须有一个能运行 Python 解释器的执行引擎——而这类语言运行时通常是用 C/C++ 编写的。
WebAssembly 是一种面向虚拟机的二进制指令格式,现代浏览器已经内置了 WebAssembly 虚拟机,且社区已有成熟的工具链能把 C/C++ 编译为 WebAssembly 代码。为了验证 WebAssembly 在当前技术条件下能做到什么程度,VS Code 团队决定把用 C/C++ 编写的 Python 解释器编译成 WebAssembly,放进 VS Code for the Web 中运行。恰好 Python 官方团队已经在推进把 CPython 编译到 WASM 的工作,VS Code 团队直接复用了这一成果。
从演示中可以看出,在浏览器里执行 Python 的体验与桌面端 VS Code 几乎无异。这一结果的价值体现在几个层面:
- Python 源码(
app.py与hello.py)托管在 GitHub 仓库中,由 VS Code 直接读取;Python 解释器可以完整访问工作区中的文件,但无法访问其他任何文件。 - 示例代码是多文件的,
app.py依赖hello.py,验证了多文件依赖解析能力。 - 程序输出能够原样呈现在 VS Code 的终端里。
- 可以启动 Python REPL 并与之完整交互。
- 最关键的是——它真的运行在 Web 上。
此外,这个编译为 WASM 的 Python 解释器在接入 VS Code for the Web 时无需任何改动,其二进制产物与 CPython 团队发布的版本逐字节一致。这意味着 WASI 运行时与宿主之间的接口是通用的,语言运行时本身不需要为 VS Code 做任何定制。
工作原理:WASI 与宿主函数调用
WebAssembly 虚拟机不像 Java 或 .NET 那样自带 SDK,因此开箱即用的 WASM 代码既不能向控制台打印内容,也不能读取文件。WebAssembly 规范真正定义的,是 WASM 代码如何调用运行虚拟机的宿主(host)中的函数——在 VS Code for the Web 场景下,宿主就是浏览器,虚拟机因此可以调用浏览器中执行的 JavaScript 函数。
CPython 团队提供了两种口味的 WASM 解释器二进制,分别用 emscripten 与 WASI SDK 编译。两者虽然都产出 WebAssembly 代码,但它们在"由宿主提供哪些 JavaScript 函数"这一关键特性上差异很大:
| 编译工具链 | 特点 | 宿主职责 |
|---|---|---|
| emscripten | 特别聚焦于 Web 平台与 Node.js 环境 | 除生成 WASM 代码外,还会生成一份充当宿主的 JavaScript 代码,负责在浏览器或 Node.js 中执行 WASM;例如它提供函数把 C 语言 printf 的内容打印到浏览器控制台 |
| WASI SDK | 将 C/C++ 代码编译为 WASM,并要求宿主实现符合 WASI 规范 | 只生成 WebAssembly 代码,不生成任何 JavaScript 函数;打印 printf 内容所需的 JavaScript 函数必须由宿主提供,例如 Wasmtime 这类运行时会把 WASI 对接到底层操作系统调用上 |
WASI 全称 WebAssembly System Interface(WebAssembly 系统接口),它定义了若干类操作系统能力,包括文件与文件系统、套接字、时钟、随机数等。VS Code 团队最终选择支持 WASI,理由是:虽然 VS Code 的首要场景是在浏览器中执行 WASM,但实际并不是在纯浏览器环境运行,而是必须在 VS Code 的扩展宿主 worker(extension host worker)中运行——这是 VS Code 标准扩展机制的承载环境。扩展宿主 worker 除浏览器 worker API 外,还拥有完整的 VS Code 扩展 API。因此,目标不是把 C/C++ 程序的 printf 接到浏览器控制台,而是接到 VS Code 的 Terminal API 上。这一点在 WASI 下实现比在 emscripten 下容易得多。
需要注意的版本前提:VS Code 当前对 WASI 宿主的实现基于 WASI snapshot preview1,本文描述的所有实现细节均针对该版本。
运行自己的 WebAssembly 代码:从 C 源码到扩展
在 Python 跑通之后,VS Code 团队意识到这套方案可以执行任何能编译到 WASI 的代码。下面演示如何用 WASI SDK 把一个小型 C 程序编译为 WASI,并在 VS Code 扩展宿主中执行。该示例假定读者已熟悉 VS Code 扩展 API,并知道如何为 VS Code for the Web 编写扩展。
首先是一个简单的 "Hello World" C 程序:
#include <stdio.h>
int main(void)
{
printf("Hello, World\n");
return 0;
}
假设已安装最新版 WASI SDK 且其位于 PATH 中,可用如下命令编译:
clang hello.c -o ./hello.wasm
该命令会在 hello.c 旁边生成 hello.wasm 文件。
VS Code 的新特性都通过扩展引入,WebAssembly 的集成也遵循同一模型:需要定义一个扩展来加载并运行 WASM 代码。扩展 package.json 清单的关键部分如下:
{
"name": "...",
...,
"extensionDependencies": [
"ms-vscode.wasm-wasi-core"
],
"contributes": {
"commands": [
{
"command": "wasm-c-example.run",
"category": "WASM Example",
"title": "Run C Hello World"
}
]
},
"devDependencies": {
"@types/vscode": "1.77.0",
},
"dependencies": {
"@vscode/wasm-wasi": "0.11.0-next.0"
}
}
清单中两个关键依赖各司其职:
ms-vscode.wasm-wasi-core:作为extensionDependencies声明的扩展,提供 WebAssembly 执行引擎,负责把 WASI API 对接(wire)到 VS Code API 上;@vscode/wasm-wasi:一个 npm 模块,提供在 VS Code 中加载和运行 WebAssembly 代码的门面(facade)API。
下面是实际加载并运行 WebAssembly 代码的 TypeScript 代码:
import { Wasm } from '@vscode/wasm-wasi';
import { commands, ExtensionContext, Uri, window, workspace } from 'vscode';
export async function activate(context: ExtensionContext) {
// Load the WASM API
const wasm: Wasm = await Wasm.load();
// Register a command that runs the C example
commands.registerCommand('wasm-wasi-c-example.run', async () => {
// Create a pseudoterminal to provide stdio to the WASM process.
const pty = wasm.createPseudoterminal();
const terminal = window.createTerminal({ name: 'Run C Example', pty, isTransient: true });
terminal.show(true);
try {
// Load the WASM module. It is stored alongside the extension's JS code.
// So we can use VS Code's file system API to load it. Makes it
// independent of whether the code runs in the desktop or the web.
const bits = await workspace.fs.readFile(Uri.joinPath(context.extensionUri, 'hello.wasm'));
const module = await WebAssembly.compile(bits);
// Create a WASM process.
const process = await wasm.createProcess('hello', module, { stdio: pty.stdio });
// Run the process and wait for its result.
const result = await process.run();
if (result !== 0) {
await window.showErrorMessage(`Process hello ended with error: ${result}`);
}
} catch (error) {
// Show an error message if something goes wrong.
await window.showErrorMessage(error.message);
}
});
}
这段代码的核心调用链值得拆解:
Wasm.load()加载 WASM API,建立与wasm-wasi-core执行引擎的连接;wasm.createPseudoterminal()创建伪终端,为 WASM 进程提供 stdio;window.createTerminal({ ..., pty, isTransient: true })将伪终端挂接到 VS Code 的终端 UI;- 通过
workspace.fs.readFile读取扩展自带的hello.wasm——之所以用 VS Code 文件系统 API 而非 Node 的fs,是为了让代码在桌面端与 Web 端行为一致; WebAssembly.compile(bits)编译字节码,wasm.createProcess(...)创建 WASM 进程;process.run()运行进程并等待退出码,非零则弹出错误提示。
虽然示例用 C/C++ 作为 WebAssembly 的源码,但因为 WASI 是标准规范,还有多种支持 WASI 的工具链可以选用,例如 Rust、.NET 以及 Swift 等。
VS Code 的 WASI 实现:把同步 WASM 映射到异步 VS Code API
WASI 与 VS Code API 在概念上高度重合——两者都有文件系统、stdio(例如终端)等抽象,这让 VS Code 可以在 VS Code API 之上实现 WASI 规范。真正的挑战来自执行行为的不同:
- WebAssembly 代码执行是同步的:一旦 WASM 执行开始,JavaScript worker 就会被阻塞,直到执行结束;
- 而 VS Code API 与浏览器 API 绝大部分是异步的,例如 WASI 中读文件是同步操作,对应的 VS Code API 却是异步的。
这一特性给在 VS Code 扩展宿主 worker 中执行 WASM 带来两个问题:
- 必须防止扩展宿主在执行 WASM 时被阻塞——否则其他扩展将无法执行;
- 需要一种机制,在异步的 VS Code 与浏览器 API 之上实现同步的 WASI API。
第一个问题容易解决:把 WebAssembly 代码放到单独的 worker 线程中运行。第二个问题则棘手得多,因为"把同步代码映射到异步代码"需要能挂起正在同步执行的线程,并在异步结果就绪时恢复它。
WebAssembly 的 JavaScript-Promise Integration 提案正是从 WASM 层解决该问题的方案,V8 中也有该提案的实验性实现;但 VS Code 团队启动这项工作时 V8 的实现尚未就绪。于是他们选择了另一条实现路径:用 SharedArrayBuffer + Atomics 把同步的 WASI API 映射到 VS Code 的异步 API 上。
整个方案的工作流程如下:
- WASM worker 线程创建一个
SharedArrayBuffer,写入需要在 VS Code 侧调用的代码相关信息; - 它把共享内存 post 给 VS Code 的扩展宿主 worker,然后用
Atomics.wait挂起等待扩展宿主 worker 完成工作; - 扩展宿主 worker 取出消息,调用相应的 VS Code API,把结果写回
SharedArrayBuffer,再用Atomics.store与Atomics.notify通知 WASM worker 线程唤醒; - WASM worker 从
SharedArrayBuffer中读取结果数据,返回给 WASI 回调。
这种方案唯一的难点在于:SharedArrayBuffer 与 Atomics 要求站点具备跨源隔离(cross-origin isolated)能力,而 CORS 具有极强的"传染性",配置跨源隔离本身就是一项工程。因此该特性当时默认只在 Insiders 版本(insiders.vscode.dev)上启用,在 vscode.dev 上需要通过查询参数 ?vscode-coi=on 手动开启。
下图详细展示了上述 C 程序被编译为 WebAssembly 后,WASM worker 与扩展宿主 worker 之间的完整交互:橙色框内是 WebAssembly 代码,绿色框内全部运行在 JavaScript 中,黄色框代表 SharedArrayBuffer。
仓库内的发布记录佐证了这条演进路径:在 VS Code 1.83 的发布说明中(release-notes/v1_83.md),跨源隔离已在 vscode.dev 上默认启用,这为共享数组缓冲区(shared array buffers)、跨文件 TypeScript 支持、Web 端 Python 执行以及 vscode-wasm-wasi 这类能力提供了基础。更早的 VS Code 1.72 发布说明(release-notes/v1_72.md)则记录了这项工作最初的形态:@vscode/sync-api-common、@vscode/sync-api-client、@vscode/sync-api-service 与 @vscode/wasm-wasi 等 npm 库,以及"Experimental - Python for the Web"扩展的引入。
Web Shell:把 Unix 命令行搬进浏览器
在成功把 C/C++ 与 Rust 代码编译为 WebAssembly 并在 VS Code 中执行之后,VS Code 团队进一步探索:能否在 VS Code for the Web 中运行一个 shell?
他们最初尝试把某个 Unix shell 编译为 WebAssembly,但部分 shell 依赖的操作系统特性(例如派生进程)在当时的 WASI 中尚不可用。于是团队换了个思路:用 TypeScript 实现一个基础 shell,只把 ls、cat、date 等 Unix 核心工具编译为 WebAssembly。由于 Rust 对 WASM 与 WASI 的支持非常成熟,团队选用了 uutils/coreutils——一个用 Rust 对 GNU coreutils 的跨平台重实现。就这样,第一个极简 Web Shell 诞生了。
一个无法执行自定义 WebAssembly 或命令的 shell 是极其受限的。为了扩展 Web Shell,其他扩展可以向文件系统贡献额外的挂载点(mount points),也可以贡献命令——当用户在 Web Shell 中输入这些命令时就会被调用。通过命令这一间接层,具体的 WebAssembly 执行与终端中输入的内容被解耦。Python 扩展从一开始就使用了这套机制:在 shell 提示符中输入 python app.py 即可直接执行 Python 代码,也可以列出通常挂载在 /usr/local/lib/python3.11 下的 Python 3.11 标准库。
局限与展望:实验性技术的边界与演进方向
需要特别说明的是,WASM 执行引擎扩展与 Web Shell 扩展都处于预览(preview)实验阶段,官方不建议用它来实现生产级扩展。它们被公开展示是为了尽早获得社区对这项技术的反馈。仓库中 Python for the Web 的官方文档(docs/python/python-web.md)也明确列出了当时解释器侧的若干限制:不支持套接字、不支持线程(因而没有异步支持)、不支持 pip、不支持原生 Python 模块;使用前提包括浏览器支持跨源隔离、通过 ?vscode-coi= 查询参数启动 VS Code for the Web 等。
围绕该主题,VS Code 团队规划了以下演进方向:
- WASI preview2 / preview3:WASI 团队正在推进规范的 preview2 与 preview3,VS Code 计划一并支持;新版本会改变 WASI 宿主的实现方式,但团队有信心让执行引擎扩展暴露的 API 基本保持稳定。
- WASIX:一个为 WASI 扩展进程、futex 等额外操作系统类特性的项目,VS Code 团队将持续关注。
- 语言服务器上 Web:VS Code 的许多语言服务器并非用 JavaScript/TypeScript 实现,团队计划探索把这些语言服务器编译为
wasm32-wasi并在 VS Code for the Web 中运行。 - Web 端 Python 调试:团队已着手改善 Web 端 Python 调试体验。
- 扩展间 WASM 复用:支持扩展 B 运行扩展 A 贡献的 WebAssembly 代码,例如让任意扩展复用贡献了 Python WebAssembly 的扩展来执行 Python 代码。
- 更多语言运行时:确保其他编译为
wasm32-wasi的语言运行时能运行在 VS Code 的 WebAssembly 执行引擎之上——VMware Labs 提供的 Ruby 与 PHPwasm32-wasi二进制均已验证可在 VS Code 中运行。
这些规划在仓库后续文档中得到了印证:VS Code 1.84 发布说明(release-notes/v1_84.md)提到实验性的 wasm-wasi-core 扩展增加了对 WASM/WASI 语言服务器的支持;VS Code 1.93 发布说明(release-notes/v1_93.md)则宣布 wasm-wasi-core 扩展与 @vscode/wasm-wasi、@vscode/wasm-component-model npm 模块发布了 1.0 版本;后续两篇博客 wasm.md 与 wasm-part2.md 进一步展示了基于 Component Model 与 WASI 0.2 的扩展开发方式、在独立 worker 中执行 WASM 以避免阻塞扩展宿主主线程,以及基于 WebAssembly 的 LSP 语言服务器等进阶用法。
总而言之,本文所阐述的 WASI Preview 1 方案确立了 VS Code 在浏览器中运行通用语言运行时的可行性基线:以扩展宿主 worker 为宿主、以 SharedArrayBuffer + Atomics 桥接同步与异步、以 wasm-wasi-core 执行引擎为标准接入点。对扩展开发者而言,编译到 wasm32-wasi 并借助 @vscode/wasm-wasi 门面 API 加载运行,是让代码同时在桌面端与 Web 端保持一致行为的最直接路径。
Happy Coding!
