本文详解 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 内置包管理器确保依赖纯净，即可稳定实现串口数据收发。
