Python 导入了错误的模块：定位同名文件遮蔽与解释器路径

脚本里写了 import json，下一行却报 AttributeError: module 'json' has no attribute 'loads'。标准库没有坏掉；项目里一个叫 json.py 的辅助脚本，就可能让 Python 导入错误的文件。

本文面向初学者到中级读者，用一个可重复的小实验定位解释器、模块来源和搜索路径，再通过改名修复。适合 Linux 自动化脚本、数据处理工具，以及调用 Python 的 Hugo 构建入口；不需要安装第三方包。

1. 方法：先看模块来自哪里

按这个顺序排查：

确认失败任务实际使用的 Python 解释器。
查看模块的 origin，判断是否指向项目里的同名文件或包。
用隔离模式做对照，再修正名称或运行环境。

Python 搜索路径文档说明：通常运行脚本时，脚本目录排在搜索路径开头；使用 -c、-m 或交互模式时，当前目录会进入搜索路径。因此 json.py、logging.py、csv.py 这类文件名容易遮蔽原本想用的模块。同名的包目录也可能造成问题。

这不是所有导入错误的统一原因。ModuleNotFoundError 可能来自错误的虚拟环境，cannot import name 也可能来自版本差异或循环导入；需要结合 traceback 中的具体路径判断。

2. 准备环境，复现同名文件故障

需要 Linux、Python 3.9 或更新版本，以及 bash 或 zsh。示例已在 Python 3.11.4 上验证；不用 pip，也不修改系统 Python。

新建一个演示目录，后续步骤都在同一目录中执行。重复实验时使用新目录名：

python3 --version
python3 --help
mkdir import-shadow-demo
cd import-shadow-demo
printf 'SOURCE = "local helper"
' > json.py

尝试调用标准库的 JSON 解析函数：

if python3 -c 'import json; print(json.__file__); print(json.loads("true"))'; then
  printf 'Unexpected success: inspect the environment
'
else
  printf 'Expected failure: local json.py has no loads()
'
fi

你会先看到演示目录里的 json.py 路径，然后看到缺少 loads 的 AttributeError，最后是 Expected failure。if 显式处理了这次预期失败，避免开启 set -e 的 shell 提前退出。若意外成功，先按下一节检查来源，不要继续假定复现条件成立。

这个 json.py 只有一个变量，故意没有定义 loads()。例子复现的是导入成功但导错对象，不是 JSON 数据格式错误。

3. 定位解释器和模块来源

查看当前命令用的解释器与环境前缀：

python3 -c 'import sys; print("executable:", sys.executable); print("prefix:", sys.prefix); print("base_prefix:", sys.base_prefix)'
command -v python3

普通 venv 中，sys.prefix 与 sys.base_prefix 通常不同。command -v 反映 shell 的命令查找结果，sys.executable 则显示本次进程的解释器路径。诊断真实任务时，应使用任务入口里的同一个解释器，并在同样的启动目录复现；虚拟环境的创建和依赖管理可参考 uv 项目环境教程。

在导入 json 前查找它的模块规格：

python3 - <<'PY_PROBE'
import importlib.util
import sys

name = "json"
spec = importlib.util.find_spec(name)
print("executable:", sys.executable)
print("origin:", None if spec is None else spec.origin)
print("package_paths:", None if spec is None else spec.submodule_search_locations)
print("sys.path:")
for entry in sys.path:
    print(" ", repr(entry))
PY_PROBE

本例的 origin 应指向当前演示目录里的 json.py；它是普通模块，所以 package_paths 为 None。搜索路径中的空字符串 '' 表示当前目录。改查其他模块时，只替换 name 的值。

find_spec() 官方说明区分“找不到规格”和“执行导入”：顶层模块不存在时通常返回 None；找到规格不保证模块执行成功。这里使用顶层名称 json，不会执行这个示例文件；若改成 package.child，查找过程会导入父包。它不是运行不可信项目的安全沙箱。

4. 对照隔离模式，再改名修复

先保持 json.py 原样，执行隔离模式：

python3 -I -c 'import json; print(json.__file__); print(json.loads("true"))'

此时应看到标准库的 json/__init__.py 路径和 True。-I 官方文档说明，隔离模式会排除脚本目录或当前目录、用户级 site-packages，并忽略 PYTHON* 环境变量。对照成功提示问题与这些输入有关；单凭 -I 成功，不能断定一定是同名文件。本例还通过 origin 确认了具体遮蔽来源。

给自己的辅助模块改一个有业务含义的名字：

mv -i json.py json_helpers.py
python3 -c 'import json; print(json.__file__); print(json.loads("true"))'
python3 -c 'import json_helpers; print(json_helpers.SOURCE)'

