插件模块路径不合法是动态导入失败最常见原因：importlib.import_module只认包路径（如"plugins.auth"），不接受文件路径（如"./plugins/auth.py"）；需先将目录加入sys.path或用spec_from_file_location加载。
插件模块路径不合法导致 ImportError: No module named
动态导入失败最常见原因是路径没处理对——importlib.import_module() 只认 Python 包路径（如 "plugins.auth"），不接受文件系统路径（如 "./plugins/auth.py"）。必须先把插件目录加入 sys.path，或用 importlib.util.spec_from_file_location() 直接加载文件。
实操建议：
- 若插件是标准包结构（含
__init__.py），用sys.path.insert(0, plugin_dir)后调用importlib.import_module("plugins.auth") - 若插件是单个 .py 文件，优先用
importlib.util.spec_from_file_location("auth", "/path/to/auth.py")，再importlib.util.module_from_spec()加载 - 避免硬编码绝对路径；用
pathlib.Path(__file__).parent / "plugins"获取相对路径更可靠
importlib.reload() 无法热更新已导入的模块
调用 importlib.reload() 前，模块必须已在 sys.modules 中存在。如果之前是用 spec_from_file_location 加载的，且未手动存入 sys.modules，reload() 会直接报 ImportError: module not in sys.modules。
实操建议：
- 加载后立即将模块对象存入
sys.modules["auth"]（键名需与后续reload一致） - 热重载前先检查
"auth" in sys.modules，否则跳过或重新完整加载 -
reload()不会更新已引用该模块的其他对象（比如类实例、函数闭包），这部分逻辑需业务层主动刷新
插件模块内全局变量/类注册表未生效
Python 模块导入时执行顶层代码，但若插件依赖某个“注册中心”（如 PLUGIN_REGISTRY = []），而注册语句写在模块末尾，却因导入顺序或异常中断未执行，就会导致插件“导入成功但未注册”。
实操建议：
- 把注册逻辑封装进一个显式函数（如
register_plugin()），并在模块末尾调用它；确保即使被reload()也能再次触发 - 不要依赖模块级变量赋值自动注册，改用装饰器（如
@plugin）+ 函数定义时注册，更可控 - 加载后主动检查
hasattr(module, "register_plugin")并调用，比被动等待更稳妥
Windows 下插件路径大小写敏感引发 ModuleNotFoundError
Windows 文件系统默认不区分大小写，但 Python 的 importlib 在解析模块名时严格按字符串匹配。若插件目录名为 Plugins，但代码中写成 importlib.import_module("plugins.auth")，就可能在某些环境（尤其是从 zip 导入或启用 PYTHONDONTWRITEBYTECODE 时）失败。
实操建议：
- 统一约定插件包名全小写，并在加载前用
os.path.normcase()标准化路径 - 用
importlib.util.find_spec()预检模块是否存在，比直接import_module()更早暴露路径问题 - CI 环境建议用 Linux 容器测试，提前暴露大小写隐患
插件架构里最麻烦的不是导入本身，而是模块生命周期管理——什么时候该 reload，什么时候该卸载，以及旧模块对象残留引发的内存和逻辑错乱。这些没法靠 importlib 自动解决，得在插件容器层做明确状态跟踪。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
