wterm：由 Zig 与 WASM 提供动力的高速网页终端模拟器

Introduction

如果你曾经需要在网页应用中嵌入终端——无论是用于云 IDE、远程 Shell 仪表盘，还是交互式教程——wterm 正是你一直在等的工具。由 Vercel Labs 开发，wterm 是一个完整功能的终端模拟器，使用 Zig 编译的 WebAssembly 在浏览器中运行。其体积小（核心 WASM 二进制约 12 KB）且性能接近原生，适用于任何现代网页技术栈。

Why wterm Stands Out

Feature	Benefit
Zig + WASM core	VT100/VT220/xterm 转义序列的近原生解析速度。
Pluggable cores	可选择超轻量的 Zig 核心（约 12 KB）或功能完整的 libghostty 后端（约 400 KB），实现完整的 VT 兼容。
DOM rendering	原生文本选择、复制/粘贴、浏览器查找以及屏幕阅读器支持，无需额外库。
Framework wrappers	为 React、Vue 3 以及原生 JS API 提供即用包装。
Theming	CSS 自定义属性让你可以即时在 Default、Solarized Dark、Monokai、Light 主题之间切换。
WebSocket transport	通过二进制帧和自动重连连接远程 PTY 后端。
Auto‑resize	使用 `ResizeObserver` 适配容器尺寸变化。
Scrollback & alternate screen	完全支持 `vim`、`less`、`htop` 等应用。

这些特性使 wterm 不仅仅是演示，它是可以在任何网页项目中嵌入的生产级组件。

Getting Started

Prerequisites

Zig 0.16.0+（用于构建 WASM 核心）
Node.js 20+
pnpm 10+（推荐的包管理器）

Installation

# Clone the repository
git clone https://github.com/vercel-labs/wterm.git
cd wterm

# Install JavaScript dependencies
pnpm install

Build the WASM Binary

zig build               # 调试构建（默认）
zig build -Doptimize=ReleaseSmall   # 生产体积构建（约 12 KB）

生成的 wterm.wasm 文件位于 web/ 目录，可作为静态资源提供。

Build All Packages

pnpm run build   # 编译 @wterm/* 包并打包示例

Using wterm in Different Environments

1. Vanilla JavaScript (DOM Renderer)

<script type="module">
  import { createTerminal } from "https://cdn.jsdelivr.net/npm/@wterm/dom";
  const term = createTerminal({ wasmUrl: "/wterm.wasm" });
  term.attach(document.getElementById('terminal'));
</script>
<div id="terminal" style="height:400px; width:100%;"></div>

DOM 渲染器为你提供一个纯 JS 终端，具备完整的剪贴板支持和原生文本选择功能。

2. React Integration

import { WTermReact } from "@wterm/react";

export default function App() {
  return (
    <WTermReact
      wasmUrl="/wterm.wasm"
      className="my-terminal"
      onData={data => console.log('User typed:', data)}
    />
  );
}

useTerminal Hook 让你可以与底层 PTY 交互，发送指令并监听输出。

3. Vue 3 Component

<template>
  <WTermVue :wasm-url="'/wterm.wasm'" />
</template>
<script setup>
import { WTermVue } from '@wterm/vue';
</script>

Vue 开发者可以获得一个遵循响应式系统的简易组件，随时可放置在组件树的任意位置。

Advanced Features

Theming with CSS Variables

:root {
  --wterm-bg: #1e1e1e;          /* 背景 */
  --wterm-fg: #d4d4d4;          /* 前景 */
  --wterm-cursor: #ffcc00;     /* 光标 */
}

运行时更新这些变量即可切换主题，终端会即时刷新，无需重新加载。

Connecting to a Remote PTY via WebSocket

import { createTerminal } from '@wterm/core';
const term = createTerminal({
  wasmUrl: '/wterm.wasm',
  transport: new WebSocketTransport('wss://my-pty-server.example.com')
});
term.attach(document.body);

内置的传输层处理二进制帧、自动重连以及流控，非常适合基于云的开发环境。

Using the libghostty Backend

如果你需要完整的 VT100/VT220 兼容（例如运行 tmux 等复杂应用），可以安装 @wterm/ghostty 包：

pnpm add @wterm/ghostty

然后在创建终端时使用 ghostty 核心：

import { createTerminal } from '@wterm/core';
import { GhosttyCore } from '@wterm/ghostty';

const term = createTerminal({
  core: new GhosttyCore(),
  wasmUrl: '/wterm.wasm'
});

额外约 400 KB 的负载带来完整的 VT 兼容，包括 24 位颜色和高级线条绘制。

Real‑World Use Cases

云 IDE – 将 wterm 嵌入 Gitpod、CodeSandbox 或自建 SaaS IDE 作为内置 Shell。
文档与教程 – 在文档中直接渲染实时命令行演示，无需本地终端。
监控面板 – 在管理后台展示实时日志或交互式 CLI 工具。
教育平台 – 为学生提供沙箱 Shell，学习 Linux 命令。

Contributing & Community

wterm 在 Apache‑2.0 许可证下开源，欢迎贡献：

Bug 报告 – 在 GitHub 上打开 Issue。
功能请求 – 通过 Pull Request 提出改进。
文档 – 改进 README、添加示例或编写教程。

项目使用 Playwright 进行端到端测试（e2e 目录）和 Vitest 进行跨包单元测试。运行测试套件只需：

pnpm test

Conclusion

wterm 填补了原生终端体验与现代网页应用之间的空白。其基于 Zig 的 WASM 核心提供高速性能，而一整套（vanilla、React、Vue、Ghostty）包装确保无论使用何种技术栈都能无缝集成。无论你在构建云 IDE、交互式教程，还是远程 Shell 仪表盘，wterm 都能为你提供可靠、可扩展且开源的解决方案。

准备好尝试了吗？ 克隆仓库，构建 WASM 二进制，几分钟即可嵌入终端。加入日益壮大的开发者社区，把命令行的力量带到浏览器中。