Python模块导入会立即执行顶层代码，引发日志配置、环境变量读取、路由注册、数据库连接等副作用；同名文件与包冲突、C扩展初始化顺序、sys.path优先级错误等均会导致隐蔽运行时问题。
模块导入时的副作用会立即执行
Python在import一个模块时，不是只“声明依赖”，而是**立刻执行该模块顶层的所有代码**。这意味着：logging.basicConfig()、os.getenv("DB_URL")、@app.route注册、甚至requests.get()都可能在import那一刻就跑起来。
常见踩坑点：
- 配置模块（如
config.py）还没被导入，业务模块（如utils.py）却已执行logging.getLogger()——日志级别仍是默认值，调试信息全丢 -
db.py里写了engine = create_engine(os.getenv("DB_URL"))，但load_dotenv()在后面才调用——DB_URL是None，连接字符串变成"sqlite:///"或直接报错 - 装饰器注册逻辑（如Flask路由、Click命令）在
import时就写入全局registry，如果A和B都import C，而C又import A，可能造成重复注册或覆盖
同名包/模块加载优先级冲突
当项目目录下存在spam.py和spam/（含__init__.py）时，import spam永远加载的是spam/包，而不是spam.py文件——后者被完全屏蔽。
这会导致：
立即学习“Python免费学习笔记（深入）”；
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
- 你以为在改
spam.py，实际运行的是spam/__init__.py里的逻辑 - 包内子模块（如
spam.loader）导入时，一定会先触发spam/__init__.py执行，哪怕你只想要其中某个工具函数 - 第三方库与本地模块同名（比如自己写了
json.py），会覆盖标准库json，引发难以定位的ImportError或行为异常
C扩展库初始化顺序引发卡死
像decord、torch、tensorflow这类带C/C++后端的库，在import时会触发底层运行时初始化（如CUDA context、FFmpeg codec registry、信号处理句柄注册）。这些操作不是原子的，且可能相互干扰。
典型现象：
-
import decord卡住不动，CPU几乎不占，进程也不退出 - 把
import torch放在import decord前面，问题消失；反过来就卡死 - 原因常是GPU上下文初始化被另一个库提前占用，或动态链接库（如
libavcodec）版本冲突导致loader阻塞
sys.path顺序决定“谁先被找到”
Python按sys.path从左到右查找模块，顺序错了，就会加载错版本：
- 当前目录（
''）排第一 → 本地myproject/utils.py会被优先加载，而非site-packages里的同名包 - 手动插入路径：
sys.path.insert(0, "/path/to/my/fork")能强制优先加载你的修改版，但若忘了删，后续升级原包就无效 -
PYTHONPATH环境变量内容会插在sys.path靠前位置，容易意外覆盖系统路径
最隐蔽的问题：某些IDE（如PyCharm）会在启动时自动把项目根目录加进sys.path，而命令行运行时没有——同一段代码，在IDE里正常，终端里报ModuleNotFoundError。
