Node.js TTY模块：ReadStream与WriteStream终端交互开发教程-代码号

一、TTY模块在Node.js中的定位

Node.js的tty模块提供了终端设备的底层抽象能力，主要包含两个类：tty.ReadStream和tty.WriteStream。多数业务场景下，开发者并不需要直接引入这个模块，因为Node.js在检测到标准输入输出处于TTY上下文时，已经自动将process.stdin和process.stdout初始化为对应实例。

引入方式如下：

var tty = require('tty');

当Node.js判断当前运行环境属于TTY上下文时，会出现两个默认行为：

process.stdin是tty.ReadStream的实例；
process.stdout是tty.WriteStream的实例。

判断当前进程是否运行在TTY上下文，可以用一行命令验证：

node -p -e "Boolean(process.stdout.isTTY)"

如果输出true，说明标准输出连接的是终端设备；输出false，通常意味着输出被重定向到文件或管道。这个判断在编写CLI工具时很关键，因为终端交互逻辑只在真实TTY环境下才有意义。

经验提示：很多终端程序在CI环境或重定向场景下行为异常，根源往往是没有先判断isTTY。直接调用setRawMode可能抛出错误，建议先做环境检测。

二、tty.ReadStream可读流

tty.ReadStream继承自net.Socket，表示TTY的可读部分。在常规Node.js程序中，它通常只有一个实例，即process.stdin，前提是isatty(0)为真。

isRaw属性

rs.isRaw是一个布尔值，初始为false，用于标识当前tty.ReadStream实例是否处于“原始”状态。

setRawMode方法

rs.setRawMode(mode)接受true或false：

传入true：将流设置为原始设备模式；
传入false：恢复为默认模式。

调用后，isRaw会被设置为传入的模式值。

原始模式的意义在于：终端默认会缓冲输入并按行处理，某些按键组合会被终端驱动拦截。开启原始模式后，按键可以逐个被程序读取，适合实现快捷键、游戏控制、交互式命令行等场景。

process.stdin.setRawMode(true);
process.stdin.resume();

这两行代码是终端按键监听的基础。resume()让流进入流动模式，否则数据不会被读取。

注意事项：原始模式下，Ctrl+C不再自动终止进程，需要程序自行处理退出逻辑。这是很多初学者容易忽略的地方。

三、tty.WriteStream可写流

tty.WriteStream同样继承自net.Socket，表示TTY的可写部分，通常对应process.stdout，前提是isatty(1)为真。

resize事件

当终端窗口的列数或行数发生变化时，process.stdout会触发resize事件：

process.stdout.on('resize', () => {
  console.log('screen size has changed!');
  console.log(`${process.stdout.columns}x${process.stdout.rows}`);
});

columns与rows

ws.columns：当前TTY的列数；
ws.rows：当前TTY的行数。

这两个属性会在resize事件触发时更新。对于需要根据终端尺寸调整输出布局的程序，比如表格渲染、进度条、终端仪表盘，监听resize是必要操作。

反思：早期写终端表格工具时，没有监听resize，用户调整窗口后输出错位。后来加上尺寸监听并重绘，体验明显改善。终端尺寸不是常量，而是动态值。

四、可运行示例：终端按键监听与退出

文件：tty.js

var tty = require('tty');

process.stdin.setRawMode(true);
process.stdin.resume();

console.log('I am leaving now');

process.stdin.on('keypress', function(char, key) {
  if (key && key.ctrl && key.name === 'c') {
    process.exit();
  }
});

这段代码做了三件事：

引入tty模块；
将标准输入设为原始模式并恢复流动；
监听keypress事件，捕获Ctrl+C后退出进程。

输出效果是终端进入原始模式，按键被逐個读取，按下Ctrl+C时程序退出。

个人建议：keypress事件在原始模式下更可靠。如果只是处理行输入，不需要开启原始模式，直接用readline模块更合适。选择原始模式意味着接管终端行为，需要自行处理退出、信号和异常。

五、本节课程知识要点

tty模块提供终端底层抽象，多数场景由Node.js自动处理；
process.stdin在TTY环境下是tty.ReadStream实例；
process.stdout在TTY环境下是tty.WriteStream实例；
isRaw标识原始状态，setRawMode用于切换；
原始模式下需自行处理Ctrl+C等退出逻辑；
resize事件配合columns、rows实现动态布局；
使用前建议判断isTTY，避免非终端环境报错。

六、练习与思考

编写一个终端程序，实时显示当前终端尺寸，并在窗口调整时更新。
在原始模式下监听方向键，输出按键名称。
思考：为什么在管道或重定向场景下，setRawMode可能不可用？如何优雅降级？
对比readline模块与tty原始模式，分别适合什么场景？

七、错误处理与类型安全建议

setRawMode只在TTY环境下可用。非TTY环境调用会抛出ERR_TTY_INIT_FAILED或类似错误。稳妥做法：

if (process.stdin.isTTY) {
  process.stdin.setRawMode(true);
  process.stdin.resume();
} else {
  console.error('当前环境不支持 TTY 原始模式');
  process.exit(1);
}

在TypeScript项目中，可以结合@types/node获得tty.ReadStream和tty.WriteStream的类型提示，减少属性访问错误。

八、现在框架中的惯用写法

现在CLI框架如commander、yargs、ink等，内部会封装TTY检测与原始模式切换。直接使用tty模块的场景多见于：

自定义终端交互逻辑；
终端游戏或实时控制；
需要精细控制按键读取的场合。

如果只是解析命令行参数，不需要引入tty。工具选型上，优先使用成熟框架，减少底层终端状态管理的负担。

tty模块是Node.js终端能力的底层支撑。理解tty.ReadStream与tty.WriteStream的职责，掌握原始模式切换、尺寸监听和按键处理，是编写高质量终端程序的基础。实际项目中，先判断isTTY，再决定是否启用原始模式，并始终处理好退出逻辑和异常分支，才能让终端工具在多种环境下稳定运行。

本文标签：

Node.js TTY模块：ReadStream与WriteStream终端交互开发教程