VSCode 阅读 Python 大型项目的关键是：确保 Pylance 正确加载虚拟环境与依赖、熟练使用 F12/Shift+F12/Ctrl+T 等语义跳转、严格限制索引范围避免污染和卡顿。
直接说结论：VSCode 阅读 Python 大型项目，关键不是装一堆插件，而是让 Pylance 正确加载依赖、用好三类跳转、管住索引范围——否则你点 F12 跳不到定义，Shift+F12 查不到引用，搜索 Ctrl+T 返回一堆无关结果，纯属白费时间。
确保 Pylance 能识别你的虚拟环境和第三方包
这是所有跳转功能生效的前提。Pylance 默认只看当前工作区，不自动扫描 venv 或 poetry 环境里的包，更不会解析 setup.py 或 pyproject.toml 中声明的本地依赖。
- 打开命令面板
Ctrl+Shift+P，运行Python: Select Interpreter，手动选中项目根目录下的venv/bin/python（macOS/Linux）或venv\Scripts\python.exe（Windows）； - 检查状态栏左下角是否显示该路径，若显示
Python 3.x.x但没带路径，说明没生效； - 如果项目用
poetry，先运行poetry shell，再在 VSCode 终端里启动 VSCode：code .，否则Pylance找不到poetry的 site-packages； - 对本地开发依赖（如
-e ./lib/utils），必须在pyproject.toml的[tool.poetry.dependencies]或requirements.txt中显式声明，否则Pylance当它不存在。
用对快捷键组合，别靠鼠标点菜单
鼠标点“Go to Definition”容易误点到 stub 文件或错误位置；快捷键能触发语义分析，返回真实定义源码。
-
F12（或Ctrl+Click）：跳转定义，对重载函数会列出候选，用方向键选准目标； -
Shift+F12：查引用，结果多时右上角输入关键词过滤，比如搜user可快速排除username相关调用； -
Ctrl+T：全局搜符号名，输驼峰缩写即可匹配，httpResp能命中HTTPResponse；再按一次Ctrl+T切换为文件搜索（等价于Ctrl+P）； -
Ctrl+Shift+O：只在当前文件内搜函数/类/变量，适合快速定位方法，比滚动翻找快得多； - 避免用
Ctrl+F全局搜字符串——它不理解作用域，status可能匹配到日志、注释、变量名，噪音极大。
控制索引范围，否则 LSP 会卡死或漏跳
VSCode 默认递归索引整个工作区，遇到 node_modules、dist、__pycache__ 或生成代码目录时，不仅拖慢响应，还会污染符号表。
立即学习“Python免费学习笔记（深入）”；
- 在项目根目录的
.vscode/settings.json中配置：{ "files.exclude": { "**/__pycache__": true, "**/*.pyc": true, "**/migrations": true, "**/build": true }, "search.exclude": { "**/node_modules": true, "**/venv": true, "**/.git": true } } - 对 monorepo 结构（如含多个子包），用
File → Add Folder to Workspace…分别添加核心模块，而非把整个仓库拖进单个文件夹； - 如果某个子模块是通过
git submodule引入的，确保它已git submodule update --init，否则Pylance不会索引其内容； - 禁用
"python.analysis.extraPaths"指向未初始化的路径，否则 LSP 启动失败且无报错提示。
折叠 + Outline 视图，先看清骨架再钻细节
动辄 800 行的 views.py 或 models.py，一上来就展开所有函数，眼睛和脑子都累。先收起来，再按需展开。
-
Ctrl+K Ctrl+0折叠全部函数，只剩类名和顶层函数签名； -
Ctrl+Shift+O呼出 Outline，点击类名可快速跳转，右侧显示方法列表，支持模糊搜索（如输save过滤出save_user、save_log）； - 对长 if/else 或 try/except 块，用
Ctrl+Shift+[折叠，保留条件判断逻辑，隐藏具体实现； - 不要依赖 “自动折叠注释” —— 很多项目用
# --- Utils ---这类分隔线，VSCode 默认不识别，得手动加#region/#endregion才能折叠。
真正卡住人的，往往不是找不到某行代码，而是 Pylance 没加载对解释器、search.exclude 没配全导致索引爆炸、或者习惯性用 Ctrl+F 替代 Ctrl+T。这三处错了，再熟的快捷键也救不回来。
