wterm本地Shell教程：浏览器里的完整本地终端（node-pty多会话实战）

wterm本地Shell教程浏览器里的完整本地终端node-pty多会话实战【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wtermwterm 是一款面向 Web 的终端模拟器terminal emulator for the web核心用 Zig 编写并编译为约 26 KB 的 WASM直接渲染到 DOM原生支持文本选择、复制粘贴、浏览器查找和 24 位色。本文基于 wterm 仓库中的 Local Shell 示例手把手教你用 node-pty WebSocket 在浏览器里跑起一台真实的本地 Shell并管理多个互不干扰的终端会话。一、为什么需要浏览器里的本地终端传统浏览器终端方案通常依赖 Canvas 渲染而 wterm 选择 DOM 渲染带来两个直接好处原生文本能力选择、复制、CtrlF 查找、屏幕阅读器直接作用于已挂载的行元素即插即用的框架组件React、Vue、Svelte 组件开箱即用见 packages/wterm/react、packages/wterm/vue、packages/wterm/svelte。wterm 的完整特性清单24 位色、Kitty 图片、Kitty 键盘协议、宽字符对齐等可以查阅 README.md。二、Local Shell 示例架构一句话讲清本项目的examples/local是一个 Next.js 应用旁边跑着一个自定义服务器用WebSocket 把浏览器和 node-pty 桥接起来浏览器里的每个终端标签页向/api/terminal发起 WebSocket 连接服务器为每个连接用 node-pty 生成一个 PTY 进程加载你的默认登录 Shell你在浏览器敲下的每个键经 WebSocket 发给服务器写入 PTYPTY 输出再经 WebSocket 回传由 wterm 渲染到页面。核心源码就两个文件非常值得精读服务端桥接examples/local/server.ts前端多会话工作区examples/local/app/session-workspace.tsx三、三步启动一键运行本地 Shell 前置要求Zig 0.16、Node.js 24、pnpm 11详见 README.md 的 Development 章节。git clone https://gitcode.com/gh_mirrors/wterm1/wterm cd wterm pnpm install zig build pnpm --filter local dev启动后浏览器打开local-example.wterm.localhost开发服务器通过 portless 分配地址若提示缺失可执行npm i -g portless即可看到一个左侧为会话列表、右侧为终端的完整本地 Shell 界面。⚠️ 注意Linux 上 node-pty 需要 C/Python 编译工具链见 README.md。四、多会话实战创建、切换、关闭三个按钮全搞定打开页面后体验 wterm 的多会话能力只需三个动作操作位置效果➕ 新建侧边栏右上角加号新增一个独立 PTY 独立终端自动获得焦点切换点击侧边栏任意会话项终端画面切换其他会话保持存活正在跑的任务不中断✖ 关闭悬停会话项右侧销毁该会话的 WebSocket 与 PTY 进程侧边栏每个会话项还会实时显示当前工作目录家目录缩写为~服务端每 500ms 轮询一次 PTY 进程的 cwdLinux 读/proc/pid/cwdmacOS 用 lsof你在终端里cd之后侧边栏标签会同步更新——实现见 examples/local/server.ts。切换会话时旧终端只是被visibility: hiddeninert遮住而非销毁examples/local/app/session-workspace.tsx所以你在 Terminal 1 里挂着htop切去 Terminal 2 干完活再切回来画面分毫未动。五、node-pty 桥接细节终端尺寸如何同步一个常见痛点浏览器窗口缩放后PTY 的列/行数必须跟着变否则vim、ls输出会错位。wterm 示例的做法很优雅前端通过onResize回调拿到核心实际应用的网格尺寸再拼一条自定义转义序列\x1b[RESIZE:cols;rows;像素宽;像素高]发给服务器examples/local/app/session-workspace.tsx服务器解析该序列后调用ptyProcess.resize(cols, rows)同时把像素尺寸写入 PTYmacOS/Linux 下通过 ioctl这样连按像素探测终端的工具也能正确工作examples/local/server.ts。由于 wterm 的autoResize基于 ResizeObserver窗口变化会即时触发onResize整条链路无需手动干预。六、进阶玩法 图形能力更强的 Ghostty 核心访问/ghostty路由终端切换为带图形能力的wterm/ghosttylibghostty 后端Kitty 图片协议可渲染 PNG/RGB 图像示例中限制在 640×480 CSS 像素内入口见 examples/local/app/ghostty/page.tsx。调试模式URL 加?debug参数可在 WTerm 实例上打开DebugAdapter检查转义序列、单元格数据与渲染性能examples/local/app/session-workspace.tsx。换主题给Terminal传themesolarized-dark/monokai/light即可文档见 packages/wterm/react/README.md。七、常见问题速查Q为什么打不开页面所有开发服务器使用 portless请留意终端里打印的实际.localhost地址而非写死的端口。QLinux 下 node-pty 安装失败需要 C 与 Python 工具链用于编译原生模块先装好再pnpm install。Q会话关闭后进程会泄漏吗不会。WebSocket 断开时服务器会立即ptyProcess.kill()并清理 cwd 轮询定时器examples/local/server.ts。八、小结wterm 的 Local Shell 示例用不到 500 行代码演示了一套完整的浏览器本地终端方案node-pty 负责真实 ShellWebSocket 负责双向传输wterm 负责高性能 DOM 渲染React 负责多会话状态管理。照着本文的三步启动命令跑起来你就能在浏览器标签页里拥有任意多个互不干扰的本地 Shell——这正是把开发环境搬进 Web 的第一步。【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考