VSCode无法找到自定义Python模块：ModuleNotFoundError（macOS环境）

AI 小北

2026-7-4

解决macOS下VSCode中Python模块导入问题

问题根源

你用命令行python -m scripts.install_third_party能正常运行，是因为-m参数会自动把当前工作目录（也就是oppia根目录）加入Python的模块搜索路径sys.path；但VSCode默认运行脚本时，没把oppia目录加到sys.path里，所以找不到core和scripts模块。复制文件夹的方法只会顾此失彼，不是根本解决方案。

具体解决方法

方法1：配置VSCode运行调试环境（推荐）

打开VSCode的「运行和调试」面板（快捷键Cmd+Shift+D），点击「创建launch.json文件」，选择「Python」环境。

在生成的launch.json中，替换成以下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "运行install_third_party",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/scripts/install_third_party.py",
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            },
            "console": "integratedTerminal"
        }
    ]
}

之后通过这个配置运行脚本，就能正常导入模块了。

方法2：在代码中临时添加路径（应急用）

在install_third_party.py的最开头添加以下代码：

import sys
from pathlib import Path
# 把项目根目录（oppia）加入模块搜索路径
sys.path.append(str(Path(__file__).parent.parent))

这种方法不用改VSCode配置，但属于硬编码路径，适合临时测试，不推荐长期使用。

方法3：全局配置VSCode的Python环境变量

打开VSCode设置（快捷键Cmd+,），搜索「Python: Env File」，设置一个.env文件路径（比如oppia根目录下的.env）。
在该.env文件中添加：
```
PYTHONPATH=${PWD}
```
或者直接在VSCode的settings.json中添加：
```
"python.env": {
    "PYTHONPATH": "${workspaceFolder}"
}
```
这样所有在VSCode中运行的Python脚本都会自动把oppia根目录加到搜索路径里。