在 VSCode 里写 Python“ModuleNotFoundError: No module named xxx” 这行报错出现的频率大概仅次于拼错变量名。更让人抓狂的是它有强烈的场景依赖性终端里python main.py跑得顺顺当当切回编辑器按 F5 就炸昨天还好好的今天把文件挪了个位置就全红本地 Mac 上一切正常推到服务器上 CI 直接挂。绝大多数人第一反应是sys.path.append一把梭或者把PYTHONPATH环境变量堆得老长结果项目越写越乱坑越填越多。这篇东西不讲“怎么用 VSCode 装 Python 插件”那种入门内容而是把 VSCode 里的 Python 模块导入问题从头拆一遍sys.path到底怎么拼出来的、解释器和工作目录是怎么错位的、相对导入为什么一碰就炸、Pylance 的红线跟运行时报错为什么是两码事最后一劳永逸的项目布局和可编辑安装怎么落地。适合已经能写点脚本、但在工程化这一步被导入问题反复折磨的人。1. sys.path 是唯一真相Python 到底在哪些目录里翻模块1.1 解释器启动那一瞬间搜索路径就已经定死了先立一个基本认知Python 找模块只认sys.path这个列表跟“我用 VSCode 打开了哪个文件夹”没有任何关系。很多从 PyCharm 转过来的人会有一个根深蒂固的幻觉——IDE 打开的项目根目录Python 就应该知道。实际情况是编辑器只是一个文本编辑器加一堆插件它不会把“打开的文件夹”这个信息灌输给 Python 解释器。sys.path的顺序是固定的从前往后依次是sys.path[0]这个位置的值随启动方式变化后面会专门讲PYTHONPATH环境变量里的每一项按书写顺序插入标准库目录由sys.prefix和sys.base_prefix推算出来通常是lib/python3.x和lib/python3.x/lib-dynloadsite-packages由site模块在启动时扫描添加同时也包括site-packages下所有.pth文件里列出的目录。这个顺序意味着一个重要结论PYTHONPATH里的路径优先级高于标准库和第三方包。这既是好事也是坏事——好处是你可以临时覆盖某个模块坏处是你放了一个叫json.py的文件在PYTHONPATH目录里标准库的 json 就被你干掉了而且是静默干掉报错信息通常在十万八千里外。还有个容易被忽略的点sys.path在解释器启动完成后仍然是可变的sys.path.append确实能生效。但这套做法治标不治本因为它依赖“代码在 append 之前就已经被执行到”这个前提一旦模块层级复杂起来哪个文件先被执行、append 有没有生效就成了玄学。真正稳的方案是让包本身可被安装而不是靠运行时往路径列表里塞东西。1.2 三种启动方式对应三套完全不同的 sys.path[0]这是所有“终端能跑、VSCode 不能跑”问题的总根源值得单独拎出来说清楚。sys.path[0]有三种取值规则启动方式sys.path[0] 的取值典型命令直接跑脚本文件脚本所在目录的绝对路径python src/app/main.py用-m跑模块当前工作目录python -m src.app.main交互式解释器 /-c空字符串等价于当前工作目录python或python -c import x注意第一行和第二行的差别直接跑脚本时进入搜索路径的是脚本文件所在的那个目录不是你在哪个目录下敲的命令而用-m时进入搜索路径的是你敲命令时所在的工作目录。这两个东西在简单项目里经常是同一个所以你看不出区别等到项目有了src/分层、脚本挪到子目录里差别立刻就暴露了。举个具体例子。项目结构是这样的myproj/ ├── src/ │ └── app/ │ ├── __init__.py │ ├── main.py │ └── utils.py你在myproj/目录下敲python src/app/main.py此时sys.path[0]是/path/to/myproj/src/appmain.py里写import utils能成但from src.app import utils一定失败因为/path/to/myproj压根不在搜索路径里。反过来如果你在myproj/下敲python -m src.app.mainsys.path[0]是/path/to/myproj这时候from src.app import utils能成而import utils会失败。同一个文件两行 import两种命令下互斥地成功。很多人被这个现象绕进去以为自己 import 写错了其实是启动方式变了。1.3 把真相打印出来比猜一百次都管用遇到导入问题第一件事永远是打印现场而不是凭感觉猜。把下面这段贴成项目根目录下的_debug_path.py分别在 VSCode 集成终端、调试器控制台、Notebook 单元格里各跑一次import os import sys print(cwd :, os.getcwd()) print(executable:, sys.executable) print(prefix :, sys.prefix) print(version :, sys.version) print(- * 60) for i, p in enumerate(sys.path): print(f[{i}] {p!r})三个关键信息一次全拿到sys.executable告诉你当前到底是哪个解释器在跑。VSCode 状态栏显示的解释器和真正执行的不是同一个这是最常见的错位os.getcwd()告诉你工作目录所有相对路径读取和-m启动的路径解析都依赖它sys.path的完整列表直接看出目标包在不在里面。提示如果sys.executable指向的是/usr/bin/python3这类系统解释器而你明明在项目里建了 venv那问题已经找到了——不是导入写错是环境没切对。我自己的习惯是在项目里放一个python -m site的输出也存一份因为site模块会告诉你site-packages的准确位置和所有.pth文件生效情况。python -m site的输出在排查“包明明装了却 import 不到”这类问题时几乎是决定性的——它能把用户级site-packages~/.local/lib/python3.x/site-packages和虚拟环境的site-packages一起列出来你就知道 pip 到底把包装哪儿去了。2. 终端能跑、VSCode 一跑就崩三种错位的完整定位方法2.1 解释器错位状态栏那个 Python 不是你终端里的 PythonVSCode 左下角状态栏会显示当前选中的 Python 解释器这个选择影响三件事调试器用哪个解释器启动、集成终端打开时自动激活哪个虚拟环境、Pylance 用哪个环境的site-packages做静态分析。三者理论上应该一致但实际项目里经常不一致。最典型的场景你在终端里手动source .venv/bin/activate然后在终端里pip install requests装进了.venv。但 VSCode 状态栏选的还是系统 Python。于是终端里python main.py能找到 requestsF5 一跑就No module named requests——因为调试器用的是系统 Python那个环境里根本没装。反向的情况也存在状态栏选对了 venv但你在终端里从没激活过直接敲python用的是系统解释器于是“终端能跑”这个前提本身就不成立了。所以排查的第一步永远是把两边的sys.executable打印出来对比而不是看着“终端能跑”就认定环境没问题。顺带说一个 VSCode 的坑多根工作区multi-root workspace里每个文件夹有独立的解释器设置。你可能在文件夹 A 里选好了 venv切到文件夹 B 那个终端去跑用的是另一个解释器。这种情况sys.executable一打就现原形。2.2 工作目录错位cwd 决定了相对路径和 -m 的一切VSCode 调试器默认的cwd是${workspaceFolder}也就是你打开的顶层文件夹。而你在终端里的工作目录可能是任意位置——cd src之后再执行命令是家常便饭。这两者不一致时会出现两类问题第一类是显式的相对路径读取比如open(config/settings.json)。终端里你在项目根目录跑能找到F5 时如果cwd设成了子目录就找不到。这类问题报错信息很直白FileNotFoundError好定位。第二类更阴是-m启动时的sys.path[0]。前面说过-m会把当前工作目录塞进搜索路径。如果调试配置里cwd被设成了${workspaceFolder}/src那sys.path[0]就变成了src你在终端里能跑通的python -m app.main在调试器里就变成了找不到app包——因为app在src下面而这个组合在终端里需要cd src才对。所以修launch.json的时候cwd这个字段不要随手写要么明确写${workspaceFolder}要么就按你终端里的实际操作目录来。写完之后用sys.path打印验证一遍比读文档快得多。2.3 启动方式错位F5 跑文件终端跑模块VSCode 默认生成的调试配置是program: ${file}也就是直接跑当前打开的文件。而你在终端里可能是用-m跑的。这两者的sys.path[0]完全不同前面已经分析过。这种情况下正确做法不是去改代码里的 import而是让调试配置跟你终端的启动方式对齐。有两种写法{ version: 0.2.0, configurations: [ { name: Python: 按模块启动, type: debugpy, request: launch, module: myproj.cli, cwd: ${workspaceFolder}, console: integratedTerminal, justMyCode: false }, { name: Python: 按文件启动, type: debugpy, request: launch, program: ${workspaceFolder}/scripts/run.py, cwd: ${workspaceFolder}, console: integratedTerminal } ] }注意type字段新版 Python 扩展用debugpy老版本用python两者目前都还能用但python在被逐步淘汰新写的配置建议直接用debugpy。还有一个细节是console默认的internalConsole不会加载终端的环境变量和 shell 配置遇到导入问题时建议改成integratedTerminal让调试进程和终端环境尽量一致减少变量。2.4 一张表把三类错位对号入座现象最可能的根因快速验证手段报错集中在第三方包解释器选错venv 与调试器不一致对比终端和调试器里的sys.executable报错集中在自己的子包启动方式不同导致sys.path[0]变化打印sys.path看项目根目录在不在报错集中在读文件cwd与预期不符打印os.getcwd()只在调试时崩、终端正常launch.json的cwd/env与终端环境不一致把console改成integratedTerminal再跑这张表不是穷举但它覆盖了我遇到过的八成情况。剩下的两成基本都落在相对导入和 Pylance 静态分析这两个话题上。3. 相对导入为什么一碰就炸main与包上下文的关系3.1 attempted relative import with no known parent package 的成因这个报错信息很长但拆开看就一句话解释器不知道你当前这个模块属于哪个包所以无法把from . import x里的那个点解析成任何东西。相对导入的解析依赖模块的__package__属性。当你用python pkg/sub/module.py直接跑一个包内部的文件时这个文件的__name__被设成__main____package__是空字符串或None。解释器失去了“它属于 pkg.sub”这个信息.这个点就没有参照物了。对比之下python -m pkg.sub.module启动时pkg和pkg.sub会被依次导入module的__name__是__main__但__package__被正确地设成pkg.sub相对导入就能解析。这就是为什么同一个文件用-m跑没事直接跑就炸。很多人被这个现象误导以为“相对导入只能在包被 import 的时候用”于是把包内部所有文件都改成绝对导入用起来确实不报错了但项目一旦重命名顶层包全项目搜索替换一遍痛苦加倍。相对导入是有价值的问题不在它本身而在入口文件的放法。3.2 正确姿势把入口抬到包的外面根治方案只有一个包内部的文件永远不要作为入口直接执行。入口要么放在包外面要么通过console_scripts注册成命令。推荐的结构是这样myproj/ ├── pyproject.toml ├── README.md ├── src/ │ └── myproj/ │ ├── __init__.py │ ├── cli.py # 真正的入口逻辑用相对导入 │ ├── core.py │ └── io/ │ ├── __init__.py │ └── loader.py └── tests/ ├── conftest.py └── test_core.py包内部的cli.py里可以放心写from .core import run、from .io.loader import load因为它是作为myproj.cli被导入的永远有正确的__package__。而启动方式有两种# 方式一以模块方式启动 python -m myproj.cli # 方式二安装后在任意位置用命令启动推荐 pip install -e . myproj方式二需要在pyproject.toml里声明[project.scripts] myproj myproj.cli:main这样main函数就是唯一入口包内部所有模块的相对导入永远是安全的。这个设计不是 VSCode 特有的任何 Python 工程都应该这么做只是 VSCode 的调试器把问题放大得更明显。3.3init.py 到底还要不要写Python 3.3 引入了 PEP 420 的隐式命名空间包理论上__init__.py可以省略。但我的建议是在应用型项目里老老实实写__init__.py原因有三条。第一工具链兼容性。很多静态分析工具、打包工具、pytest的收集逻辑在有__init__.py时行为更可预测。你省掉它得到的通常是诡异的“有些目录算包、有些不算”的不一致行为。第二显式优于隐式。__init__.py存在本身就是一个信号这个目录是包的一部分不是随手放的杂物目录。第三可以放包级别的初始化逻辑比如__version__、日志配置、公共异常定义。当然__init__.py里不要塞重逻辑import 这个包就触发一堆副作用是另一个大坑容易造成循环导入。循环导入这个话题可以顺带提一句它和相对导入是两回事但报错经常混在一起。判断方法很简单把报错栈的调用链从上到下列出来看看是不是 A import B、B import C、C 又 import A。遇到这种情况解法是把公共依赖抽到更底层的模块或者把 import 挪到函数内部延迟执行。4. Pylance 的红线它和 Python 运行时不共用同一个大脑4.1 红线不等于报错报错也不一定有红线Pylance 是 VSCode 里的语言服务器它做的是静态分析——不执行代码只看源码推断类型和解析导入。它的路径解析规则和运行时的sys.path是两套独立机制。Pylance 主要参考当前选中解释器的site-packages、python.analysis.extraPaths配置项、python.analysis.stubPath、以及pyrightconfig.json。这导致两种非常容易让人误判的情况情况一有红线但能跑。Pylance 没找到某个包可能装在另一个环境里画了红波浪线但你运行时用的是正确环境代码完全没问题。这时候如果你去改代码就是被工具牵着走。情况二没红线但跑起来报错。Pylance 通过extraPaths找到了包的源码不画红线但运行时sys.path里没有这个路径直接异常。判断方法很直接红线只是线索真正的判据是运行时能不能 import 成功。先跑代码再决定要不要动 Pylance 的配置。4.2 extraPaths 的正确用法与滥用风险python.analysis.extraPaths是settings.json里的数组用来告诉 Pylance “这些目录也要参与模块解析”{ python.analysis.extraPaths: [ ${workspaceFolder}/src ] }在srclayout 的项目里为了让 Pylance 能解析import myproj而不需要真的安装包加这一行是合理且常见的。但要注意它只影响静态分析不影响运行时。所以加了之后如果红线消失了你还要再确认运行时也能跑通否则就是自欺欺人。滥用的情况是把一堆目录全塞进去{ python.analysis.extraPaths: [ ./src, ./src/myproj, ./src/myproj/io, ./lib, ./scripts, ./tests ] }这种做法在短期内能让红线全消但代价是静态分析失去了对包边界的判断能力本来该报出来的“模块不在包里”的问题被掩盖了。而且一旦目录一多Pylance 的解析会变慢大项目里能明显感觉到卡顿。我的原则是extraPaths只放src这一层不放更深让工具的分辨率保持在“能看见顶层包”这个粒度上。4.3 什么时候该考虑 pyrightconfig.json工作区级别的settings.json有个局限它是编辑器配置跟项目本身绑得不够紧换个人来 clone 项目就得重新配一遍。如果你希望这些解析规则跟着代码走可以放一个pyrightconfig.json到项目根目录{ include: [src, tests], extraPaths: [src], venvPath: ., venv: .venv, reportMissingImports: warning }这样即使同事用别的编辑器只要支持 Pyright 协议或者 CI 里跑静态检查都能复用同一份配置。这是把“编辑器个人偏好”变成“项目约定”的一步。4.4 别用 diagnosticSeverityOverrides 掩盖真问题有一种常见操作是把导入错误降级成警告眼不见心不烦{ python.analysis.diagnosticSeverityOverrides: { reportMissingImports: none } }我理解这个诉求但强烈建议只在临时排查时用不要长期留在配置里。原因很简单这个开关一开Pylance 就不再告诉你“这个包找不到”了而“包找不到”恰恰是最需要提前发现的问题之一——它能提前暴露轮子没写进依赖清单、包名拼错、环境不一致这些会在部署时爆炸的隐患。用一个配置项把警报关掉等于把问题推迟到更贵的时刻。5. 从根上解决项目布局与可编辑安装5.1 src layout 和 flat layout 的实际差别包目录直接放在项目根目录下flat layout和放在src/下面src layout在导入行为上有实实在在的区别。flat layout 的典型样子是根目录下就是myproj/和tests/此时项目根目录本身会被pytest之类的工具加进sys.path于是import myproj能成——但注意你 import 的是源码目录本身而不是安装后的包。这个差别在本地写代码时感受不到但会掩盖几个问题打包时忘写packages配置、包名和目录名的映射关系不清、tests目录可能被误当成包。一旦发布到别处用这些隐藏问题就全冒出来了。src layout 的核心作用就是强制你以安装后的形态来导入包。在src布局下根目录里没有可导入的包目录import myproj唯有在包被正确安装或路径被正确配置之后才能成功。这个约束看起来是麻烦实际是免费的保险——它在开发阶段就把“能不能装”这个问题提前暴露了。5.2 pyproject.toml 一份够用的最小配置以 setuptools 为例pyproject.toml里需要的最小内容如下[build-system] requires [setuptools64, wheel] build-backend setuptools.build_meta [project] name myproj version 0.1.0 requires-python 3.9 dependencies [ requests2.31, ] [project.optional-dependencies] dev [ pytest7.4, ruff, ] [project.scripts] myproj myproj.cli:main [tool.setuptools.packages.find] where [src]几个点值得注意。setuptools64这个版本要求不是随便写的PEP 660 的可编辑安装支持从这个版本开始稳定。[tool.setuptools.packages.find]里where [src]告诉 setuptools 去哪里找包配合 src layout 使用。optional-dependencies把开发依赖单独拆出来别人装生产环境不会被 pytest 污染。5.3 pip install -e . 之后到底发生了什么这是整套方案里最值得理解的一步。执行pip install -e .之后pip 会在环境的site-packages里放一个.pth文件或者一个__editable__前缀的 finder 模块内容是把你项目的src目录加到sys.path。于是无论你从哪个工作目录、用哪个脚本启动import myproj都能解析到源码目录。关键区别在于这不是sys.path.append那种运行时注入而是在解释器启动阶段通过site模块生效的路径注册。它跟环境绑定不需要每份代码里都写一遍也不会因为执行顺序问题失效。项目改名、目录重排之后只需要重装一次。验证方法pip install -e . python -c import myproj; print(myproj.__file__)输出的路径应该指向你的src/myproj/__init__.py而不是site-packages下的副本。如果指向了site-packages说明装成了非可编辑模式改源码不会生效。注意可编辑安装和虚拟环境绑定。如果你pip install -e .装进了 venv A后来切到 venv B需要重新执行一次。这是“换环境后突然 import 不到”的常见原因。5.4 什么时候可以不用可编辑安装不是所有项目都值得上这套。一次性脚本、小工具、教学示例直接在根目录平铺文件、用绝对导入就够了。判断标准可以简单点如果这个项目有tests/目录、有超过两个层级的包嵌套、或者要被别人使用就值得上 src layout 可编辑安装。反之就别给自己增负担工具要为项目服务不是反过来。6. 调试、测试、Notebook 三条支线的一致性配置6.1 launch.json把 cwd、env、envFile 三件套写明白调试配置里跟导入最相关的字段有四个cwd、env、envFile、module/program。一个覆盖大多数场景的配置长这样{ version: 0.2.0, configurations: [ { name: Python: myproj, type: debugpy, request: launch, module: myproj.cli, cwd: ${workspaceFolder}, envFile: ${workspaceFolder}/.env, console: integratedTerminal, justMyCode: true } ] }envFile指向的.env文件会在调试启动时被加载这一点非常有用但有个前提VSCode Python 扩展默认会读取python.envFile设置指向的文件默认值就是${workspaceFolder}/.env调试配置里再写一次是显式声明避免设置被改过之后行为不一致。.env里设置PYTHONPATH要特别注意分隔符# Linux / macOS用冒号分隔 PYTHONPATH${workspaceFolder}/src:${workspaceFolder}/lib # Windows用分号分隔 PYTHONPATH${workspaceFolder}/src;${workspaceFolder}/lib${workspaceFolder}这个占位符在.env里是被支持的Python 扩展会做替换。如果你复制粘贴的时候忘了改分隔符表现出来就是“只有第一个路径生效”很难第一眼看出来。6.2 测试pytest 的 rootdir 和 conftest.py 位置决定一切pytest 有自己的模块解析逻辑跟直接跑脚本又不一样。它默认用 prepend 导入模式对于每个测试文件从它所在的目录往上一层层找找到第一个不含__init__.py的目录把这个目录插到sys.path前面。这就意味着tests/目录下有没有__init__.py会直接影响sys.path被改成什么样。如果tests/里没有__init__.py那么每个测试文件所在的目录都会被插进路径如果tests/是一个正式的包有__init__.py那么插入的就是项目的上一层目录。VSCode 里跑测试还需要配置{ python.testing.pytestEnabled: true, python.testing.unittestEnabled: false, python.testing.pytestArgs: [tests], python.testing.cwd: ${workspaceFolder} }python.testing.cwd这个字段常被忽略但它决定了 pytest 进程的工作目录进而影响 rootdir 的判定。如果它和你终端里实际执行的位置不一致就会出现“命令行跑测试全绿、VSCode 测试面板全红”的经典现象。统一的方法就是在项目根目录放一个pytest.ini或pyproject.toml段落把 rootdir 固定住[tool.pytest.ini_options] testpaths [tests] pythonpath [src]pythonpath这个配置项是 pytest 7 之后内置的不需要额外装pytest-pythonpath插件了。它的效果等价于在测试启动时把src加进路径比在每个conftest.py里手动操作sys.path干净得多。6.3 Notebook内核和解释器是两码事Jupyter 在 VSCode 里运行的时候走的是内核kernel机制跟普通的 Python 调试完全是两条路。你状态栏选中的解释器不一定是 Notebook 用的内核。所以会出现“普通 py 文件跑得通、.ipynb里 import 不到”的情况。解决方法是在 Notebook 右上角手动选择内核选择“Python Environments”下面那个带 venv 标记的条目。如果列表里找不到你的虚拟环境说明缺ipykernelpip install ipykernel python -m ipykernel install --user --name myproj --display-name myproj (.venv)装完之后重启 VSCode 窗口内核列表里就会出现。这一步在数据科学类的项目里几乎是必做的因为 Notebook 里的相对导入本来就少靠的都是安装后的包路径所以确保内核环境里有myproj的可编辑安装也就是在这个环境里执行过pip install -e .是必要条件。7. 把自己坑惨的命名冲突与大小写陷阱7.1 自己的文件叫 json.py 是自杀式命名这是最隐蔽的一类问题你在项目根目录建了一个json.py用来封装 json 处理逻辑然后在同目录的main.py里import json。因为sys.path[0]是脚本所在目录你的json.py优先级高于标准库的 json于是标准库被静默替换。报错不会出现在import json那一行而是出现在后面某处AttributeError: module json has no attribute dumps或者更离谱的ImportError: cannot import name JSONDecodeError from json。第一次遇到的时候能查半天。高危名字清单值得背下来json、random、types、queue、select、code、logging、email、test、string、os不太可能但存在、io、abc、copy、signal、platform。另外注意目录名也参与这个机制一个叫utils的目录如果和某个第三方包重名同样会截胡。判断方法在报错的文件里执行import json; print(json.__file__)看看输出指向哪里。指向项目目录而不是标准库问题就确认了。重命名是最彻底的解法。如果实在不能改名就用绝对导入加明确的包前缀但那种情况下你的项目结构本身可能就需要调整。7.2 大小写不敏感带来的“本地能跑、线上崩”macOS 默认的文件系统APFS和 Windows 的 NTFS 都是大小写不敏感的Linux 的 ext4 是大小写敏感的。这意味着文件叫DataLoader.py你写from .dataloader import DataLoader在 Mac 上能跑通在 Linux CI 上直接挂。这类问题的恶心之处在于它只在特定环境下暴露本地开发怎么都复现不出来。防御手段有两个一是建立命名规范模块文件名一律小写下划线类名才用大驼峰二是在 CI 里加一个大小写检查步骤或者干脆在本地开一个大小写敏感的 APFS 卷来做最终验证。我在实际项目里见过一次因为这类问题导致线上任务全挂的事故排查花了两个多小时成本相当高。7.3 缓存残留与语言服务器重启改了目录结构、删了包、重命名了模块之后偶尔会遇到“代码明明改了但行为还是旧的”这种情况。可能的原因有两层第一层是 Python 的字节码缓存__pycache__。正常情况下解释器会比对源文件时间戳自动失效缓存但如果手动复制过文件、时间戳被改乱就可能加载到旧的.pyc。清理方法很简单find . -name __pycache__ -type d -prune -exec rm -rf {} find . -name *.pyc -delete第二层是 Pylance 的索引缓存。改了pyproject.toml里的包配置、改了extraPaths、重装了包之后Pylance 的解析结果可能还是旧的。这时候执行命令面板里的“Python: Restart Language Server”或者干脆重启窗口比等它自己刷新靠谱。还有一个不太常见但确实存在的场景换了 Python 版本后旧的.venv目录里残留的site-packages结构已经不匹配pip 装包会报奇怪的错。这种时候最省事的做法就是删掉.venv重建不要试图修。8. 一套按顺序执行的排查清单把上面所有内容压缩成一个可执行流程遇到导入问题时从第一步往下走不要跳步。步骤动作目的1打印sys.executable和sys.version确认解释器是不是预期的那个2打印os.getcwd()确认工作目录判断相对路径和-m的基础3打印完整sys.path看目标包所在目录在不在列表里4检查报错模块名是否有命名为冲突的风险排除自己的文件遮蔽标准库或三方库5用python -m和直接跑文件各试一次判断问题是否来自启动方式6检查 Pylance 是否有红线红线是否与运行时一致区分静态分析问题和真实运行问题7检查launch.json/settings.json/.env的路径配置确认编辑器配置与预期一致8检查是否执行过pip install -e .以及装在哪个环境确认包级解析机制是否生效9检查文件名大小写与目录大小写排除跨平台差异10清理__pycache__并重启语言服务器排除缓存干扰这套顺序的设计逻辑是从最便宜、最确定的验证手段开始逐步排查到配置和结构层面。打印三个变量花不了十秒钟却能排除掉大部分问题。很多人反着来先怀疑代码写错改了半天 import 语句最后发现是解释器选错了得不偿失。还有一点值得强调不要用sys.path.append作为最终方案。它是有效的临时手段在排查阶段用来验证“是不是路径问题”非常好用但绝不能留在生产代码里。一个项目里出现多处sys.path.append等于宣告这个项目没有统一的包管理策略后面每加一个模块都是一次赌博。我在带人的过程中发现几乎所有人第一次遇到这类问题时都会走一段弯路先怀疑自己的 import 语法再怀疑是 VSCode 的 bug最后才想到环境问题。而一旦把sys.path这套机制理解透了这类问题就变成了一道选择题——按清单过一遍五分钟定位。真正花时间的从来不是解决问题而是想清楚问题出在哪一层。习惯性地把sys.executable、os.getcwd()、sys.path这三样东西打印出来看一眼这个小动作省下来的时间比任何插件都值。