串口通信常见问题及解决方案：设备未插、权限不足、端口号错误占90%；linux/macos需配置用户组权限，windows注意端口名格式；避免裸写serial初始化，应设超时、清缓存、用read()或read_until()替代readline()；多线程必须单线程操作串口并用队列通信；正确使用reset_input_buffer()清接收缓存，flush()仅用于确保数据发出。
串口打开就报 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')）。
立即学习“Python免费学习笔记（深入）”；
- 初始化时务必设
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、系统权限细节——这些没法靠文档覆盖，只能靠日志打点 + 缓冲区快照 + 端口状态轮询一点点对齐。
