遮蔽标准库

Shadowing the Standard Library — nesbitt.io · 17 小时前 · 🔒 安全

标准库遮蔽是 Python 里最容易被忽视、又最容易白白浪费一个下午的故障模式：解释器启动时会把脚本所在目录插到 sys.path 的最前面，用 python -m、python -c 或交互式解释器时插入的则是当前工作目录，于是同目录下一个叫 json.py、types.py、random.py 或 logging.py 的文件，就会顶替掉标准库里的同名模块。作者的结论直接写在最前面——export PYTHONSAFEPATH=1。这个环境变量在 Python 3.11 引入，语义是不要把一个不安全的路径前置到 sys.path，脚本目录以及 -m/-c/REPL 场景下的当前工作目录都不再被自动加入，等价的命令行开关是 python -P，运行期可以通过 sys.flags.safe_path 检查它是否生效。这类 bug 的难缠之处在于症状与病因完全脱节：报错往往出现在完全无关的第三方库内部，表现为 ImportError、AttributeError 或某个函数签名对不上，而且只在特定目录下运行、或者只在 CI 与本地之间切换时才会出现，让人反复怀疑依赖版本而不是文件名。它同时是一条被低估的攻击面：只要能在目标的工作目录里落下一个与标准库同名的文件，就能劫持整个进程的导入行为，供应链攻击、恶意仓库和「先跑一下安装脚本」的习惯都会放大这个风险。在 3.11 之前，唯一可用的手段是 -I 隔离模式，但它同时会忽略 PYTHONPATH 和用户级 site-packages，副作用太大，因此 PYTHONSAFEPATH 的价值在于把「去掉不安全的隐式路径」与「保留显式配置」这两件事解耦。需要注意的是，开启之后依赖同目录兄弟模块导入的项目会立刻报错，需要改成显式安装为包或自行调整 sys.path；PYTHONPATH 与 site-packages 的行为不受影响，site-packages 内部的重名冲突也不在它的解决范围内。

核心论点

• 遮蔽的机制非常简单且不可绕过：Python 启动时把 sys.path[0] 设为脚本所在目录，用 python -m、python -c 或 REPL 时设为当前工作目录，而它排在标准库之前，所以一个名为 types.py、json.py、random.py 或 logging.py 的本地文件会静默地替换掉标准库同名模块，连标准库内部的其他模块在导入时也会拿到这个冒牌货。
• 这类故障最难处理的地方是症状与病因脱节，报错通常出现在完全无关的第三方库内部，表现为 ImportError、AttributeError 或函数签名不匹配，并且只在特定目录、特定启动方式或 CI 与本地之间切换时复现，导致排查方向长期锁定在依赖版本上；它同时是一条被低估的攻击面，只要能在目标工作目录落下一个同名文件，就能劫持整个进程的导入行为。
• 作者给出的修复是 export PYTHONSAFEPATH=1，该环境变量自 Python 3.11 起提供，作用是停止把一个不安全的路径前置到 sys.path，脚本目录与 -m/-c/REPL 下的当前工作目录都不再自动加入，等价的命令行选项是 python -P，运行期可用 sys.flags.safe_path 判断是否生效；在 3.11 之前只能退而求其次使用 -I 隔离模式。
• 选择 PYTHONSAFEPATH 而非 -I 的关键理由在于解耦：-I 会同时忽略 PYTHONPATH 和用户级 site-packages，把显式配置也一并砍掉，而 PYTHONSAFEPATH 只移除那个不安全的隐式前置路径，保留 PYTHONPATH 与 site-packages 的正常语义，代价是依赖同目录兄弟模块导入的项目必须改成显式打包安装或自行调整 sys.path。

💡 为什么值得读: 它把一个人人都踩过、却几乎没人系统化处理的 Python 陷阱讲清楚了，并给出可以直接写进 CI 和 shell 配置的一行修复方案。

🏷️ Python, PYTHONSAFEPATH, standard library, security

---