VS Code无法识别工作区自定义Python模块的路径配置问题

你之前尝试的PYTHONPATH配置方向是正确的，未生效是因为配置没有覆盖所有Python运行场景，或是写法、存放位置有误，以下是可直接落地的方案，按推荐优先级排序：

方案1：可编辑模式安装本地包（通用最优解，不依赖编辑器配置） #

这是Python包开发的标准实践，配置一次后，无论用什么编辑器、在哪个目录运行脚本/测试，都能正常导入mymodule，完全不需要手动修改路径：

• 在工作区根目录（与mymodule、tests文件夹同级）创建pyproject.toml文件，写入最小配置：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mymodule"
version = "0.0.1"
packages = ["mymodule"]

• 激活你当前使用的Python环境（VS Code右下角选择的对应解释器环境），在终端执行命令：

pip install -e .

执行完成后，当前环境会以软链接形式关联工作区的mymodule源码，所有场景下import mymodule都能正常加载，后续修改源码也不需要重新安装。

方案2：全场景VS Code配置（不修改环境包，仅对当前工作区生效） #

如果不想做包安装，可通过以下配置覆盖调试运行、右键运行、终端执行、单元测试所有场景，自动把工作区根目录加入搜索路径：

2.1 配置.env文件（覆盖终端运行、测试场景） #

你之前的.env配置未生效，大概率是文件位置不对或变量写法有误：

• 把.env文件直接放在工作区根目录，不要放到子文件夹
• 文件内不需要写绝对路径，直接写入：

PYTHONPATH=${workspaceFolder}

VS Code的Python扩展会自动解析${workspaceFolder}变量，自动替换为当前工作区的绝对路径，工作区迁移位置后不需要修改配置。

• 打开VS Code设置，搜索python.envFile，确认配置值为${workspaceFolder}/.env（该选项为默认值，未手动修改过无需调整）。

2.2 修正launch.json配置（覆盖F5调试、运行场景） #

之前的launch.json配置缺少工作目录指定，完整配置如下（文件存放在根目录.vscode文件夹下）：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 运行当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}

配置中添加的"cwd": "${workspaceFolder}"会固定调试时的工作目录为根目录，避免子目录运行时的路径解析错误。

2.3 测试框架额外配置（解决pytest/unittest导入报错） #

如果运行测试用例时仍报模块找不到的错误，按你使用的测试框架补配置：

• 若使用pytest：在工作区根目录创建pytest.ini，写入：

[pytest]
pythonpath = .

• 若使用unittest：打开VS Code设置，搜索python.testing.unittestArgs，添加参数--rootdir=${workspaceFolder}即可。

之前配置失效的常见原因 #

• 仅配置launch.json的环境变量：该配置只对F5启动的调试进程生效，右键运行、手动在终端执行脚本、跑测试时不会加载该配置，因此会报错。
• .env文件存放在子目录、写死的绝对路径与实际工作区路径不匹配、或手动修改过python.envFile配置指向其他位置，都会导致Python扩展无法加载对应的PYTHONPATH配置。

内容的提问来源于stack exchange，提问作者moro11