Python模块导入机制(sys.path详解)

前言

这篇博客将汇总讲解Python的模块导入机制，弄明白Python解释器在导入包时的运作原理。

核心概念

sys.path 是 Python 解释器的“模块查找清单”，导入模块时，解释器会逐一遍历清单中的路径，找到对应 .py 文件或包则导入成功，否则报错。其构成来源（按优先级排序）：

1. 当前环境的 site-packages（第三方库路径）
2. 环境变量 PYTHONPATH 配置的自定义路径
3. 程序启动时的 当前工作目录（指的是控制台当前所处的目录）
4. 启动脚本（主程序）所在的目录（仅主脚本专属），比如执行python main.py时，python解释器会把main函数所处目录加入到sys.path路径中。

值得注意的是，sys.path 在程序启动时一次性确定，在程序执行中，执行函数、导入模块等运行中操作，不会自动修改 sys.path。除非我们程序主动修改sys.path。

还有一点值得说明，启动脚本（主程序）是指直接被执行的 .py 文件（如python main.py中的 main.py），或通过 uvicorn 等工具指定的入口文件（如uvicorn main:app中的 main.py）。只有这个脚本的存放目录，会被 Python 自动加入 sys.path，其他被导入的模块/函数所在目录均不会自动加入。