PySerial 串口通信实用教程

本文深入剖析了PySerial串口通信中高频踩坑场景与实战解决方案：从设备未接入、权限不足、端口号错误等占90%的初始化失败原因，到Linux/macOS用户组配置、Windows端口名规范与动态枚举技巧；从readline()因缺少换行符导致的无限阻塞，到推荐使用带超时的read()、read_until()及in_waiting精准控制数据读取；再到多线程下必须采用单线程串口操作+队列通信的强制范式；最后厘清flush()与reset_input_buffer()的根本区别——前者确保数据发出，后者才真正清除接收缓存。全文直击生产环境真实痛点，强调日志、快照与状态轮询等调试思维，是开发者避开玄学故障、构建稳定串口通信系统的实用指南。

串口打开就报 SerialException: could not open port

设备没插、权限不对、端口号写错，三者占了 90% 的情况。Linux/macOS 上尤其要注意权限：/dev/ttyUSB0 默认非 root 不可访问，加用户进 dialout 组（Ubuntu/Debian）或 uucp 组（macOS）后需重新登录生效。

Windows 下常见端口名写成 COM3 却用了 COM3:（多冒号）或 com3（小写），pyserial 对大小写不敏感但冒号是非法字符；另外热插拔后端口号可能变，别硬编码 COM4，用 serial.tools.list_ports.comports() 扫一遍再匹配设备描述符更稳。

• 检查前先运行 python -c "import serial.tools.list_ports; print(list(serial.tools.list_ports.comports()))"
• 避免用 ser = serial.Serial('COM3') 这种裸写法，加 timeout=1 和 write_timeout=1 防卡死
• Linux 下如果仍 PermissionError，临时试下 sudo chmod a+rw /dev/ttyUSB0 快速验证是不是权限问题

readline() 一直阻塞，或者读不到完整数据

根本原因是串口没有换行符终结，而 readline() 默认等 \n，设备发的是 \r、\r\n，甚至无分隔符的二进制帧——这时候它就永远等下去。

生产环境必须放弃无脑 readline()。改用 read() 配合超时 + 缓冲区手动解析，或用 read_until() 指定结束字节（比如 read_until(b'\n') 或 read_until(b'\r')）。

• 初始化时务必设 timeout=0.1（单位秒），否则一次读卡住会拖垮整个主循环
• 如果协议固定长度（如 16 字节帧），直接 ser.read(16)，比反复 read 更可靠
• 用 in_waiting 查当前缓存字节数，避免空读：if ser.in_waiting: data = ser.read(ser.in_waiting)

多线程里读写串口崩出 SerialException: write failed

pyserial 的底层串口句柄不是线程安全的。两个线程同时调 ser.write()，或一个在读一个在 close()，大概率触发异常或数据错乱。

唯一靠谱做法是把串口操作收归单一线程，其他线程通过队列通信。不要试图加锁绕过——锁住 ser.write() 本身没用，因为底层 OS 调用可能已被中断。

• 用 queue.Queue 接收写请求，由 dedicated 串口线程消费并执行 ser.write()
• 读操作也统一走这个线程，解析完再把结构化数据 put 到另一个 result queue
• 绝对不要在子线程里调 ser.close()，主线程负责生命周期管理，关闭前先 stop worker thread

为什么 flush() 和 reset_input_buffer() 总被误用

flush() 是等输出缓冲区清空（即发完），不是清输入缓冲区；真正清接收缓存的是 reset_input_buffer()（清输入）和 reset_output_buffer()（清输出）。很多人想丢掉旧数据却调了 flush()，结果什么也没清掉。

典型误用场景：刚打开串口就读，发现读到上一次残留数据。正确做法是打开后立刻 ser.reset_input_buffer()，而不是等 read 出错再 flush。

• 每次 ser.open() 后建议紧跟 ser.reset_input_buffer() 和 ser.reset_output_buffer()
• flush() 只应在明确需要确保数据已物理发出时才用（比如发完指令等设备响应前），多数时候不需要
• 注意 Windows 下 reset_input_buffer() 可能清不干净，实测有时要调两次

串口通信真正的麻烦不在 API 多难，而在设备行为不一致、线缆干扰、驱动 bug、系统权限细节——这些没法靠文档覆盖，只能靠日志打点 + 缓冲区快照 + 端口状态轮询一点点对齐。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PySerial 串口通信实用教程》文章吧，也可关注golang学习网公众号了解相关技术文章。