如何在 Thonny IDE 中正确使用 pyserial 模块实现串口通信

本文详解 AttributeError: module ‘serial’ has no attribute ‘Serial’ 错误的成因与解决方案，重点说明在 Thonny 中导入 pyserial 的正确方式、常见陷阱及稳定实践方法。

本文详解 `attributeerror: module ‘serial’ has no attribute ‘serial’` 错误的成因与解决方案，重点说明在 thonny 中导入 pyserial 的正确方式、常见陷阱及稳定实践方法。

在 Thonny ide 中使用 pyserial 进行串口通信时，出现 AttributeError: module ‘serial’ has no attribute ‘Serial’ 是一个高频问题。该错误并非 pyserial 未安装或硬件异常所致，而是由 Python 的模块命名冲突引起：当项目目录（或 Python 路径）中存在名为 serial.py 的本地文件时，Python 会优先导入该文件而非第三方 pyserial 包，导致 serial.Serial 等核心类不可用。

✅ 正确的导入方式应明确指定来源，推荐以下两种安全写法：

方式一（推荐）：显式导入类

from serial import Serial  connection = Serial('COM3', 115200, timeout=1)  try:     while True:         data = connection.readline()         if data:             print(data.decode('utf-8', errors='ignore').strip()) except KeyboardInterrupt:     print("n串口已关闭") finally:     connection.close()

方式二：导入模块并使用全限定名

import serial.tools.list_ports  # 可选：用于枚举可用端口 import serial  # 确保导入的是 pyserial，非本地 serial.py print("Serial module path:", serial.__file__)  # 调试用：检查实际加载路径  connection = serial.Serial('COM3', 115200, timeout=1) # ... 后续逻辑同上

⚠️ 关键注意事项：

• ? 检查命名冲突：在 Thonny 的当前工作目录及子目录中搜索 serial.py 或 serial.pyc，重命名或删除它们；
• ? 确认安装状态：在 Thonny 的 Shell 中执行 import serial; print(serial.__version__)，若报错 ModuleNotFoundError，则需通过 Tools → Manage packages… 安装 pyserial；
• ?️ windows 用户注意端口名：COM3 需与设备管理器中显示的实际 COM 端口号一致；macos/linux 请使用 /dev/tty.usbserial-* 或 /dev/ttyACM0 等路径；
• ⏳ 务必设置 timeout：避免 readline() 永久阻塞，影响程序可控性；
• ? *不推荐 `from serial import `**：虽然能临时绕过错误，但污染命名空间、降低可读性且掩盖根本问题，不符合 Python 最佳实践。

总结：解决该问题的核心是消除本地 serial.py 的干扰，并采用明确、可维护的导入方式。调试时善用 serial.__file__ 定位真实模块路径，结合 Thonny 内置包管理器确保依赖纯净，即可稳定实现串口数据收发。