PHP posix_isatty 怎么判断 CLI 是否连接交互终端

同一个 PHP CLI 命令，人工执行时希望显示提示并等待输入，被管道调用时却应该直接读取数据。判断这两种场景，不要靠环境变量或终端名称猜测，直接把 STDIN 交给 posix_isatty()：返回 true，说明描述符连接着终端；返回 false，说明它更像管道、重定向文件或其它非交互端点。

官方地址：https://www.php.net/manual/en/function.posix-isatty.php

最小用法是 posix_isatty(STDIN)。它只回答“这个描述符是否连接终端”，不负责读取数据、解析参数，也不会替你决定终端颜色或交互文案。

一、先判断 STDIN 到底连接了什么

我在写 PHP 命令行工具时，最容易踩的坑是把“当前运行在 CLI”误认为“当前一定有人在终端前输入”。脚本通过管道接收文件时仍然是 CLI SAPI，但 STDIN 已经不是交互终端；用重定向文件启动时也是同样结果。

posix_isatty() 接收文件资源或整数文件描述符，只有描述符打开且连接到终端时才返回 true。因此通常先判断 STDIN，如果要判断输出是否适合交互提示，也可以把 STDOUT 作为待检测描述符。

二、根据检测结果选择读取策略

判断结果应该直接服务于输入策略，而不是变成一个单独的“环境标签”。下面的函数只做能力探测和 TTY 判断；真实项目可以把交互提示、默认值和业务校验放在调用方。

这个分支的重点不是把所有非 TTY 都当成错误，而是让批处理调用保持可预测：例如 printf 'alice\n' | php script.php 时，脚本应消费输入而不是再打印一个交互提示。若业务必须要求人工操作，可以在 false 分支明确退出并给出错误码。

三、为什么不要用环境变量替代 TTY 判断

环境变量只能表达启动环境里的一部分信息，不能准确说明某个具体文件描述符此刻是否连接终端。脚本被 CI、定时任务、管道或重定向调用时，环境变量可能保持不变，而 STDIN 的连接对象已经变化。

如果要判断输出是否应该带进度提示，应检查 STDOUT，不要只看 STDIN。输入是管道、输出仍是终端的场景很常见：程序需要安静读取数据，但可以向终端报告进度。反过来，输出被重定向到文件时，也应避免把彩色提示或进度字符写进结果文件。

另外，posix_isatty() 只处理描述符类型判断。它不会判断是否已经有可读数据，也不会替代 fgets()、stream_get_contents() 或命令行参数解析。

四、把扩展和版本边界放在调用点

PHP 手册说明，整数参数会被当作底层文件描述符直接传递；PHP 8.4 起无效描述符会设置 EBADF，PHP 8.5 起遇到无效 file_descriptor 还会产生 E_WARNING。这意味着生产代码应保持参数来源明确，不能依赖“传个数字试试”的探测方式。

常见问题

posix_isatty 返回 false 就代表没有输入吗？

不是。它只说明描述符不是交互终端；管道、普通文件、设备或已关闭的端点都可能得到 false。是否有数据要交给对应的读取函数判断。

应该检测 STDIN 还是 STDOUT？

看你要决定哪一侧的行为：读取方式看 STDIN，是否显示进度、颜色或提示看 STDOUT。两者可以分别检测。

能用 stream_isatty 替代吗？

如果项目运行的 PHP 版本和扩展已经提供它，可以按项目兼容范围选用；本文的边界是解释 POSIX 扩展中的 posix_isatty()，不要在没有确认运行环境时混用两个 API。