徐术挺-漫思录

10-包与模块

22分钟阅读

第 10 章 包与模块：import 机制深坑

这一章拆解 Python 的 import 系统，帮你彻底搞懂循环导入为什么炸、绝对导入和相对导入怎么选、以及 sys.path 那些看不见的暗坑——对照 Go 的 package 和显式导入路径，你会明白两边设计哲学差在哪。

墨叔：老哥，你在 Go 里写 import "github.com/foo/bar"，路径写死、编译器按路径找、环依赖直接编译不过。Python 里你大概也写过 import os、from mypkg import utils，然后某天改了目录结构，突然满屏 ModuleNotFoundError 或者更诡异的「导入了但对象是 None」。这些错你搜半天，最后靠把 import 挪到函数里才「玄学地好了」。今天咱们把 import 这团浆糊彻底搅清。

老哥：说实话，import 我一直当黑盒。能跑就跑，跑不了就瞎挪，从不深究。

墨叔：那就对了，90% 的 Python 循环导入「玄学修复」都是因为不懂底层。这章我带你从「模块和包到底是什么」一路干到「sys.path 怎么决定一切」，每一步都对照 Go，让你以后遇到 import 报错，能直接在脑子里推演原因，而不是瞎试。

一、模块与包到底是什么（怎么用）

先破一个最基础的混淆：模块（module）是一个 .py 文件；包（package）是一个含 __init__.py 的目录（Python 3.3+ 后甚至可以不带，但工程里建议带）。当你写 import foo，解释器去找 foo.py（模块）或 foo/（包）。

# 文件结构
# myproj/
#   __init__.py
#   config.py
#   auth/
#     __init__.py
#     login.py
 
# 在 myproj 外运行
from myproj.config import load
from myproj.auth.login import do_login

__init__.py 的作用你可能只知道「标记这是个包」，但其实它是包被导入时最先执行的代码。你可以在里面做初始化、定义 __all__（控制 from pkg import * 导出的名字）、或把子模块的内容提升上来：

# myproj/__init__.py
from myproj.config import load        # 让外部能直接 from myproj import load
__all__ = ["load", "do_login"]

对照 Go：package 声明在文件顶部，包的导入路径就是目录在 module 里的相对路径，编译器从 go.mod 的 module 名 + 目录拼出全路径，一切显式、无歧义。Python 的 import 则依赖一个运行时搜索列表 sys.path（下一节讲），路径不是写死的，是运行时凑出来的——这就是 Python import 坑多的根因：它是动态的、有状态的。

墨叔：你记住一句话——Go 的导入是编译期、路径确定、无副作用；Python 的导入是运行时、搜索列表可变、导入即执行。这两个「即执行」是万恶之源：你 import 一个模块，它顶层的所有代码（包括可能很重的初始化、甚至发网络请求）都会跑一遍。这也是为什么 Python 里能出现「循环导入」，而 Go 因为先编译全图、检查环，直接拒掉。

二、绝对导入 vs 相对导入（怎么选）

Python 两种导入写法：

# 绝对导入：从「顶层包」写全路径
from myproj.auth.login import do_login
 
# 相对导入：用点表示相对当前包
from .login import do_login          # . 表示当前包
from ..config import load            # .. 表示上级包
from .sub.mod import thing           # 子包

关键规则：相对导入只能在「作为包的一部分被导入」的模块里用，不能在一个直接被 python xxx.py 当脚本运行的文件里用——因为脚本的 __package__ 是 None，解释器不知道「相对谁」。这也是「我直接跑这个文件就报 ImportError: attempted relative import with no known parent package」的真正原因。

对照 Go：Go 没有相对导入，全是绝对路径（基于 module 名），从根上避免了「相对谁」的歧义。Python 保留相对导入，是为了让一个包能被整体改名或移动而不必改内部引用——比如把 myproj 改名为 myapp，包内部用相对导入的代码一行都不用动。

老哥：那我项目里该用哪种？

墨叔：经验法则——库代码（要被别人 import 的）内部用相对导入，保持可移植；应用代码（你自己的服务，入口明确）用绝对导入，路径清晰、不容易错。混用也行，但别在一个文件里 from .a import x 和 from myproj.a import y 同时出现，那会创建两份模块对象，产生「同一个类 import 两次却是不同类型」的诡异 bug（isinstance 判断失败）。一个包内部统一风格，这是铁律。

