Cursor ：Python 运行路径设置自定义模块导入报错：No module named ‘xxx’ 的解决方案

引言

在使用 PyCharm 与 VSCode/Cursor 进行 Python 开发时，你可能会遇到一个细节上的差异：

• PyCharm 中，os.getcwd() 默认指向 当前脚本所在目录。
• VSCode/Cursor 中，os.getcwd() 默认指向 当前工作区（项目目录）。

这个差异往往会导致一个常见的问题：
在 VSCode/Cursor 中运行 Python 脚本时，出现 自定义模块无法导入 的报错：

ModuleNotFoundError: No module named 'xxx'

原因是 VSCode/Cursor 依赖 终端运行 Python，并不会像 PyCharm 一样自动搜索项目中的自定义包路径。

一、问题复现

假设项目结构如下：

project/
│── utils/
│    └── helper.py
│── main.py

在 main.py 中我们写了：

from utils.helper import my_func

在 PyCharm 中运行一切正常，但在 VSCode/Cursor 中运行时，终端会报错：

ModuleNotFoundError: No module named 'utils'

二、问题根源

Python 解释器在运行时，会根据 sys.path 中的目录查找模块。
默认情况下，VSCode/Cursor 的运行目录是 工作区根目录，并不会自动把 project/ 路径加到 PYTHONPATH。

这就是为什么在 VSCode/Cursor 中经常会遇到模块找不到的问题。

---

三、解决方案（一次配置，永久生效）

核心思路：解决方法就是让 VSCode 运行 Python 时自动将工作区目录加入 PYTHONPATH，无需每次手动配置。

配置步骤

1. 打开 Cursor
2. 依次点击菜单栏：文件 -> 首选项 -> 设置
   3.在设置搜索框中输入 settings.json，选择「在 settings.json 中编辑」；
3. 在配置文件中添加以下代码（若已有其他配置，需确保 JSON 格式正确）：

{
"terminal.integrated.env.windows": {"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"},"python.terminal.executeInFileDir": false
}

一般是在 C:\Users\用户名\AppData\Roaming\Cursor\User 里面
4. 保存文件，配置立即生效。

参数解释

• ${workspaceFolder}：Cursor 当前工作区根目录（如上述 project/），将其加入 PYTHONPATH 后，解释器可识别根目录下的所有子模块；
• ${env:PYTHONPATH}：继承系统环境变量中的 路径PYTHONPATH，避免覆盖系统已配置的 Python 依赖路径；
• python.terminal.executeInFileDir": false：固定终端运行目录为工作区根目录，确保 PYTHONPATH 配置的一致性，避免因脚本所在目录不同导致路径混乱。

这样配置后，每次在 VSCode/Cursor 的终端运行 Python 脚本时，都会自动将当前项目路径加入 PYTHONPATH。

---

四、结果验证

完成配置并重启终端后，再次运行你的 main.py。现在，模块导入错误应该已经消失了。你可以再次运行之前那个打印 sys.path 的验证脚本，会发现 ${workspaceFolder} 已经被添加到了模块搜索路径列表中。

五、总结

• 问题根源：Cursor/VSCode在终端中运行Python脚本，其默认的模块搜索路径处理与PyCharm不同，不会自动将项目根目录加入 sys.path。
• 解决方案：通过修改编辑器的 settings.json 文件，将 ${workspaceFolder} (项目根目录) 永久添加到集成终端的 PYTHONPATH 环境变量中。
• 方案优势：
  • 一劳永逸：一次配置，对当前项目所有Python文件均有效。
  • 非侵入性：无需在代码中修改 sys.path，保持了代码的整洁和可移植性。
  • 环境隔离：该配置通常作用于工作区级别，不会影响系统其他项目。

通过这个简单的配置，你可以在享受Cursor/VSCode带来的轻快与高效的同时，彻底告别 ModuleNotFoundError 的烦恼，获得无缝的模块导入体验。