如果你写过稍微大一点的 Python 项目，多半遇到过这些让人抓狂的情况：一个跑得好好的脚本，换个目录就报ModuleNotFoundError；自己的电脑上一切正常，发给同事就崩；明明是同一个项目里的文件，互相 import 却老是提示找不到。这些问题背后，几乎都指向同一个东西——Python 模块和包引用配置。
这篇文章我打算把这块彻底讲透。先说 Python 到底是怎么找到模块的，再说清楚几种常见的引路方式分别适合什么场景，接着把最让人头疼的相对导入掰扯明白，最后给出一套我在实际项目里反复验证过的工程化目录结构与配置习惯。不管你是刚入门的新手，还是写了几年 Python 但一直靠“试错”解决 import 问题的老手，看完这篇应该都能少走不少弯路。
1. 先从一行 import 说起：Python 找到模块的完整链路
很多人遇到 import 报错，第一反应是去百度一段sys.path.append粘上去。这本质上属于头痛医头，一旦目录结构再变一变，问题又会复发。想根治，就得先搞清楚 Python 解释器执行import xxx时，背后到底发生了几件事。
1.1 import 语句背后发生的事
当你在代码里写下import requests，Python 不会真的去磁盘上逐层扫描所有目录，而是严格按一套固定流程来：
第一步，检查sys.modules这个字典。它是一个内存级缓存，记录着所有已经成功导入过的模块。如果requests已经在里面，解释器直接把它拿回来用，不会重新执行模块代码。
第二步，如果缓存里没有，Python 会按照sys.path里列出的目录顺序，逐个去寻找名为requests的模块或者名为requests的包。找的时候，一个目录下会依次尝试三种形态：requests.py文件、requests/目录（含__init__.py的常规包，或 Python 3.3 之后无__init__.py的命名空间包）、以及内建模块。
第三步，找到了之后，Python 会创建模块对象、执行模块里的代码，然后把它放进sys.modules缓存里，这样后续 import 就直接命中缓存。
理解这个流程，你就能明白大多数 import 问题的根源：不是“文件存在就一定能被找到”，而是“文件必须存在于 sys.path 覆盖的范围内”。模块文件就在你眼前，可解释器根本没被告诉要去那个目录找。
1.2 sys.path：一切问题的核心
sys.path说白了就是一个按顺序排列的目录列表。你可以用下面几行代码随时查看自己当前环境里的实际值：
import sys for i, path in enumerate(sys.path): print(i, path)不同运行方式下，这个列表的首位会不一样，这是新手最容易忽略的坑。以最常见的三种启动方式为例：
| 启动方式 | sys.path[0] 的值 | 典型影响 |
|---|---|---|
python script.py运行脚本 | 脚本所在目录 | 直接能找到同目录下的兄弟模块 |
python -m pkg.module以模块方式运行 | 当前工作目录 | 必须从项目根目录找到包路径 |
| 在 Python 交互式解释器里 | 空字符串，代表当前目录 | 当前目录下的模块可被找到 |
除了首位目录，后面依次还有PYTHONPATH环境变量指定的目录、标准库目录，以及site-packages里所有第三方库和可安装包的目录。很多人误以为把项目里的所有.py文件放一起就万事大吉，其实只要目录层级一深、运行入口一变，sys.path 的覆盖范围就会跟着变，找不到模块是必然结果。
1.3 已经被导入过的模块不会再执行第二次
sys.modules 缓存的存在，带来一个很多初学者理解相反的现象：同一个模块文件，在一个进程内只会被真正“执行”一次。
# a.py print("a.py 正在执行") value = 42 # main.py import a import a import importlib importlib.reload(a) # 强制重新执行一次运行 main.py，print只会输出一次，除非你显式调用importlib.reload()。这个特性平时挺好用，避免了重复执行带来的性能浪费，但坑也很实际：如果你在模块顶层写了一些“立刻执行”的代码（比如连接数据库、读取大文件），那么它所在模块一旦被任何一个文件 import，这些代码就会在 import 发生时立刻执行。这既是设计要点，也是很多隐蔽 Bug 的来源——后面讲循环导入时还会回到这里。
2. 三种主流引路方式：环境变量、动态路径与可安装包
搞清楚搜索链路之后，真正的问题来了：我怎么让 Python 知道该去哪里找我的模块？现实中我见过的主流做法有三种，它们各有适用场景，也各有隐藏的副作用。
2.1 PYTHONPATH 环境变量：适合临时借路
PYTHONPATH是 Python 解释器在启动时会读取的环境变量，里面的目录会被追加到 sys.path 中，排在脚本目录之后、标准库之前。设置方式取决于你的操作系统：
# Linux / macOS，临时生效 export PYTHONPATH="/home/user/myproject:$PYTHONPATH" python main.py # Windows PowerShell，临时生效 $env:PYTHONPATH = "C:\Users\xxx\myproject;$env:PYTHONPATH" python main.py这种方式的好处是：不用改任何业务代码，项目里的所有模块立刻在全局可见。坏处也明显——它是“环境级别”的全局配置，换个环境就得重新设一遍。团队协作时，如果谁机器上没配这个变量，代码一跑就炸。我建议只把 PYTHONPATH 当作临时急救手段，或者用于明确约定的开发环境配置，不要把项目的可用性建立在这上面。
如果你需要长期、固定的路径配置，可以在site-packages目录里放一个.pth文件（比如myproject.pth），内容直接写一行项目绝对路径。Python 解释器启动时会自动读取并加入 sys.path。这算是个轻量偏方，但换机器依然要重复配置，治标不治本。
2.2 在代码里动态维护 sys.path：灵活但是把双刃剑
另一种流传很广的写法，是在入口文件的顶部手动把项目根目录塞进 sys.path：
import sys from pathlib import Path PROJECT_ROOT = Path(__file__).resolve().parent if str(PROJECT_ROOT) not in sys.path: sys.path.insert(0, str(PROJECT_ROOT))这样写的好处非常直观：不管你从哪个目录执行脚本，只要入口文件自己能定位到项目根目录，整个项目的包都能被找到。尤其适合一些快速验证的脚本、数据处理任务、机器学习实验代码。
但我不建议在正式的项目主代码里到处写这种东西。原因有三：第一，它把路径配置散落在代码里，项目一大就很难维护；第二，sys.path.insert(0)的写法会影响模块查找优先级，万一和别的库重名，可能出现“同名的不是你想用那个”的情况；第三，Path(__file__).resolve().parent只对真实文件有效，在某些交互式环境、打包环境里行为会变得很迷。这类代码适合放在入口脚本或者 conftest.py 里，做一次性的收尾，而不是在每个模块里各写一份。
2.3 pyproject.toml + pip install -e .：工程化的正解
如果你是想被团队长期使用的正经项目，最佳实践是把自己的项目做成一个“可安装的包”，用开发模式装进当前环境。这一步做完，项目本身就会出现在 site-packages 里，所有模块引用问题自然消散。
现代做法是在项目根目录放一个pyproject.toml，配合构建后端（最常见的是 setuptools）：
[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "myproject" version = "0.1.0" description = "示例项目" requires-python = ">=3.9" dependencies = [] [tool.setuptools.packages.find] include = ["myproject*"]然后在项目根目录执行：
pip install -e .-e代表 editable，也就是可编辑模式。它不会把代码复制到 site-packages，而是建立一个指向你项目目录的链接，改代码立刻生效，不用每次重新安装。这一步做完，你在项目里的任何脚本、甚至随便一个交互式终端里，都能直接import myproject.xxx。
这套方案之所以是“正解”，是因为它把“项目路径在哪”这件事交给了打包工具去管理，而不是靠每个人的环境变量、代码里的一段路径补丁去凑。团队里任何一个人 clone 下来，执行一遍pip install -e .，环境就完全一致了。
3. 包内引用：绝对导入、相对导入与init.py 的边界
sys.path 解决的是“模块在哪个目录”，包内引用解决的是“包内部的模块之间怎么互相引”。很多人从这里开始混乱，因为同样的代码，用不同的命令跑，结果完全不一样。
3.1 相对导入为什么总报错
假设你有这样一个目录结构：
myproject/ ├── main.py └── pkg/ ├── __init__.py ├── a.py └── b.pya.py里想引用b.py，大多数人会写：
# pkg/a.py from . import b这行代码叫相对导入，开头的点表示“相对于当前包”。它本身没有语法问题，但如果你直接执行：
python pkg/a.py就会得到著名的报错：
ImportError: attempted relative import beyond top-level package原因在于：当你把a.py当作“顶层脚本”运行时，Python 认为它的顶层包就是空包，a.py不再属于pkg的一部分，于是from . import b中的“当前包”根本不存在。换句话说，相对导入只有在“你的文件被当作某个包里的模块”时才有意义。
3.2 规则：要让脚本按“包的一部分”运行，请用 python -m
正确的做法是从项目根目录，让解释器把那个模块当作包成员来运行：
python -m pkg.a-m会先定位到pkg包，再进入pkg.a模块执行。此时__package__会被正确设置为pkg，相对导入就能正常工作。
这套规则我用一句话总结：入口脚本可以相对导入，但必须从项目根目录用python -m启动；直接python xxx.py时，这个文件永远没有包上下文。这也是为什么很多项目会在根目录放一个薄的入口文件（比如main.py），由它去调用包里的内容，而包内部模块之间一律使用相对导入，互不打扰。
顺着这个逻辑，还有一个容易忽略的细节——if __name__ == "__main__"判断。如果一个模块同时承担“可被 import”和“可作为入口运行”两种角色，你应该把运行代码放在这个判断块里，避免被别人 import 时直接触发执行逻辑。
3.3init.py 与all的正确用法
__init__.py在 Python 3 里已经不需要是空文件了，它充当包的初始化入口和对外“门面”。比如你可以在pkg/__init__.py里写：
from .a import AClass from .b import b_function __all__ = ["AClass", "b_function"]这样外部使用者可以写from pkg import AClass，而不需要知道 AClass 定义在哪个子模块。__all__则约束了from pkg import *时导出的名字，避免把一堆内部工具函数顺带暴露出去。我的习惯是：__all__始终显式写出，哪怕只有一两个名字，因为不写的话，import * 的行为会变得不可预测。
需要特别留意的是，__init__.py里的代码在包被导入时会立刻执行，所以不要在它里面放重量级初始化。如果你在里面写了一段联网请求或者读配置文件的代码，那整个项目的 import 速度都会被拖住。
4. ModuleNotFoundError 排查实录：四类高频场景
讲完原理，来看几个我实际遇到、也经常被同事问到的报错场景。这些场景覆盖面很广，代码本身没写错，错的是“运行方式”或者“项目结构”和配置不匹配。
4.1 场景一：同目录模块居然找不到
目录结构很简单：
project/ ├── run.py └── utils.pyrun.py里写import utils，然后你从项目根目录执行python run.py，一切正常。但如果你切到别的目录，用绝对路径执行：
python /path/to/project/run.py就会报ModuleNotFoundError: No module named 'utils'。
原因刚才已经说过：python 脚本路径会把脚本所在目录放入 sys.path[0]。注意，放入的是“脚本所在目录”，不是“当前工作目录”。如果你在别的目录下执行一个绝对路径脚本，脚本所在目录依然是/path/to/project，按理说也能找到utils.py，真正会出问题的是另一种变体——脚本内部再通过相对路径拼接去“读取”其他文件，或者你在项目里用到了cwd相关逻辑。
这个场景最隐蔽的点在于：很多人以为“报错是因为当前目录不对”，于是去cd到项目根目录，却发现错误依旧。这时候要看清楚报错的是哪个模块，它是 import 报错，还是open()打开文件报错。前者看 sys.path，后者看当前工作目录，两者经常被混为一谈。我的排查口诀是：import 找不到看 sys.path，文件读取不到看 os.getcwd()。
4.2 场景二：IDE 里正常，命令行一跑就挂
这是被问得最多的一类问题。PyCharm、VS Code 里点运行一切正常，换到系统终端执行同样的命令就报模块缺失。
原因在于 IDE 默认会把项目根目录加入 PYTHONPATH，同时把运行时的“当前工作目录”设置为项目根目录。这是 IDE 帮你做了一层隐形的路径配置。到了终端里，这两项全没了，自然露馅。
解决办法分两个层次。如果是临时跑一下，就按上面的PYTHONPATH配一下，或者用python -m指定包路径启动。如果是长期项目，我推荐直接走“可安装包”路线——pip install -e .之后，IDE、终端、CI 里的运行行为就完全一致了，不再依赖任何一方的特殊配置。
4.3 场景三：循环导入导致“模块还在初始化”就被人借用
循环导入是最隐蔽的一类问题，报错信息往往让你摸不着头脑：
AttributeError: partially initialized module 'a' has no attribute 'func' (most likely due to a circular import)它和 sys.path 没关系，而是模块缓存的锅。假设a.py第 3 行import b，而b.py第 3 行又import a。执行a.py时，Python 先把 a 标记为“正在初始化”，然后执行到import b；b 里又回来 import a，此时 a 在 sys.modules 里已经存在，但还是个“半成品”，还没执行到定义func的那一行，于是访问a.func直接报错。
我处理循环导入的固定套路是三步：第一步，把 import 语句从模块顶层挪到函数内部，推迟到真正调用的那一刻再导；第二步，重构数据结构，把两个模块共同依赖的部分抽到第三个模块里；第三步，实在要保留现状，就在if __name__ == "__main__"块里引导启动顺序。优先推荐第二步，因为前两步本质上是拖延，只有解耦才能真正根治。
4.4 场景四：包名与标准库、第三方库撞名
另一个我踩过的坑：项目里有个email/目录或者json.py文件，看起来很正常，但代码运行后行为诡异，甚至直接报错。因为email、json、time这些都是 Python 标准库的名字，sys.path 的搜索顺序是项目目录在前、标准库在后，所以你的本地文件会“遮蔽”标准库。这会导致两个后果：你 import 了错误的东西，或者标准库内部依赖同名模块时被你的文件劫持，引发一堆莫名其妙的异常。
排查方式也简单，用一行代码看模块真实来源：
import json print(json.__file__)如果输出指向你的项目目录，而不是标准库路径，说明发生了遮蔽。解决办法是给项目包加一层顶层命名空间，比如把所有业务代码放进myproject/目录，而不是散落在根目录下。这既是避免撞名的稳妥方案，也方便后续打包成可安装包。
5. 工程化收尾：一套可以直接复制的引用配置方案
原理和避坑讲完了，最后分享一套我在多个项目里反复调整后固定下来的目录结构。它不是唯一正解，但可以保证：克隆到任何机器，按文档两条命令就能跑；IDE、命令行行为一致；后续加模块、加脚本都不需要再动路径配置。
5.1 一份不会出错的目录结构
myproject/ ├── pyproject.toml ├── README.md ├── main.py ├── myproject/ │ ├── __init__.py │ ├── config.py │ ├── models/ │ │ ├── __init__.py │ │ └── user.py │ └── services/ │ ├── __init__.py │ └── auth.py └── tests/ ├── __init__.py └── test_user.py规则只有三条。第一，业务代码全部放在内部myproject/包目录下，外层目录只留入口脚本和配置文件；第二，包内模块之间一律使用相对导入，从包外访问一律使用绝对导入（from myproject.services import auth）；第三，入口脚本main.py只做两件事——初始化环境和调用myproject包里的真正入口函数。
这套结构下，包的引用路径始终是从项目根目录到内部包的完整路径，不会出现跨层乱找的问题。
5.2 在 pyproject.toml 里把依赖和入口写明白
配合上面的结构，pyproject.toml 还可以声明命令行入口：
[project] name = "myproject" version = "0.1.0" requires-python = ">=3.9" [project.scripts] myproject = "myproject.main:run" [tool.setuptools.packages.find] include = ["myproject*"]配好之后执行pip install -e .，你甚至可以直接在终端输入myproject命令启动项目。新成员加入时，只需要两步：
cd myproject pip install -e .不需要任何环境变量的记忆，不需要任何 IDE 的特殊设置。这份配置会成为项目的“单一事实来源”，所有路径、依赖、入口都记录在里面。
5.3 我踩过坑之后的几个固定习惯
最后讲几个我自己养成的习惯，每次新项目都照做，基本告别了 import 类问题。
第一，新建项目第一时间就把pyproject.toml和内部包目录建好，哪怕只有一个文件也把这个架子搭起来。别等项目写大了再重构，那时文件之间的引用关系已经纠缠不清，重构成本高很多。
第二，所有脚本都用python -m myproject.xxx的方式启动，而不是python xxx.py。强制自己从入口角度思考运行方式，就不会写出“只能在该文件目录下运行”的脆弱代码。
第三，__init__.py只在需要控制包对外接口时才写内容，其余情况保持空文件或者只写__all__。它虽然可以有逻辑，但每一次执行都是有开销的。
第四，遇到报错先看是“找不到模块”还是“模块内部报错”。前者是路径问题，后者是代码问题，处理方式完全不同。仅凭报错截图里的红色字体去盲改，是最浪费时间的行为。
Python 的模块和包引用配置，本质上就是一套“解释器去哪里找文件、以什么身份运行文件”的规则。规则不算多，但每条都贯穿项目结构和运行方式。把这套逻辑理顺之后，你会发现大多数 import 报错都不是玄学，而是有固定答案的常规问题。