三、循环导入：成因与解法（核心坑）

这是你最痛的点，咱们拆透。循环导入就是 A 导入 B，B 又导入 A。

# a.py
from b import B
class A: ...
 
# b.py
from a import A
class B: ...

你一运行 import a，发生什么？解释器开始执行 a.py：执行到 from b import B，它暂停 a，转去执行 b.py；b.py 执行到 from a import A，此时 a 还没执行完（卡在 import b 那行），a 模块对象虽然在 sys.modules 里，但 A 这个类还没定义好，于是 from a import A 报 ImportError: cannot import name 'A'。死锁一样的相互等待。

老哥：Go 直接编译不过，反而省心。Python 为什么允许这种破事存在？

墨叔：因为 Python 的「先执行模块、边执行边记录到 sys.modules」机制是惰性的、运行时的。它允许模块在「还没完全初始化」时就被引用，大部分情况下没问题（你只在函数内部用到对方，真正调用时双方都好了）。只有当模块顶层就互相引用对方的名字时，才爆。所以循环导入不是「设计错误」，而是「在错误的地方（顶层）过早依赖」。

解法有四招，按推荐程度：

第一招（最推荐）：把 import 移进函数/方法内部。 顶层只做「必要」的导入，把循环依赖的那个 import 放到真正用到它的函数里——函数执行时双方早初始化完了。

# a.py
class A:
    def use_b(self):
        from b import B     # 延迟导入，运行时才执行
        return B()

第二招：重构，抽出公共依赖到第三个模块。 A 和 B 都依赖的东西，放到 common.py，A 导入 common、B 导入 common，A 和 B 互不导入。这是治本——循环往往说明「抽象没分好层」。

第三招：用 TYPE_CHECKING 做类型注解的导入隔离。 很多时候循环只是为了类型注解（mypy 需要），运行时不真正用：

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from b import B        # 只在类型检查时导入，运行时完全不执行
 
def f(x: "B") -> None: ...

TYPE_CHECKING 是 False 运行时，所以这段 import 不会真执行，循环消失，mypy 又能拿到类型。

第四招：合并模块。 如果 A 和 B 紧耦合到必须互相 import，说明它们本该是一个模块，直接合并。

老哥：所以遇到循环导入，第一反应不该是「瞎挪 import」，而是看「是不是该分层」？

墨叔：对！绝大多数是架构信号，不是语法问题。Go 编译期直接拦掉，逼你一开始就想清楚依赖方向；Python 把这个责任推给你自己——灵活但容易烂。你会用前面三招，循环导入就再也不是玄学了。

四、命名空间包与 sys.path 暗坑

墨叔：讲完循环导入，再给你挖两个更隐蔽的坑。

坑一：sys.path 怎么决定「能 import 谁」。 import foo 时，解释器按 sys.path 这个列表挨个目录找 foo.py 或 foo/ 包。sys.path 默认包含：当前脚本所在目录、环境变量 PYTHONPATH、标准库、以及安装包的 site-packages。问题就在这「当前目录」——你从哪个目录运行 python，那个目录就被加进 sys.path[0]。所以同一个项目，在不同目录运行，能 import 的模块可能完全不同。

import sys
print(sys.path[:3])   # 第一个通常是你启动脚本的目录

最常见的翻车：项目根目录有个 utils.py，你在 src/ 下运行 python main.py，main.py 里 import utils 找不到，因为 src/ 不在 sys.path 里——但你在根目录运行却又能找到。这种「在我机器上能跑」的玄学，根源就是 sys.path 随启动目录变。

对照 Go：Go 的路径从 go.mod 的 module 根 + 导入语句完全确定，跟「从哪运行」无关。Python 这点就是动态语言的代价。

坑二：同名遮蔽。 如果你自己写了个 utils.py，又恰好和标准库或第三方包撞名（比如 email.py、json.py、test.py），import email 可能 import 到你的文件而不是标准库——因为当前目录在 sys.path 里排第一。所以千万别用和标准库/热门库同名的文件，这是新手高频坑。

