Python pylance 的类型检查性能优化

pylance卡顿主因是全量索引，应关闭autosearchpaths、显式配置extrapaths和pyrightconfig.json的include、日常用basic类型检查、补全types-包、避免深层符号链接。

PyLance 启动后卡住或 CPU 占用高

PyLance 在大型项目里启动慢、编辑时卡顿，本质是它默认对整个工作区做全量类型索引。不是你代码写得慢，是它在后台拼命读 __pycache__、扫描第三方包、解析上万行 stub 文件。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 在 VS Code 设置中关闭自动索引：把 "python.analysis.autoSearchPaths" 设为 false，避免它递归扫描无关目录
• 用 "python.analysis.extraPaths" 显式声明只检查的路径，比如 ["src", "tests"]，跳过 venv、node_modules、build
• 确认 pyrightconfig.json 存在且配置了 "include"（而非 "exclude"），因为 PyLance 优先读它；exclude 有时被忽略，include 更可靠

typeCheckingMode: basic vs strict 的实际影响

"python.typeCheckingMode" 不只是开/关开关，它直接决定 PyLance 是否加载完整类型系统。设成 "basic" 时，它跳过泛型约束、协议检查、Literal 推导等——这些功能很准，但解析成本高，尤其遇到 numpy 或 pydantic 这类 heavily-annotated 包时，会反复重算类型流。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 日常开发用 "basic"，足够捕获 str 传给期待 int 的函数这类硬错误
• CI 或提交前用 "strict"，配合 pyright CLI 单独跑一次，不拖慢编辑体验
• 别在 settings.json 里全局设 "strict"，容易让 PyLance 在打开 venv/lib/python3.x/site-packages 里的某个大包时卡死

第三方库类型提示缺失导致反复 fallback

PyLance 遇到没类型提示的库（比如老版本 requests、自研未打 stub 的 SDK），会尝试从源码 infer，这个过程不可缓存、不可中断，且每次打开新文件都可能重来。你看到的“正在分析…”提示，八成卡在这儿。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 用 pip install types-requests types-redis 等 types- 包补全常用库，比自己写 .pyi 现实得多
• 对内部 SDK，在其 pyproject.toml 加 [[tool.mypy.plugins]] 或提供 py.typed 文件，否则 PyLance 永远当它是 “untyped”
• 在 pyrightconfig.json 的 "stubPath" 下建软链接指向你整理好的 stub 目录，避免它每次去 site-packages 翻找

workspaceFolder 太深或含符号链接引发路径爆炸

VS Code 把软链接当真实路径展开，PyLance 又按绝对路径去重——结果一个 ../common 被展开成十几个不同绝对路径，每个都单独索引。你改一行，它重刷五遍。

实操建议：

立即学习“Python免费学习笔记（深入）”；

• 用 ls -la 检查工作区根目录下有没有隐藏的符号链接（尤其 src → ../shared/src 类型）
• 把 workspace folder 设为最浅层级：比如项目结构是 monorepo/apps/web，别打开 monorepo，直接打开 monorepo/apps/web
• 在 settings.json 加 "python.defaultInterpreterPath" 指向项目级 venv，避免它跨目录找解释器再顺带扫一堆无关 site-packages

PyLance 的性能瓶颈往往不在“要不要开”，而在“它到底在索引什么”。很多人调了半天 typeCheckingMode，却没发现真正拖慢的是某个被意外包含的 logs/ 目录，或者一个没删干净的 __pycache__ 嵌套了七层。