如何用WebSocket把wterm Web终端连上真实ShellWebSocketTransport完全指南【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wtermwterm 是一个面向 Web 的终端模拟器而WebSocketTransport是它内置的 WebSocket 传输层——用几行代码就能把浏览器里的 wterm Web 终端连接到服务端的真实 ShellPTY实现打字、回显、重连一气呵成。本指南面向新手带你从零理解它的工作原理、完整配置和常见坑位。为什么 Web 终端需要 WebSocket浏览器里的终端本质上只是画面上的一层字它背后没有任何真正的进程。想让它执行ls、vim这样的命令必须有一条通往服务端的管道上行你敲下的按键含转义序列、鼠标事件下行Shell 输出的字节流含 ANSI 转义WebSocket 全双工、低延迟、天然适合这种双向实时字节流场景因此成为 Web 终端的事实标准。wterm 在wterm/core包里内置了WebSocketTransport类源码位于 packages/wterm/core/src/transport.ts零 DOM 依赖可配合任意框架使用。30秒上手最简连接代码安装并引入两个类完成终端 ↔ WebSocket ↔ PTY的接线import { WTerm, WebSocketTransport } from wterm/dom; const term new WTerm(document.getElementById(terminal), { cols: 80, rows: 24 }); await term.init(); const ws new WebSocketTransport({ url: ws://localhost:8080/pty, onData: (data) term.write(data), // 服务端 - 终端 }); ws.connect(); term.onData (data) ws.send(data); // 终端 - 服务端整个接线只有两行核心代码ws.onData - term.write和term.onData - ws.send数据就这样在浏览器和真实 Shell 之间双向流动。WebSocketTransport 配置选项速查选项类型默认值作用urlstring—WebSocket 服务端地址reconnectbooleantrue断线后是否自动重连maxReconnectDelaynumber30000重连最大间隔毫秒onDatacallback—收到服务端数据时触发onOpen/onClose/onErrorcallback—连接状态回调完整字段定义见 packages/wterm/core/src/transport.ts官方参考文档在 apps/docs/content/docs/api-reference.mdx 的WebSocketTransport一节。三个让连接更稳的内置机制1. 指数退避自动重连默认reconnect: true断线后按 1s → 2s → 4s … 逐次加倍重试直到触达maxReconnectDelay上限默认 30 秒成功后延迟计数器自动归零。相关实现见_scheduleReconnect方法transport.ts。new WebSocketTransport({ url: wss://example.com/pty, reconnect: true, // 可设为 false 关闭 maxReconnectDelay: 10000, });2. 未连接时的发送缓冲在 WebSocket 还没打开CONNECTING 状态时调用send()数据不会丢失而是进入内部缓冲区连接建立后按序自动补发_flushBuffer见 transport.ts。这意味着页面加载慢、网络抖动时用户提前敲下的输入也能完整送达 Shell。3. 二进制与文本双通道传输层统一设置binaryType arraybuffer收到二进制帧自动转为Uint8Array字符串帧原样透传transport.ts。onData回调里两种类型都可能出现写终端时用term.write(data)即可同时兼容。服务端要准备什么一个最小 PTY 后端wterm 官方提供了完整示例examples/local/server.ts。它用node-pty派生登录 Shell通过ws库的WebSocketServer在/api/terminal路径上处理连接核心逻辑很简单收到RESIZE转义序列时创建/调整 PTY 尺寸pty.onData的输出原样发回浏览器浏览器消息写入ptyProcess连接关闭时kill()掉 PTY 进程 注意官方示例用 JSON 包装{type:output,data:...}以便额外推送工作目录等信息如果你只要纯字节流直接透传即可WebSocketTransport对两种格式都不设限。常见坑与排查清单HTTPS 页面连ws://会被浏览器拦截—— 生产环境务必用wss://resize不同步导致错行—— 把WTerm的onResize转发给服务端用 PTY 的resize(cols, rows)同步尺寸重连后 Shell 会话丢失—— 传输层只负责重连网络会话状态需服务端自己维护重连后重新 spawn 或复用主动close()后仍会重连—— 不会close()会标记内部_closed状态并取消定时器彻底停止重连transport.ts延伸阅读使用文档apps/docs/content/docs/vanilla.mdxWebSocket Transport 章节包说明packages/wterm/core/README.md单元行为验证packages/wterm/core/src/tests/websocket-transport.test.ts覆盖缓冲、重连退避、上限等全部机制掌握WebSocketTransport后你的浏览器里就有一个真终端了——vim、htop、python想跑就跑断网也不慌。【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考