坑三：命名空间包（namespace package）。 Python 3.3+ 引入了「没有 __init__.py 也能当成包」的命名空间包。好处是能把分散在多个目录的同名「虚拟包」合并成一个；坏处是你忘了放 __init__.py，代码居然还能跑，但行为可能和你想的不一样（导入顺序、相对导入限制）。工程上我的建议：凡是要当正式包的目录，老老实实放 __init__.py，别依赖命名空间包的隐式行为，否则团队成员在不同 Python 版本/环境下会踩不一致的坑。

一个正确管理 sys.path 的工程做法：用可安装包（pip install -e . 配合 pyproject.toml，第 11 章细讲），把项目根登记进环境，这样无论从哪运行都能稳定 import，不再依赖「当前目录」——这等价于 Go 的 module 路径确定感。

坑四：import 只执行一次，缓存进 sys.modules。 你大概听过「同一个模块 import 多次只执行一次」，但很少人想透它意味着什么。解释器每成功导入一个模块，就把它放进全局字典 sys.modules；之后再 import 同一个模块，直接返回缓存，顶层代码不再执行。这带来两个后果：一是模块级状态（全局变量、单例）天然是「进程内唯一」，相当于 Go 的包级变量，这通常是你想要的；二是你想「重新执行一遍模块初始化」做不到，除非用 importlib.reload()（但 reload 很危险，会制造新旧对象混存的半初始化状态，生产代码千万别用）。

还有个和 import 强相关的老朋友：if __name__ == "__main__":。当一个文件被 import 时，它的 __name__ 是包路径（如 "myproject.config"）；只有当它作为主程序直接运行时，__name__ 才是 "__main__"。所以 if __name__ == "__main__": 块里的代码，在 import 时不会执行——这正是为什么你能安全地 import 一个「同时也带命令行入口」的模块，而不触发它的主逻辑。对照 Go：Go 的 package main 和 func main() 是绑死的，一个文件要么是库要么是入口，不存在「同一文件既是库又是入口、靠运行方式区分」的玩法。Python 这个机制让单文件既能当库被复用、又能当脚本直接跑，灵活但要求你清楚「哪些代码该放进 __main__ 守卫里」。

坑五：绝对不要依赖「运行目录」能 import 到什么。 很多新手在 __init__.py 或脚本里写 import config（期望找到根目录的 config.py），在自己机器根目录跑通了，一上 CI 或从别处运行就 ModuleNotFoundError。记住：依赖「当前目录在 sys.path」的代码是不可移植的。正确做法是让项目通过 pyproject.toml 安装进环境（包名确定、路径确定），所有 import 都从顶层包名写起（绝对导入）。这把「从哪运行」这个不确定性彻底消除——和你 Go 项目「无论在哪编译，module 路径都确定」的体感一致。

五、一个贴近项目的例子

给你一个能直接照抄的、不会踩坑的项目骨架和导入约定：

myproject/
├── pyproject.toml          # 声明可安装，项目根进 sys.path
├── myproject/
│   ├── __init__.py
│   ├── config.py
│   ├── db.py
│   └── auth/
│       ├── __init__.py
│       ├── login.py        # 内部用相对导入 from ..db import get_conn
│       └── token.py
└── tests/
    └── test_login.py       # 用绝对导入 from myproject.auth.login import do_login

auth/login.py 内部：

from ..db import get_conn          # 相对导入，包内稳定
from ..config import settings
 
def do_login(user, pwd):
    conn = get_conn()
    ...

tests/test_login.py：

from myproject.auth.login import do_login   # 绝对导入，从安装后的顶层包起
 
def test_do_login():
    assert do_login("a", "b") is not None

约定：库内部相对、外部/测试绝对；所有包都有 __init__.py；项目用 pyproject.toml + pip install -e . 安装，避免依赖运行目录。这套骨架能让你和 Go 项目一样，import 行为可预测、可复现。

六、收益与代价（为什么这么设计）

墨叔：最后把 Python import 的设计取舍讲清，你才能既用得好又不抱怨。

收益：

  • 运行时导入 + 导入即执行，带来极强的灵活性：可以根据环境变量、命令行参数、甚至运行时探测到的平台，决定导入哪个实现（插件机制、平台分支实现都靠这个）。Go 的编译期导入做不到这种「动态选实现」。
  • 相对导入 + 命名空间包让包可被移动、拆分、合并，重构成本低。
  • sys.path 可变意味着你能动态扩展搜索路径（比如插件目录运行时加进去），适合插件化架构。

