在 VS Code for the Web 中运行 WebAssembly:WASI 执行引擎原理与扩展开发实战

原创2026-10-08 19:32:112,191 阅读
文章标签:文档教程

在 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);
        }
    });
}

这段代码的核心调用链值得拆解:

  1. Wasm.load() 加载 WASM API,建立与 wasm-wasi-core 执行引擎的连接;
  2. wasm.createPseudoterminal() 创建伪终端,为 WASM 进程提供 stdio;
  3. window.createTerminal({ ..., pty, isTransient: true }) 将伪终端挂接到 VS Code 的终端 UI;
  4. 通过 workspace.fs.readFile 读取扩展自带的 hello.wasm——之所以用 VS Code 文件系统 API 而非 Node 的 fs,是为了让代码在桌面端与 Web 端行为一致;
  5. WebAssembly.compile(bits) 编译字节码,wasm.createProcess(...) 创建 WASM 进程;
  6. 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 带来两个问题:

  1. 必须防止扩展宿主在执行 WASM 时被阻塞——否则其他扩展将无法执行;
  2. 需要一种机制,在异步的 VS Code 与浏览器 API 之上实现同步的 WASI API。

第一个问题容易解决:把 WebAssembly 代码放到单独的 worker 线程中运行。第二个问题则棘手得多,因为"把同步代码映射到异步代码"需要能挂起正在同步执行的线程,并在异步结果就绪时恢复它。

WebAssembly 的 JavaScript-Promise Integration 提案正是从 WASM 层解决该问题的方案,V8 中也有该提案的实验性实现;但 VS Code 团队启动这项工作时 V8 的实现尚未就绪。于是他们选择了另一条实现路径:用 SharedArrayBuffer + Atomics 把同步的 WASI API 映射到 VS Code 的异步 API 上。

整个方案的工作流程如下:

  1. WASM worker 线程创建一个 SharedArrayBuffer,写入需要在 VS Code 侧调用的代码相关信息;
  2. 它把共享内存 post 给 VS Code 的扩展宿主 worker,然后用 Atomics.wait 挂起等待扩展宿主 worker 完成工作;
  3. 扩展宿主 worker 取出消息,调用相应的 VS Code API,把结果写回 SharedArrayBuffer,再用 Atomics.store 与 Atomics.notify 通知 WASM worker 线程唤醒;
  4. 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。

WASM worker 与扩展宿主之间通过 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 与 PHP wasm32-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!

登录后查看全文
vscode-docs