Python import 导进来的不是那个文件:8 处静默取错
服务重启了三次,输出还是一行。我把 json.dumps 换成 json.dump、补上 indent=2、又确认了三遍文件真的存盘,最后在进程里打了一行 print(json.__file__),屏幕上给出的是项目目录下的 json.py —— 一个三个月前为了写迁移脚本随手建的、只有 17 字节的空文件。
import 这件事最容易被忽略的一点是:导入失败一定报错,导入到错的文件一声不响。它确实执行了一次导入,只是那个模块不是你写代码时脑子里想的那个。下面八种形态我实际跑了八组脚本,每一种都能量出「文件是真的、代码是真的、结果不是你以为的」。
本文的实验环境是 Windows 11 加 CPython 3.13.14(MSC v.1944 64 位),抓取与实测时间 2026-11-13。全程只用标准库,没有装任何第三方包 —— 这次实验里最「外部」的依赖,是标准库自己。下文每段输出都是原样粘贴,没有改写。文中不含任何联盟推广链接,也不含佣金链接。
TL;DR:八条里六条退出码是 0
TL;DR:导入失败会报错,导入错文件不会。十个可复现路径里有六条以退出码 0 结束 —— 它们不会让 CI 变红,也不会让服务起不来,只会在某一天让一个单例变成两份、让 isinstance 安静地返回 False、让改过的代码继续跑旧逻辑。定位只需要三条命令:module.__file__、importlib.util.find_spec(name).origin、python -X importtime。
| 场景 | 触发条件 | 失败形态 | 退出码 |
|---|---|---|---|
| 同名遮蔽 | 脚本目录里有 json.py | AttributeError,附带改名提示 | 1 |
| 空字符串路径 | -c 启动后中途 os.chdir() | 静默导入另一目录的同名文件 | 0 |
| 旧字节码 | 改写后字节数不变且落在同一秒 | 运行旧代码,无警告 | 0 |
| 顶层循环导入 | 模块 A、B 相互 from ... import | ImportError,提示里不提循环 | 1 |
同上,改用 import | 只写 import b 不取属性 | 拿到半成品模块 | 0 |
| 直接跑包内文件 | python pkg/mod.py | ModuleNotFoundError | 1 |
-m 跑包内文件 | python -m pkg.mod | 同一文件两个模块对象 | 0 |
| 命名空间包 | 目录没有 __init__.py | 取 __file__ 时 TypeError | 1 |
| 大小写两种拼写 | 设了 PYTHONCASEOK | 两个模块对象,状态互不可见 | 0 |
reload() | 之前用过 from m import f | 旧函数继续被调用 | 0 |
这张表本身就是本篇的结论:退出码不是判据。下面逐条给出复现方法与报错原文。
先看清 import 的执行顺序
顺序不复杂,但每一步都可能被你的文件截胡。
第一步查缓存。官方文档的原文是「The first place checked during import search is sys.modules」,并且「During import, the module name is looked up in sys.modules and if present, the associated value is the module satisfying the import, and the process completes」。注意最后半句:一旦命中,导入过程直接结束,后面的查找一步都不走。
第二步查 sys.meta_path,默认三个 finder:内建模块、冻结模块、路径查找器。前两个与你无关,第三个才是出问题的地方 —— 它按 sys.path 的顺序逐个路径项去问「你这儿有没有这个模块」。
第三步,找到之后先登记再执行。文档原文:「The module will exist in sys.modules before the loader executes the module code.」这一句解释了后面两节的现象:循环导入能拿到一个「半个」模块,以及一个模块 import 自己不会无限递归。
关键在第二步的「按 sys.path 顺序」。我在这台机器上把 sys.path 打出来,九项,挑四项看:
0 ''
1 D:\openclaw-blog\tmp\implab-1113\pathorder
2 ...\python313.zip
3 ...\DLLs
4 ...\Lib
6 C:\Users\xuany\AppData\Roaming\Python\Python313\site-packages
8 ...\Lib\site-packages
标准库目录 Lib 在索引 4,而用户 site-packages 在 6、系统 site-packages 在 8。也就是说 你自己的目录排在标准库前面,而装进去的包排在标准库后面。同一条规则,两种后果,这是下面第一条陷阱的全部原因。
陷阱一:同目录一个同名文件就能顶掉标准库
目录里放一个 json.py,内容只有一行 MARK = 'local json',然后写 main.py:
import json
print('file =', json.__file__)
print('has dumps =', hasattr(json, 'dumps'))
print(json.dumps({'a': 1}))
跑出来是这样:
file = D:\openclaw-blog\tmp\implab-1113\lab1\e1\json.py
has dumps = False
AttributeError: module 'json' has no attribute 'dumps' (consider renaming
'D:\openclaw-blog\tmp\implab-1113\lab1\e1\json.py' since it has the same name
as the standard library module named 'json' and prevents importing that
standard library module)
三行输出里有两个信号。第一,json.__file__ 已经指向本地文件,说明导入成功了;第二,3.13 在报错尾部加了一句改名建议,并且明说这个文件「prevents importing that standard library module」。这句提示是 3.13 才有的一类改进,老版本只会给你一句干巴巴的 AttributeError,让人以为是标准库改了 API。
顺带把另一半验证了:PYTHONPATH 也一样能顶掉标准库。把同一个 json.py 放进一个目录,用 PYTHONPATH=. 启动,json.__file__ 依然指向本地文件 —— 因为 PYTHONPATH 的条目落在索引 1,仍然在 Lib(索引 4)之前。
反面则是 site-packages:按同一顺序规则,它排在标准库之后,所以在 site-packages 里放一个叫 json 的包顶不掉标准库。这一条我是按 sys.path 实测顺序推定的,没有真的装一个假包去试 —— 区别在这里说明白,免得读者以为所有「同名」都一样危险。
判断方法便宜到不用记:在项目根目录跑一句 python -c "import json; print(json.__file__)",看路径里有没有你的项目名。有,就是它。
陷阱二:sys.path 第 0 项有三种身份
同样是 import helper,启动方式不同,sys.path[0] 完全不同。实测三种:
| 启动方式 | sys.path[0] |
|---|---|
python main.py | 脚本所在目录的绝对路径 |
python -c "..." | 空字符串 '' |
python -m probe | 当前工作目录的绝对路径 |
文档对这三种都有明文:-c 是「the current directory will be added to the start of sys.path」,脚本是「the directory containing that file is added to the start of sys.path, and the file is executed as the __main__ module」。
差别不在「第 0 项是什么」,而在它什么时候被解析。绝对路径在启动那一刻就固化了;空字符串是一个占位,每次导入时才按当时的当前目录去解释。于是 os.chdir() 会改变后续导入的结果,而这一点在两种启动方式下表现相反。
我建了两个目录 a/ 和 b/,各放一个 helper.py,分别写 WHERE = 'a' 和 WHERE = 'b'。用 -c 启动,先 import 一次,chdir 到另一个目录、从 sys.modules 删掉缓存再 import 一次:
cwd-run first a
cwd-run second b
同一个进程,同一个 import helper,拿到两个不同的模块。换成脚本方式再跑一遍完全相同的事,第二次仍然是 a —— 因为 sys.path[0] 是 a 的绝对路径,不会跟着 cwd 走。
这条在真实项目里长这样:CI 里是 cd build && python ../scripts/gen.py,本地是 IDE 里直接点运行。两边 sys.path[0] 一个是 scripts/、一个是别的东西,同名模块的胜者就变了。3.11 起有个开关能直接掐掉这个不确定性:python -P,不把可能不安全的路径塞进 sys.path[0]。我在放了这个 json.py 的目录里加 -P 再跑,json.__file__ 回到了标准库,has dumps 也回来了。
陷阱三:.pyc 的失效判据只有整数秒和字节数
这条最反直觉,因为它连「文件变了」都不看。
CPython 的字节码缓存不带源码哈希(默认模式),只带两个数:源码的修改时间(截断到整秒)与源码的字节数。源码第 1113 行附近就写着 source_mtime = int(st['mtime']),校验函数里两处比较分别是 _unpack_uint32(data[8:12]) 与 source_mtime 比、_unpack_uint32(data[12:16]) 与 source_size 比。
于是有一个很窄但完全真实的口子:字节数不变、且改动落在同一个整数秒内,旧字节码就继续有效。
我按这个条件做了一遍。先写 VALUE = 'first',导入一次生成缓存;然后把文件改成 VALUE = 'FIRST' —— 大小写互换,字节数还是 17;再用 os.utime 把修改时间放回原来那一秒。磁盘上现在明明白白写着 FIRST。再导入:
file on disk now: VALUE = 'FIRST' | size 17
run2: first
跑出来是 first。退出码 0,没有任何警告。把修改时间往后挪五秒,同样的导入立刻给出 FIRST,说明卡住的正是那一秒。
更值得记住的是 -v 的诊断输出。它不会告诉你「我读的是缓存」,它说的是:
# ...\__pycache__\greet.cpython-313.pyc matches ...\greet.py
# code object from '...\__pycache__\greet.cpython-313.pyc'
一个 matches 就把源码跳过去了。缓存头里那两个数字我顺手解出来对过:source_mtime = 1794521655,source_size = 17。
换个失效模式就骗不过了。标准库支持哈希校验的 pyc,用 py_compile.compile(..., invalidation_mode=PycInvalidationMode.CHECKED_HASH) 生成一份,再用同样的「同字节数 + 同一秒」手法改写,导入拿到的是新值。两种失效模式里,只有 50% 能被这个手法绕过 —— 时间戳模式会,哈希模式不会。
现实里怎么撞上:代码生成器写完文件立刻 import(模板渲染、DTO 生成、迁移脚本都常见);打包镜像或解包 tar 时把 mtime 抹平成固定值;两台机器之间同步文件但保留旧时间戳。我这台机器的环境里恰好设了 PYTHONDONTWRITEBYTECODE=1,第一次做实验时连 __pycache__ 都没生成,才意识到这台机器根本不会撞上这条 —— 而生产容器通常不会设它。
陷阱四:循环导入有两种报错,顶层文件那种不提循环
同一个 bug,顶层的模块和包里的模块给出的提示不一样,而其中一种完全没有「循环」两个字。
顶层文件互导的场景:alpha.py 里 from beta import BEE,beta.py 里 from alpha import VALUE,而 VALUE 写在 import 语句之后。报错是:
ImportError: cannot import name 'VALUE' from 'alpha' (consider renaming
'...\alpha.py' if it has the same name as a library you intended to import)
这里给出的建议是「改名」,理由是怀疑你撞了同名库。它一次都没提循环导入。新手照着这句话去改文件名,改完还是同样的错。
同一个环放进包里,提示立刻换了一套:
ImportError: cannot import name 'A' from partially initialized module 'pkg.a'
(most likely due to a circular import) (...\pkg\a.py)
partially initialized module 加上 most likely due to a circular import —— 这才是能搜到答案的那句话。所以「同样的错为什么别人搜得到我搜不到」有时候不是搜索技巧问题,是报错文案不同。
比报错更贵的是不报错的那种。把 from alpha import VALUE 改成 import alpha,再在 delta.py 里 import gamma 并读 gamma 的属性:
delta sees []
ok
delta sees [] 说明它拿到的 gamma 是一个还没有任何属性的空壳 —— 因为那时 gamma 只执行到第一行。整个进程退出码 0。等到某次请求真的访问那个属性,才会在别的地方炸出 AttributeError: module 'a3' has no attribute 'A',而栈里已经看不到循环导入的影子。
顺带一个能救命的细节:顺序决定成败。把 A = 1 挪到 from .b import B 之前,同一个环立刻就通了,b got A = 1。所以定位这类问题时不要只问「谁 import 了谁」,要问「被取的那个名字在第几行被赋值」。
陷阱五:__main__ 是另一份模块
包里的文件用两种方式跑,结果不同,而第二种更隐蔽。
pkg/state.py 里建一个模块级字典 REGISTRY,文件末尾用 if __name__ == '__main__' 再 import pkg.state 自己。直接跑:
python pkg/state.py
ModuleNotFoundError: No module named 'pkg'
原因还是第 0 项:sys.path[0] 变成了 pkg/ 目录,仓库根不在路径上,pkg 这个包名自然找不到。
换成 python -m pkg.state,能跑,但模块体执行了两次:
body runs, __name__ = __main__
body runs, __name__ = pkg.state
two module objects: True
两个模块对象、两个 REGISTRY 字典、两个 id。__main__ 那一份和 pkg.state 那一份互不相识,你往其中一个写进去的东西,从另一个里读不到。在真实项目里这会长成:注册表少了一半条目、Flask 应用被实例化两次、信号处理器注册两遍、单例连接池变成两个。
修法不复杂:入口文件只做一件事 —— 调 main(),不要在里面创建模块级状态;或者干脆建 pkg/__main__.py,业务状态全部放在能被正常导入的模块里。同属「代码到底跑没跑」这个问题的还有变异测试下的 unittest.mock 七个静默失效,那篇测的是测试替身。
陷阱六:没有 __init__.py 也能 import,但 __file__ 是 None
PEP 420 之后,目录里没有 __init__.py 也是一个包 —— 命名空间包。文档写得很清楚:「With namespace packages, there is no parent/__init__.py file.」而且它的 __path__ 不是普通列表:「They instead use a custom iterable type which will automatically perform a new search for package portions on the next import attempt within that package if the path of their parent package (or sys.path for a top level package) changes.」
我建了一个只有 ns/sub/leaf.py 的目录树,没有任何 __init__.py。import ns.sub.leaf 成功,leaf.V 正常拿到 1。然后:
ns.__file__ = None
ns.__path__ = _NamespacePath ['D:\openclaw-blog\tmp\implab-1113\lab2\e5\ns']
TypeError: argument should be a str or an os.PathLike object where __fspath__
returns a str, not 'NoneType'
__file__ 是 None,于是 Path(ns.__file__).parent 这一行 —— 出现在无数项目的日志配置、资源加载、模板路径里 —— 直接抛 TypeError,而且报错信息里连变量名都没有,只说 not 'NoneType'。
所以「包目录要不要放 __init__.py」不是风格问题,是契约问题:只要有任何一处代码依赖 包.__file__(哪怕只是为了打印一下启动路径),就得放。需要读包内资源文件的话,正确工具是 importlib.resources,它按 __path__ 找,不依赖 __file__。
陷阱七:同一个文件可以是两个模块对象
sys.modules 的键是字符串,精确匹配。而文件系统可能不区分大小写。这两件事凑在一起,就有了「一个文件、两个模块」。
Windows 上的默认行为其实是大小写敏感的:目录里有 Casemod.py,写 import casemod 会得到 ModuleNotFoundError: No module named 'casemod'。但文档里还留着一个开关:「If this is set, Python ignores case in import statements. This only works on Windows and macOS.」设上 PYTHONCASEOK=1 再跑同一段代码:
same object = False
STATE = ['x'] []
isinstance across both = False
sys.modules keys = ['Casemod', 'casemod']
四项全中:两个模块对象、两个列表、isinstance 跨两个类对象返回 False(不报错,就是 False)、sys.modules 里两个键指向同一个文件。
这就是最难查的一类线上问题:类型检查全对、逻辑全对、对象就是过不了 isinstance;注册表单例看起来「有时候生效」。它和两个看起来一样的字符串为什么永远不相等是同一个母题 —— 你看见的身份和解释器使用的身份是两样东西。修法很土但有效:统一命名规范并在 CI 里禁止设置 PYTHONCASEOK;如果你在大小写不敏感的文件系统上工作(macOS 默认如此),这条值得自己跑一遍 —— 我没有 macOS 机器,这一句只作提醒,不作为结论。
陷阱八:reload 不重绑已经 from-import 出去的名字
热更新脚本最喜欢 importlib.reload()。它做的事比多数人以为的少。
实测:模块 m 里 f() 返回 'v1';主程序同时 from m import f 和 import m;运行中把 m.py 改成返回 'v2';然后 importlib.reload(m)。结果:
before = v1
module.f() = v2
bound f() = v1
f is m.f = False
reload 确实重编译、重执行了模块体,m.f 已经是新函数;但你之前 from m import f 绑到局部命名空间的那个名字,还是旧函数对象。官方文档把这条写在 caveats 里:「Other references to the old objects (such as names external to the module) are not rebound to refer to the new objects and must be updated in each namespace where they occur if that is desired.」
同一段文档里还有一句更阴的:「If the new version of a module does not define a name that was defined by the old version, the old definition remains.」删掉的函数不会消失 —— 模块字典是先保留再覆盖的。
顺带把三种 import 形式各自绑定什么量清楚了,这在排 NameError 时很省时间:
| 写法 | 绑定的名字 |
|---|---|
import pkg.mod | 只绑 pkg,mod 未绑定 |
import pkg.mod as mm | 只绑 mm,连 pkg 都不绑 |
from pkg import mod | 只绑 mod |
第一种后面写 mod.VALUE 会得到 NameError: name 'mod' is not defined,而 pkg.mod.VALUE 正常 —— 这个不对称每年都要坑一批人。
Troubleshooting:三条命令定位「这个模块到底从哪来」
第一步,打印来源。在任何怀疑点上插一句 print(json.__file__),或者对包用 print(pkg.__path__)。这一步能解决七成问题,因为它把「我以为」换成了一行路径。
第二步,不导入也能查。importlib.util.find_spec('json').origin 直接给出将被加载的文件,不会执行模块体。我这边输出是:
C:\Users\xuany\.workbuddy\binaries\python\versions\3.13.12\Lib\json\__init__.py
第三步,看导入耗时找异常。python -X importtime 的输出走 stderr,格式是三段:自身耗时、累计耗时、模块名,单位微秒。我这边 json 那一行是:
import time: 987 | 18903 | json
自身 987 微秒、含依赖累计 18,903 微秒。真正有用的是发现「某个你根本没写的模块被导入了」以及「某个模块出现在意料之外的路径下」——把 stderr 重定向到文件再按模块名排序,比读代码快。
再加一条隐形的:python -v 会把每个模块「从哪个文件加载、缓存命中与否」逐行打出来,前面陷阱三那条 matches 就出自它。它的输出量很大,只在锁定单个模块时用。
如果你只想记一张清单,记这六条:
- 项目根目录不要出现与标准库同名的文件(
json.py、types.py、random.py、logging.py、queue.py是高发名单) - 包内代码用
python -m pkg.module跑,不要python pkg/module.py - 需要
__file__的包,放一个空__init__.py - 生成代码后立刻导入的流程,加
PYTHONDONTWRITEBYTECODE=1或改用哈希 pyc - 循环导入优先把 import 挪进函数,而不是调整赋值顺序
- 热更新只用
import m; m.f(),不要依赖from m import f加reload
本文的边界
我在这台机器上只测了 CPython 3.13.14 与 Windows 11 的组合。以下都没测,不当结论用:macOS 与 Linux 的大小写与 mtime 行为;Docker 镜像层的 mtime 处理与只读文件系统下 pyc 写入失败的表现;PyPy 与 freezer 工具链;zipimport 与冻结模块;3.8 到 3.12 各版本之间的提示文案差异(3.13 的改名提示与 -P 都是较新的东西)。第八条的 reload 行为在文档里写了很久,但具体到你的框架是否包装过 reload,只能自己验。同一条思路用在数值上,是金额舍入的八处静默分歧。
FAQ
Q:删掉 __pycache__ 是不是就干净了?
只解决缓存那一层。同名遮蔽、循环导入、__main__ 双份都与 pyc 无关;而且下次导入会重新生成缓存,在生成代码的场景里旧问题会立刻回来。反过来,如果一个「改了没生效」的问题删缓存就好了,那基本可以确认是陷阱三。
Q:pip 装了一个叫 json 的包,会顶掉标准库吗?
按这台机器实测的 sys.path 顺序,site-packages 排在标准库目录之后,所以不会。真正危险的是脚本所在目录与 PYTHONPATH —— 这两处都排在标准库之前。区别的原因在查找顺序,不在名字。
Q:本地跑得好好的,容器里为什么 ModuleNotFoundError?
先看启动方式。python pkg/mod.py 把 pkg/ 目录放进了 sys.path[0],仓库根不在路径上;容器里的工作目录又常常与本地不同,于是同一个命令在两边命中不同的路径项。用 python -m 并把工作目录固定,能消掉这一类。
Q:import a.b 之后为什么 b 用不了?
因为 import a.b 只绑定 a。要么写 a.b.x,要么 from a import b,要么 import a.b as b。这是语法层面的规定,和模块找不找得到无关。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。