代价：

  • 导入有副作用（顶层代码会执行），模块级的状态可能被 import 顺序影响，产生「难以复现的初始化顺序 bug」。
  • 灵活性换来的是不确定性和坑：循环导入、同名遮蔽、sys.path 随目录变。Go 用「编译期全图检查 + 显式路径」把这些都掐死在出厂前，Python 把责任交给开发者。
  • 调试难度高：import 错误往往发生在程序最早期（ModuleNotFoundError 连你的日志都还没起来），而且报错信息有时指不到真正的根因。

老哥：所以 Python 的 import 不是「烂」，是「把 Go 在编译期帮你做的事，挪到你运行时自己负责」。

墨叔：一语中的。理解了这点，你就不会再骂 Python import 反人类，而是会像高级工程师那样——用可安装包固定路径、用分层避免循环、用相对/绝对分离保清晰。这跟你用 Go 时「约束自己写好 package 依赖方向」是同一种工程纪律，只是 Python 给的绳子更长，你也更容易勒到自己。

【思考题】

  1. 你在 Go 里从不会出现循环导入（编译期就拒了），但 Python 允许且常出现。如果让你设计一个 Python 模块，A 和 B 互相需要对方的类型做注解，但运行时不需要对方的对象，你怎么写才能既消除循环导入又保留类型检查？
  2. 你项目里有个 utils.py 直接在仓库根目录，团队里有人从根目录跑测试能过、有人从子目录跑就 ModuleNotFoundError。用本章的 sys.path 知识解释根因，并给出两种工程化的根治方案。
  3. Python「导入即执行」有利有弊。举一个你项目里「希望导入时就跑初始化」的合理场景，再举一个「导入时执行了不该执行的重逻辑导致问题」的反例，并说怎么规避。

【参考答案】

  1. 用 from typing import TYPE_CHECKING 做导入隔离： 
    # a.py
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from b import B          # 仅类型检查期导入，运行时跳过
def f(x: "B") -> None: ...   # 注解用字符串/引号形式
    TYPE_CHECKING 运行时为 False，所以 from b import B 不会真正执行，循环消失；mypy 在静态检查时会把它当 True 处理，仍能校验 B 类型。配合字符串注解 "B"（或在 3.11+ 用 from __future__ import annotations 让所有注解惰性化），彻底消除运行期循环。这是 Python 社区处理「注解型循环依赖」的标准解法，等价于 Go 里「类型只在编译期存在、运行期无负担」的特性。
  2. 根因：sys.path[0] 是「启动脚本所在目录」。从根目录跑，根目录进 sys.path，import utils 能找到；从子目录跑，子目录进 sys.path，根目录不在里面，utils 找不到。这正是「在我机器能跑」的经典来源——import 行为依赖启动目录。根治方案：① 把项目做成可安装包（pyproject.toml + pip install -e .），项目根（包目录）被登记进环境，无论在哪运行都能稳定 import，等价于 Go 的 module 路径确定；② 在测试/启动入口显式把根目录加入 sys.path（如 sys.path.insert(0, PROJECT_ROOT)），但不如方案①干净，且易引入重复路径。推荐①，这也是第 11 章要讲的工程化基线。
  3. 合理场景：插件系统在入口 import plugins 时，利用「导入即执行」在模块顶层把自身注册进全局插件表（PLUGINS.register(...)），框架启动时只需遍历安装好的包即可发现所有插件，无需手动登记——这是 import 副作用的正面用法。反例：某模块顶层直接 requests.get(config.url) 去拉远程配置，结果「导入该模块就发网络请求」，导致单元测试 import 阶段就卡住/超时，且 import 顺序不同行为不同。规避：把重逻辑（网络、文件 IO、全局状态初始化）移出模块顶层，放进显式的 init() / configure() 函数，由入口在合适的时机主动调用；模块顶层只放轻量、无副作用的定义。这跟 Go 里「包级 var 初始化要轻、重活在 func init() 且 init 也要快」是同样的纪律。

反向链接