如何在3分钟内给React项目嵌入Web终端：wterm快速上手教程

如何在3分钟内给React项目嵌入Web终端：wterm快速上手教程

【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm

wterm 是一款面向浏览器的 Web 终端模拟器（terminal emulator for the web），核心用 Zig 编写并编译为约 26 KB 的 WASM，配合 React 组件可在几分钟内给任意 React 项目加上一个支持文本选择、复制粘贴、24 位颜色与主题切换的完整终端。本文将带你走通安装、接入和输入控制的完整流程，零后端即可先跑起来。

wterm 是什么？为什么值得用

与传统基于 Canvas 的方案不同，wterm 直接渲染到 DOM，带来几个天然优势：

• 🖱️原生交互：文字选择、复制粘贴、浏览器查找、读屏器无障碍直接可用
• 🚀高性能：Zig + WASM 核心，脏行追踪（dirty-row tracking）只重绘变化的行
• 🎨内置主题：Default、Solarized Dark、Monokai、Light，支持 CSS 变量自定义
• 🧩多框架绑定：官方提供 React、Vue 3、Svelte 组件
• 🔗完整 VT 支持：VT100/VT220/xterm 转义序列、OSC 8 超链接、宽字符（CJK/emoji）、备用屏幕（vim、htop 等 TUI 程序可正常工作）

各包职责一目了然（完整说明见 README.md）：

包名	用途
@wterm/core	无头 WASM 桥接 + WebSocket 传输
@wterm/dom	DOM 渲染器，原生 JS 终端
@wterm/react	React 组件 +useTerminalhook
@wterm/just-bash	纯浏览器内运行的 Bash 壳

第 1 步：安装 React 终端依赖（约 30 秒）

在 React 项目根目录执行：

npm install @wterm/dom @wterm/react

💡 如果项目是 Next.js，记得在next.config.mjs中把两个包加入transpilePackages（原因见下文"Next.js 项目额外配置"）。

WASM 二进制已内嵌在包里，无需任何额外配置即可运行。

第 2 步：3 行代码渲染终端

导入<Terminal>组件和样式表，放入页面即可：

import { Terminal } from "@wterm/react"; import "@wterm/react/css"; function App() { return <Terminal />; }

刷新页面，一个 80×24 的终端就出现了。此时直接敲键盘，输入会原样回显到终端（echo 模式）。完整最小示例可参考官方文档 react.mdx 与 get-started.mdx。

第 3 步：接管键盘输入（onData 实战）

真正连接后端或脚本时，需要用useTerminalhook 接管输入。官方 React 包 README 给出的标准写法：

import { Terminal, useTerminal } from "@wterm/react"; import "@wterm/react/css"; function App() { const { ref, write } = useTerminal(); return ( <Terminal ref={ref} onData={(data) => { socket.send(data); // 把键盘输入发给你的 WebSocket 后端 }} /> ); }

useTerminal返回的四个成员覆盖了几乎所有控制场景（详见 README）：

成员	作用
ref	传给<Terminal ref={ref}>
write(data)	向终端写入内容（字符串或二进制）
resize(cols, rows)	调整终端尺寸
focus()	聚焦终端

常用配置速查

<Terminal>支持的关键 Props（完整表格见 react.mdx）：

Prop	默认值	说明
cols/rows	80 / 24	初始行列数
theme	—	"solarized-dark"、"monokai"、"light"
autoResize	false	跟随容器自动调整尺寸
wasmUrl	—	改为独立静态文件加载 WASM（利于 CDN 缓存）
onData	回显	处理输入；不传则自动 echo
onTitle/onBell/onResize/onReady	—	标题、响铃、尺寸、就绪回调

切换主题只需一行：<Terminal theme="monokai" />。自定义主题通过 CSS 变量--term-fg、--term-bg、--term-color-0～--term-color-15实现。

Next.js 项目额外配置

Next.js 需要在配置中声明两个包，否则构建会报 ESM 相关错误：

// next.config.mjs const nextConfig = { transpilePackages: ["@wterm/dom", "@wterm/react"], };

零后端体验：搭配 just-bash

想让终端"真的能执行命令"而不用写一行服务端代码？@wterm/just-bash提供一个完全跑在浏览器里的 Bash 壳。官方 Next.js 示例的接线逻辑非常简洁（源码见 page.tsx）：

const shell = new BashShell({ greeting: ["Hello from wterm!"] }); shell.attach(write); // 输出 → 终端 // <Terminal onData={(data) => shell.handleInput(data)} /> 输入 → 壳

支持ls、cat等命令、Ctrl+R 历史搜索、Tab 补全。想本地跑起官方演示：

git clone https://gitcode.com/gh_mirrors/wterm1/wterm cd wterm && pnpm install && zig build pnpm --filter nextjs dev

进阶方向

完成 3 分钟接入后，可以按需求继续扩展：

• 连接真实 PTY：用@wterm/core的 WebSocket 传输对接服务端 PTY，实现 SSH 远程终端（参考示例 examples/ssh/README.md）
• 满血 VT 兼容：换用@wterm/ghostty内核，支持 Kitty 图像协议、组合字符等高级特性（ghostty 文档）
• 终端里渲染 Markdown：@wterm/markdown包
• API 全量参考：api-reference.mdx、configuration.mdx

wterm 以极小的 WASM 体积换来了接近原生终端的能力，无论是做 IDE 内嵌终端、AI 聊天命令行，还是教学演示，都是一个轻量又完整的选择。

【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm