简介：这是一份面向Qt开发者的Telnet客户端完整源码，版本v2.1，以LGPL/GPL3开源协议发布。项目基于Qt框架完整实现了Telnet协议的关键环节，包括TCP连接管理、命令交互的编码与解码、选项协商、异常处理与会话重连，并自带simpleClient示例与跨平台构建脚本，适合需要学习Qt网络编程、终端模拟或Telnet协议实现的开发者阅读。资源包共29个文件，涵盖4个pro工程文件、qttelnet核心cpp与h源码、pri构建配置，以及txt说明文档、qdoc/qch帮助文档、html页面与png图片等，压缩包整体仅79KB；目录将src、examples、doc、buildlib清晰分区，便于按模块查阅。目前已有283人学习/浏览。通过研读源码，可以掌握在Qt中搭建终端模拟客户端的完整思路，理解QWidget界面与网络通信组件的配合方式；结合examples示例还能学习工程组织、模块划分与跨平台构建方法，代码侧重协议交互细节，适合二次开发或教学演示。
1. 项目整体设计与思路拆解
做嵌入式开发这些年，打交道最多的两个工具就是串口终端和Telnet终端。串口好办，工具一堆，但Telnet这个场景反而挺尴尬——Windows自带的telnet客户端难用不说，对终端仿真、乱码、字体这些细节几乎是零支持；用Xshell、SecureCRT这类商业软件吧，功能又过于臃肿，很多功能根本用不上，还得考虑授权问题。所以我干脆自己动手，用Qt写了一个Telnet客户端，也就是这个v2.1版本的源码项目。
1.1 为什么自己写Telnet客户端
先说一个很扎心的现状：Qt官方并没有专门为Telnet协议封装好的高层类。Qt的QNetworkAccessManager是给HTTP这类应用层协议用的，QTcpSocket虽然能干这事，但Telnet协议本身的状态机、选项协商、命令字节处理这些都得自己实现。
很多人在网上搜"Qt telnet"，拿到的要么是半成品，要么就是直接把数据往QTcpSocket里一塞就完事，完全没处理Telnet协议里最关键的IAC（Interpret As Command）字节。这样导致的直接后果就是：连上设备之后交互乱了套，设备发来的WILL ECHO、WILL SUPPRESS GO AHEAD这些协商指令会直接变成乱码显示出来，终端行为也完全不对。
v2.1这个版本的定位很明确：做一个开箱即用的Telnet客户端，把协议解析、选项协商、终端显示这三件事都处理好，同时保持代码轻量、单文件可移植、直接在Qt工程里拖进去就能编译。
1.2 模块划分与选区考量
整个项目的模块划分其实很清晰，就三层：
- 网络层：负责TCP连接的建立、断开、数据收发，直接封装
QTcpSocket - 协议层：解析Telnet数据流中的控制命令，处理选项协商，向上层暴露干净的读写接口
- UI层：连接配置界面、命令输入、回显显示、日志记录
v2.1相比v2.0最大的改动在协议层——把原来散乱的switch-case处理改成了一套基于状态机的解析流程，同时补齐了对NAWS（Negotiate About Window Size，窗口尺寸协商）和TTYPE（Terminal Type，终端类型协商）这两个选项的支持。这两个选项在实际调试中太常用了：不告诉对端终端类型，很多网络设备会拒绝给你全功能菜单，或者行为表现异常。
2. Telnet协议核心原理：别被"老协议"吓住
Telnet协议是1969年就定型的远古协议，但它并没有过时——今天几乎所有网络设备的管理接口、嵌入式Linux的调试入口、光猫超级密码获取通道，底层用的还是这套协议。理解了Telnet协议，很多设备交互上的疑难杂症也就迎刃而解了。
2.1 IAC命令与状态机基础
Telnet协议有个关键设计：数据流中的普通数据字节和控制命令字节是混在一起传输的。如果直接把收到的QByteArray当普通文本处理，命令字节就会和显示内容混在一起。
解决方法是引入一个特殊字节：IAC（Interpret As Command），十进制255。当接收方看到这个字节，就知道后续的数据不是普通文本，而是一条控制命令。
在一个简单的Telnet数据流中，可能出现这样的原始数据：
FF FD 18 FF FB 01 68 65 6C 6C 6F 0D 0A其中FF FD 18是一条命令：IAC + DO + 终端类型（0x18），表示"对端要求我们发送终端类型"；FF FB 01是另一条：IAC + WILL + ECHO，表示"对端准备开启回显"；后面的68 65 6C 6C 6F才是真正的文本"hello"。
如果代码不解析，直接在文本框里显示，那一行字符会变成一堆乱码。v2.1的协议层核心就是一个状态机，专门区分"当前字节属于命令还是普通数据"。
状态机逻辑其实很朴素：
- 初始状态是
Data，所有字节都按普通数据输出 - 收到
IAC，进入IAC状态，等待下一个字节 - 如果第二个字节是命令类型（如
WILL、DO），再进入CommandOption状态，继续读一个字节获取选项编号 - 如果是
SB（Subnegotiation，子协商），进入子协商的接收状态，直到遇到IAC SE才结束
2.2 选项协商机制解析
Telnet协议里最活跃的部分就是选项协商。打个比方，你到一家餐厅，服务员（服务器）会先问问你需不需要茶水（回显）、需不需要靠窗座位（窗口尺寸）、能不能扫码点餐（终端类型）。这些"询问"就是选项协商报文。
常见的选项协商命令有四个，配合选项编号使用：
| 命令 | 字节 | 含义 |
|---|---|---|
| WILL | 251 | 发送方将要开启某个选项 |
| WONT | 252 | 发送方拒绝开启某个选项 |
| DO | 253 | 发送方要求接收方开启某个选项 |
| DONT | 254 | 发送方要求接收方关闭某个选项 |
常见的选项编号有：
| 选项 | 字节 | 说明 |
|---|---|---|
| ECHO | 1 | 回显 |
| SUPPRESS GO AHEAD | 3 | 抑制Go Ahead |
| STATUS | 5 | 状态查询 |
| TTYPE | 24 | 终端类型 |
| NAWS | 31 | 窗口尺寸 |
v2.1的协议层会做这样几件事：
- 收到
WILL ECHO，回复DO ECHO，表示接受回显开启 - 收到
DO TTYPE，回复WILL TTYPE，然后发送子协商报文，附上终端类型字符串 - 收到
DO NAWS，回复WILL NAWS，然后发送当前窗口宽度和高度
不处理这些协商的后果是什么？大部分设备在收到DONT或没有任何响应后，会降级到最保守的交互模式，比如不给你回显（你敲命令看不见自己打了什么）、不给你菜单（某些交换机会隐藏高级命令）。所以协议层这一块不能偷懒。
2.3 子协商（Subnegotiation）的处理
子协商是选项协商的进阶版，用于传输比"开/关"更复杂的信息。格式是：
IAC SB 选项编号 数据... IAC SE比如TTYPE的子协商全流程是这样的：
- 服务器发：
IAC DO TTYPE（请告诉我你的终端类型） - 客户端回：
IAC WILL TTYPE（好的我会发） - 服务器发：
IAC SB TTYPE 1 IAC SE（请发你的终端类型，1表示SEND） - 客户端回：
IAC SB TTYPE 0 xterm IAC SE（我的终端类型是xterm，0表示IS）
整个过程中，SB和SE是成对出现的，中间的数据段不能被普通状态机拦截。所以我在v2.1里专门加了SubNegotiation子状态：进入SB后，所有字节都往缓冲区里存，直到遇到IAC SE才解除状态。这一步不处理好，数据流会错乱。
3. v2.1核心代码实现与实操要点
如果只打算拿源码直接编译，你可以跳过协议理论那部分，但代码的几个关键模块还是要看懂，后面排查问题会省力很多。
3.1 连接管理模块：封装QTcpSocket
v2.1的连接管理依然基于QTcpSocket，但做了几个增强：超时处理、自动重连、错误分类。
核心连接函数长这样：
bool TelnetClient::connectToHost(const QString& host, quint16 port, int timeoutMs) { if (m_socket->state() != QAbstractSocket::UnconnectedState) { m_socket->abort(); } m_socket->connectToHost(host, port); if (!m_socket->waitForConnected(timeoutMs)) { m_lastError = m_socket->errorString(); m_socket->abort(); return false; } m_connected = true; m_parser.reset(); emit connected(); return true; }注意waitForConnected是一个阻塞调用，如果在UI线程里直接用，界面会卡死。v2.1的做法是把连接操作丢到QtConcurrent::run里执行，连接完成后再通过信号槽把结果传回主线程。这样既保持了代码简单，又避免了界面冻结。
另外一个细节是m_parser.reset()。每建立一次新连接，协议解析器的状态机必须重置——你不想上一个连接残留在缓冲区里的半截报文污染新连接吧。这一点在实际切换不同设备调试时尤为重要。
断开连接的实现也做了优化，不是直接暴力disconnectFromHost()，而是先尝试通知对端再断开：
void TelnetClient::disconnectFromHost() { if (!m_connected) return; // 发送Telnet断开命令: IAC IP (Interrupt Process) QByteArray bye; bye.append(static_cast<char>(255)); // IAC bye.append(static_cast<char>(244)); // IP m_socket->write(bye); m_socket->flush(); m_socket->disconnectFromHost(); m_connected = false; emit disconnected(); }很多设备对突然断开的TCP连接处理得很粗糙，导致端口长期处于TIME_WAIT状态，重连就报"address already in use"。主动发一个IAC IP告诉对端"我要中断本次进程了"，可以明显降低这种概率。
3.2 协议解析器：QByteArray缓冲兼容粘包
嵌入式设备调试中最常见的网络问题是粘包和半包。TCP是流式协议，不会保证每次readyRead信号读到的一定是完整数据，所以协议解析器必须自己维护一个缓冲区。
v2.1的做法是这样的：
void TelnetClient::onReadyRead() { m_buffer.append(m_socket->readAll()); parseBuffer(); } void TelnetClient::parseBuffer() { int i = 0; while (i < m_buffer.size()) { uchar byte = static_cast<uchar>(m_buffer.at(i)); switch (m_state) { case ParserState::Data: if (byte == IAC) { m_state = ParserState::IAC; } else { appendToDisplay(byte); } i++; break; case ParserState::IAC: // 判断下一个字节 switch (byte) { case Command::WILL: case Command::WONT: case Command::DO: case Command::DONT: m_pendingCmd = byte; m_state = ParserState::Command; break; case Command::SB: m_subBuffer.clear(); m_state = ParserState::SubNegotiation; break; case Command::IAC: // 转义：数据中出现的255 appendToDisplay(byte); m_state = ParserState::Data; break; default: m_state = ParserState::Data; break; } i++; break; case ParserState::Command: handleOption(m_pendingCmd, byte); m_state = ParserState::Data; i++; break; case ParserState::SubNegotiation: if (byte == IAC) { // 检查下一个字节是不是SE if (i + 1 < m_buffer.size() && m_buffer.at(i + 1) == Command::SE) { handleSubNegotiation(m_subBuffer); m_state = ParserState::Data; i += 2; continue; } m_subBuffer.append(byte); } else { m_subBuffer.append(byte); } i++; break; } } m_buffer.remove(0, i); }这版解析器最需要注意的地方是IAC IAC转义序列。255这个字节既是命令的引导符，也可能作为普通数据出现。协议规定：如果数据中真的需要传255这个字节，发送方会将其写成IAC IAC两个连续字节。解析时必须把这个情况单独处理，否则数据就会被切断、显示异常。
3.3 选项协商的自动回包
之前讲过，协议层要做的关键事情之一是对WILL/DO等请求自动回包。v2.1的handleOption函数是这么实现的：
void TelnetClient::handleOption(uchar cmd, uchar option) { QByteArray response; switch (cmd) { case Command::WILL: switch (option) { case Option::ECHO: // 接受回显 response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::DO)); response.append(static_cast<char>(Option::ECHO)); break; case Option::SUPPRESS_GO_AHEAD: response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::DO)); response.append(static_cast<char>(Option::SUPPRESS_GO_AHEAD)); break; case Option::TTYPE: response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::DO)); response.append(static_cast<char>(Option::TTYPE)); break; default: // 不支持的选项，回复DONT response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::DONT)); response.append(static_cast<char>(option)); break; } break; case Command::DO: switch (option) { case Option::TTYPE: response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::WILL)); response.append(static_cast<char>(Option::TTYPE)); // 立即发送终端类型 sendTerminalType(); break; case Option::NAWS: response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::WILL)); response.append(static_cast<char>(Option::NAWS)); sendWindowSize(); break; default: response.append(static_cast<char>(IAC)); response.append(static_cast<char>(Command::WONT)); response.append(static_cast<char>(option)); break; } break; default: break; } if (!response.isEmpty()) { m_socket->write(response); } }这里有个细节：对于不认识的选项，一定要回WONT或DONT，而不是什么都不发。因为很多网络设备是"你默认接受"的假设，不发回包它就一直等，导致后续交互卡住。这就像电话沟通中对方问你问题，你不回答，他就只能一直追问或者干等。
3.4 UI层：从QPlainTextEdit到终端渲染
v2.1的UI层很简单：上面一个QPlainTextEdit做显示区，下面一个QLineEdit做输入区，加一个"连接"按钮。但这里埋了一个坑：QPlainTextEdit默认不支持终端控制序列，比如\x1b[2J清屏、\x1b[0m重置颜色、\x1b[1;31m红色粗体等。设备端会发这些ANSI转义序列，直接显示就是一片乱七八糟的字符。
我的处理方案是写了一个轻量的TerminalTextEdit类，继承QPlainTextEdit，重写appendData(const QByteArray&)方法，在做解析时把常见的控制序列剥掉，仅保留可显示的文本。完整的VT100仿真工作量大得惊人，但v2.1里做了个折中：识别并处理最常用的几个序列——清屏、光标归位、颜色重置、换行、回车、退格。
void TerminalTextEdit::appendData(const QByteArray& data) { int i = 0; while (i < data.size()) { uchar ch = static_cast<uchar>(data.at(i)); if (ch == 0x1B) { // ESC // 查找下一个字母字符，跳过完整的控制序列 int j = i + 1; while (j < data.size() && !(data.at(j) >= 0x40 && data.at(j) <= 0x7E)) { j++; } parseEscapeSequence(data.mid(i, j - i + 1)); i = j + 1; } else if (ch == '\r') { // 忽略裸CR，除非后面跟LF i++; } else { insertPlainText(QString::fromUtf8(data.mid(i, 1))); i++; } } ensureCursorVisible(); }注意这里用QString::fromUtf8处理数据。如果设备返回的是GBK编码的中文，显示会变成问号。很多光猫和旧交换机默认输出GBK编码，所以v2.1的编码处理也要做配置：在连接窗口里加一个编码下拉框，支持UTF-8、GBK、GB18030。实际处理时用QTextCodec转换，一行代码的事，但能救回无数乱码页面。
3.5 发送数据的处理
输入框的发送逻辑也做了处理，不只是简单地write(text.toUtf8())。关键要处理回车换行符——Telnet协议规定回车是\r\n（CRLF），而不是普通聊天工具的\n。
void MainWindow::onCommandSubmitted(const QString& text) { if (!m_telnet->isConnected()) { appendLocalMessage(tr("尚未连接到服务器")); return; } QByteArray data = text.toUtf8(); data.replace("\n", "\r\n"); m_telnet->sendData(data); m_inputEdit->clear(); }还有个小细节：回显。连接开启回显后，你敲的命令会在本地显示一次，设备端又会回显一次，导致命令看起来出现两遍。实际处理是在显示区过滤掉自己发的数据，只保留设备端的回显，或者干脆在本地禁止回显、只显示设备端返回的内容。v2.1默认是后者，这样更加贴近真正的终端体验。
4. 常见问题与排查技巧实录
这部分是实际调试中踩坑最集中的地方，我把遇到的高频问题整理成一个速查表，再逐个细说。
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
连接后立即断开，提示errno 104 | 对端主动重置连接；协议协商失败 | 先检查端口和协议类型；抓包确认协商包是否正确 |
| ping通但telnet端口不通 | 设备禁用了telnet服务；防火墙拦截 | 确认端口是否为23；用nmap -p 23扫描；检查服务配置 |
| 中文显示乱码 | 编码不匹配 | 切换GBK/UTF-8编码 |
| 命令敲了没反应 | 没发CRLF | 确认发数据时是否替换为\r\n |
| 界面卡死 | 阻塞调用waitForConnected | 改用异步连接或丢到线程池 |
| 设备内容显示重叠不换行 | CR/LF处理不当 | 把\r\n统一交给渲染层处理 |
4.1 errno 104：Connection reset by peer
这是最常见的报错，表示对端把你的TCP连接主动重置了。我遇到过很多次，排查路径基本固定：
第一，确认协议类型。很多设备同时开了telnet和SSH，你连的是23端口，但设备那边根本没起telnet服务，壳都不存在，连上就RST。第二，检查是否被防火墙拦截。第三，抓包看协商过程。如果设备端发送了WILL ECHO、你的客户端回了DO ECHO，但设备后续仍没有响应，很可能是协商包格式不对，比如字段顺序错了、IAC重复了、或者直接用文本工具发送了不可见字节。在v2.1里，我专门加了一个"协议日志"窗口，会把原始二进制数据按十六进制打出来，排查这类问题效率极高。
4.2 快速定位协议错乱：十六进制日志
聊到排查，要特别建议你在自己的工具里加上十六进制日志。只靠肉眼观察文本输出，很多协议问题根本看不见。举个例子，Telnet传输过程中收到的数据经常是这样：
FF FD 1F FF FB 03 FF FD 18 FF FB 01 ......这些字节在文本显示区基本是不可见的，或者会变成奇怪的符号，但你根本看不出是"什么协议指令"。十六进制日志把每条收到的原始报文都打出来，配合协议文档对照，协议协商成功与否一目了然。
v2.1里实现这个功能很简单，就是在onReadyRead和sendData两个函数的入口加一行：
emit rawDataReceived(m_buffer.mid(0, n)); // n为本次读取的字节数在UI上接一个QPlainTextEdit，把字节转成十六进制输出，同时保留ASCII版本：
QString hex = data.toHex(' ').toUpper(); QString ascii; for (char c : data) { ascii.append(QChar::isPrint(static_cast<uchar>(c)) ? QChar(c) : QChar('.')); } m_hexLog->appendPlainText(hex + " " + ascii);这个工具在跟设备厂商联调协议问题时，简直是救命的。你可以直接把日志丢给对方，双方对着报文说话。
4.3 ping通但telnet一直失败
另一个高频问题是：设备能ping通，但telnet 23端口就是连不上。这个问题的排查路径要宽一些：
- 设备是否开启了telnet服务？很多设备默认只开SSH，telnet服务要在配置页面手动开启，或者需要通过串口/特定命令激活。
- 是否有ACL限制？不少网络设备支持管理ACL，只允许指定源IP访问管理端口。你的机器IP可能不在允许列表里。
- 是否存在中间防火墙拦截？这个问题在办公网环境很常见。
- 端口冲突？设备上23端口被其他服务占用，或者设备本身telnet进程挂了。
针对这些问题，v2.1额外加了一个小功能：连接前的端口探测。说白了就是用QTcpSocket先试探性连接一下端口，如果连接成功则立刻断开，然后再走完整的Telnet握手流程。这个功能用于区分"端口不通"和"协议协商失败"，可以在界面上直接提示用户。
4.4 Qt环境相关的几个坑
除了协议层的问题，开发环境本身也有几个容易踩的坑，尤其新手容易在这里卡很久。
一个是qxcbconnection: failed to initialize xrandr这类X11错误。在无图形界面的服务器上运行Qt程序，或者通过SSH远程执行带GUI的Qt程序时经常碰到。解决办法很朴素：程序本身不需要GUI就编译成命令行版本，或者用QT_QPA_PLATFORM=offscreen环境变量强制使用离屏渲染。不过如果你要是做一个纯命令行交互工具，那压根别带Qt的GUI模块，直接用QCoreApplication就行。
另一个是QCoreApplication::exec()执行后，信号槽不触发的问题。有些初学者习惯把业务逻辑写在main()里，但exec()一跑起来，任何不在其事件循环中的代码都无法收到信号，因为它们没有跑在事件循环里。解决方法是：所有连接、发送数据的逻辑，都要在主窗口或协议对象的构造函数里完成初始化，靠信号槽驱动，而不是靠顺序调用驱动。
还有一个和VS Code相关的问题。很多人在VS Code里打开别人的Qt工程，发现头文件都找不到，这是因为没有配置includePath。VS Code默认不知道Qt安装目录，需要在.vscode/c_cpp_properties.json里指定Qt头文件路径：
{ "configurations": [ { "name": "Qt", "includePath": [ "${workspaceFolder}/**", "D:/Qt/5.15.2/mingw81_64/include", "D:/Qt/5.15.2/mingw81_64/include/QtWidgets", "D:/Qt/5.15.2/mingw81_64/include/QtNetwork", "D:/Qt/5.15.2/mingw81_64/include/QtCore" ], "defines": [], "compilerPath": "D:/Qt/Tools/mingw810_64/bin/g++.exe", "cStandard": "c17", "cppStandard": "c++17", "intelliSenseMode": "windows-gcc-x64" } ] }5. 项目扩展与实际应用心得
v2.1源码除了作为一个Telnet客户端直接使用，还可以二次开发成很多有用的东西。我在实际项目里就把它改成了自动化巡检工具：定时连接网络设备，执行命令，抓取输出，保存到日志文件。这比在命令行里一条条敲要高效得多。
5.1 从客户端到自动化脚本
如果你希望Telnet客户端能自动执行一组命令，只需要在协议层之上加一个命令队列：
void TelnetClient::execCommandBatch(const QStringList& commands, int intervalMs) { m_commandQueue = commands; m_commandTimer.start(intervalMs); } void TelnetClient::onCommandTimerTimeout() { if (m_commandQueue.isEmpty()) { m_commandTimer.stop(); return; } QString cmd = m_commandQueue.takeFirst(); sendData(cmd.toUtf8() + "\r\n"); }这里有个经验：设备执行命令是需要时间的，尤其是一些耗时操作（如保存配置、重启服务），连续发送命令会导致部分命令丢失。所以每条命令之间的间隔时间要足够长，或者用"输出匹配等待"——发送一条命令，等收到期望的输出再发下一条。后者更可靠，但实现复杂度更高。v2.1目前的定时器轮流发送方案，对大多数巡检场景已经够用。
5.2 编码识别再做一层加固
在应对老设备时，编码问题永远是个痛。v2.1的编码切换是手动的，但如果你的工具要交付给不太懂技术的人用，可以考虑自动识别编码。常见做法是：先按UTF-8解析，如果检测到非法字节序列，就尝试用GBK重新解析。Qt里QStringDecoder可以辅助判断：
QString decodeWithFallback(const QByteArray& data) { auto utf8Decoder = QStringDecoder(QStringDecoder::Utf8); QString result = utf8Decoder.decode(data); if (utf8Decoder.hasError()) { auto gbkDecoder = QStringDecoder(QStringDecoder::Gb18030); return gbkDecoder.decode(data); } return result; }这个逻辑不复杂，但能省掉用户手动切换编码的麻烦。
5.3 多协议扩展：Telnet只是起点
Telnet和SSH在协议层面是孪生兄弟——都是"连接网络设备、执行命令、获取输出"的通道，差别在传输层加密和认证方式。如果你想更进一步，可以在v2.1的架构上接入libssh或者Qt的QProcess调用系统ssh命令，实现SSH客户端。有了v2.1的UI框架和命令队列机制，切换协议只是换掉连接层和传输层的事。
实际上，我在自己的开发工作流里，已经把v2.1做成了"万能网络调试器"：既能连Telnet，也能连串口（通过QSerialPort），还接了一个HTTP API用来测试设备REST接口。这种"一个入口连所有设备"的工作方式，对日常开发调试的效率提升非常明显。
如果你也经常跟网络设备、嵌入式Linux开发板打交道，建议花点时间把v2.1源码吃透，改成适合自己习惯的工具。别小看这个看起来"古老"的协议，它至今仍然是网络设备最通用的调试入口，掌握了它，你的武器库里就多了一把万能钥匙。
本文还有配套的精品资源，点击获取
