科普：python中你写的模块找不到了——`ModuleNotFoundError`

python中你写的模块找不到了------ModuleNotFoundError，这是新手常见的问题，如何破？？？

---

一、Python 路径 & 模块导入

只要记住下面 5 条铁律 ，就不会报 ModuleNotFoundError

1. 工作目录 = 你在哪个文件夹运行命令

假设有文件结构：

C:\aaa\
    ├── bbb\
    │   └── ccc.py   <-- 你的程序在这里
    └── ddd\
        └── eee.py

• 在 C:\aaa> 运行 python bbb/ccc.py
  → 工作目录 = C:\aaa
• 在 C:\aaa\bbb> 运行 python ccc.py
  → 工作目录 = C:\aaa\bbb

所有相对路径（图片、SVG、文件）都从工作目录开始找

2. __file__ = 当前 .py 文件自己的绝对路径

这是最可靠 的定位方式，不受工作目录影响

3. .. 表示上一级，../.. 表示上两级

• os.path.dirname(__file__) → 当前文件所在文件夹（上述结构中：你的程序在这里）
• .. → 往上走一级
• ../.. → 往上走两级

4. sys.path = Python 找模块的搜索列表

你加什么路径，Python 就能找到什么路径下的模块

5. 最安全的导入写法（万能）

import sys, os
#若我们要引用的模块的最外层目录在当前文件目录的上二级目录，则：
sys.path.append(os.path.join(os.path.dirname(__file__), "../.."))

通常把项目的根目录加入搜索路径

从此无论在哪儿运行（不管工作目录），都能找到项目的模块

---

二、拆解上述路径函数

把上述的一行代码拆解成 3 个函数，方便你理解：

sys.path.append(
    os.path.join(
        os.path.dirname(__file__), 
        "../.."
    )
)

---

1. __file__（不是函数，是内置变量）

功能：获取当前 .py 文件自己的完整路径

• 它是 Python 内置的
• 永远指向当前代码所在文件

例子：

如果你在运行：

C:\manim_projects\scenes\china_map\china_map.py

那么

__file__ = "C:\manim_projects\scenes\china_map\china_map.py"

---

2. os.path.dirname(路径)

功能：从一个完整路径中，取出【所在文件夹路径】

去掉文件名，只留文件夹。

例子：

os.path.dirname("C:/a/b/c.py")

结果：

"C:/a/b"

---

3. os.path.join(路径1, 路径2)

功能：把两段路径拼在一起，自动加斜杠 \ 或 /

它会自动适配 Windows / Linux。

例子：

os.path.join("C:/aaa", "bbb")
→ "C:/aaa/bbb"

---

4. 额外：sys.path.append(路径)

功能：把一个路径加入 Python 的模块搜索目录

从这个函数的名字就可以看出来它是干什么的。路径加进去之后，Python 就能找到这个目录下的所有模块。

---

记住：

1. __file__ = 我自己在哪
2. os.path.dirname() = 我在哪个文件夹
3. os.path.join() = 把路径拼对
4. sys.path.append() = 把路径加到Python的搜索链中，让它能找到模块

sys.path.append(
    os.path.join(
        os.path.dirname(__file__),   # 1. 拿到当前文件所在文件夹
        "../.."                      # 2. 往上走两级，通常你要修改为走到项目的根目录
    )
)

上述可写为：

sys.path.append(os.path.join(os.path.dirname(__file__), os.pardir, os.pardir))

• . = os.curdir (Current Directory)
• .. = os.pardir (Parent Directory)

三、除了上述方法外，还可以设置环境变量 PYTHONPATH

---

假定项目的根为：C:\manim_projects

Windows 终端运行：

set PYTHONPATH=C:\manim_projects

或永久加到系统环境变量

Python 会自动搜索这个路径

---