vscode默认不将项目文件夹视为源码根目录，导致import失败、补全失效、类型检查报错；根本原因是pylance仅扫描工作区根目录和site-packages，需通过python.analysis.extrapaths显式声明模块路径。
VSCode 默认不把项目文件夹当作 Python 的“源码根目录”，所以 import 会失败、补全不生效、类型检查报错——这不是你代码写错了，是 VSCode 没认出你项目的结构边界。
为什么 import 报 ModuleNotFoundError？
Python 解释器本身不关心“项目根目录”，它只看 sys.path；而 VSCode 的 Pylance（或旧版 Python 插件）默认只扫描工作区根目录和虚拟环境 site-packages，不会自动把子目录（比如 src/）加进模块搜索路径。
- 你在
src/main.py里写from mypkg.utils import helper，但mypkg在src/mypkg/下——Pylance 不知道该去src/里找 - 即使终端里手动
cd src && python main.py能跑通，VSCode 调试或补全仍可能失效，因为两者路径来源不同 -
settings.json里配python.defaultInterpreterPath只影响解释器，不影响模块解析路径
python.analysis.extraPaths 是最直接的解法
这是 Pylance 官方推荐的方式，告诉语言服务器：“这些路径也要当成本地模块源来索引”。它不改运行时行为，只解决编辑时的识别问题（补全、跳转、类型提示、ModuleNotFoundError 红波浪线）。
- 打开 VSCode 设置（
Ctrl+,），搜python.analysis.extraPaths，点击“在 settings.json 中编辑” - 添加相对路径，例如项目结构是
./src，就写："python.analysis.extraPaths": ["./src"] - 支持多个路径：
["./src", "./lib", "./tests"]，路径相对于工作区根目录（即你用 VSCode 打开的那个文件夹） - 改完保存，VSCode 右下角会提示“重新加载窗口”，点它；或者等几秒，Pylance 自动重启索引
调试时 cwd 配置必须同步
编辑时能识别模块，不代表运行时就能导入成功。如果脚本里还用了 open("data/config.json") 这类相对路径读文件，cwd（当前工作目录）不对照样报 FileNotFoundError。
- 确保
.vscode/launch.json里每个配置都有"cwd": "${workspaceFolder}"或更精确的值，比如"${workspaceFolder}/src" - 不要依赖“打开文件夹即默认 cwd”——某些插件或终端启动方式会覆盖它
- 验证方法：在 Python 文件里加一行
import os; print(os.getcwd())，运行后看输出是否符合预期
别碰 PYTHONPATH 环境变量配置
网上很多教程让你在 settings.json 里配 terminal.integrated.env.* 加 PYTHONPATH，这容易引发冲突：
- 它只影响集成终端，不影响调试器和 Pylance
- 如果同时设了
extraPaths和PYTHONPATH，可能导致重复索引或路径优先级混乱 - Windows/macOS/Linux 的环境变量 key 名不同（
env.windows/env.osx），漏配一个就失效 - 真正需要的是编辑时识别 + 运行时路径一致，而不是靠环境变量“打补丁”
复杂项目里，src/ 目录层级深、有多个包并存、还要对接测试工具链——这时候光靠单个配置撑不住，得靠 pyproject.toml 里的 [tool.setuptools.packages] 或 [tool.flit.sdist-include] 声明结构，再配合 VSCode 的 extraPaths 和 launch.json 协同工作。路径不是越配越多就越稳，而是每条路径都得有明确职责。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