第二条命令应输出标准库路径和 True，第三条输出 local helper，说明辅助代码仍然可用。mv -i 会在目标已存在时询问，避免覆盖已有辅助文件；本次新建目录中该目标应不存在。实际项目还要把对旧辅助模块的引用改成新名字。

每条命令都是新进程，因此改名后会重新查找模块。Notebook、常驻服务或交互解释器已经缓存了导入对象时，应重启对应 Python 进程或内核后验证；本例不需要删除整个 __pycache__。

不要把 -I 直接追加到所有生产命令：依赖项目本地模块的程序也可能因此无法导入。这里用它定位路径影响，修复名称才恢复了普通运行方式。

5. 自动验证成功和失败分支

下面的自检独立于前面演示文件，可直接复制运行。它在自己的临时目录创建夹具，检查退出码和实际输出，结束后自动清理；不会删除前面的演示目录。

python3 -I - <<'PY_CHECK'
from pathlib import Path
import os
import subprocess
import sys
import tempfile

env = os.environ.copy()
for key in list(env):
    if key.startswith("PYTHON"):
        del env[key]

def run(folder, code, isolated=False):
    flags = ["-I"] if isolated else []
    return subprocess.run(
        [sys.executable, *flags, "-c", code], cwd=folder, env=env,
        capture_output=True, text=True, timeout=10, check=False,
    )

with tempfile.TemporaryDirectory(prefix="import-shadow-test-") as tmp:
    folder = Path(tmp)
    local = folder / "json.py"
    local.write_text('SOURCE = "local helper"\n', encoding="utf-8")
    probe = run(folder, "import importlib.util; print(importlib.util.find_spec('json').origin)")
    assert probe.returncode == 0 and Path(probe.stdout.strip()) == local, probe

    check = "import json; print(json.loads('true'))"
    failed = run(folder, check)
    assert failed.returncode != 0 and "AttributeError" in failed.stderr, failed
    isolated = run(folder, check, isolated=True)
    assert isolated.returncode == 0 and isolated.stdout.strip() == "True", isolated

    local.rename(folder / "json_helpers.py")
    fixed = run(folder, check)
    assert fixed.returncode == 0 and fixed.stdout.strip() == "True", fixed
    helper = run(folder, "import json_helpers; print(json_helpers.SOURCE)")
    assert helper.returncode == 0 and helper.stdout.strip() == "local helper", helper

    package = folder / "json"
    package.mkdir()
    (package / "__init__.py").write_text("", encoding="utf-8")
    package_fail = run(folder, check)
    assert package_fail.returncode != 0 and "AttributeError" in package_fail.stderr, package_fail
    missing = run(folder, "import importlib.util; print(importlib.util.find_spec('demo_missing_74219'))")
    assert missing.returncode == 0 and missing.stdout.strip() == "None", missing

print("OK: file shadowing, isolated mode, rename, helper, package shadowing, missing module")
PY_CHECK

预期输出：

OK: file shadowing, isolated mode, rename, helper, package shadowing, missing module

测试还覆盖 json/__init__.py 同名包，以及顶层模块不存在时 find_spec() 返回 None。子进程设置了 10 秒等待上限，预期失败不会被当成成功。

6. 常见错误与下一步

现象	具体处理
`origin` 指向项目里的 `json.py` 或 `json/__init__.py`	给自己的文件或包改名，同步修改引用，再用新进程验证。
`find_spec()` 返回 `None`	核对模块名和 `sys.executable`，再检查依赖是否装在该项目环境中。标准库 `json` 不需要另装同名 pip 包。
`origin` 正确，但仍报 `cannot import name`	查看完整 traceback 中最早涉及自己代码的位置，检查双方循环导入和实际安装版本。
只有定时任务失败	对齐任务使用的解释器和启动目录，按定时任务路径与环境排查检查入口。
改名后常驻进程仍看到旧模块	重启对应进程或 Notebook 内核，再检查来源。不要在运行中的服务里随意清空整个 `sys.modules`。

origin 也可能是 built-in、frozen 或 None，不能一概视为错误；例如命名空间包可以没有普通源文件。对本例的 json，应结合 __file__ 与实际调用结果判断。

如果 Python 进程还没有启动就报 bad interpreter，应先检查 Linux 脚本的 CRLF 与 BOM，导入排查要等解释器成功启动后再做。

7. 小结

遇到模块缺少属性，先记录解释器路径和模块来源，再决定是否需要处理依赖。用同名文件复现、隔离模式对照、改名后新进程验证，可以把路径遮蔽与环境问题逐步分开。将这组检查放进排障流程，能减少对系统 Python 和全局包的无效修改。