Pylance补全卡顿的根源是autoSearchPaths默认开启导致无界扫描，应设为false并配合pyrightconfig.json的include/exclude精确限定索引范围，typeCheckingMode保持basic。

为什么Pylance补全总卡在“正在分析…”

这不是你网络慢或电脑差，而是Pylance在后台反复扫描整个工作区——包括venv、node_modules、__pycache__，甚至顺着软链接展开七八层路径建索引。右下角状态栏只显示Pylance但没带(typeCheckingMode: basic)，基本可以确定配置没生效。

必须关掉python.analysis.autoSearchPaths

这个开关默认为true，是所有卡顿的根源。它会让Pylance主动向上找父目录、扫同级src/和lib/，哪怕你根本不用那些代码。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 在 VS Code 设置（Ctrl+,）中搜autoSearchPaths，设为false
• 紧接着配python.analysis.extraPaths，只写你真正在写的模块，例如["src", "tests"]
• 路径必须是相对工作区根目录的，./src或绝对路径会失效
• monorepo 项目别加packages/**，只加当前子包，比如["packages/my-core"]

用pyrightconfig.json接管include规则

pyrightconfig.json比settings.json更优先，而且exclude常被忽略，include却一定生效。没这个文件，所有排除配置都可能白写。

• 在工作区根目录新建pyrightconfig.json，内容至少含：

  { "include": ["src","tests"], "exclude": ["**/venv/**","**/node_modules/**","**/__pycache__/**"] }

• include不能为空，也不能只写["."]，必须是明确子目录或 glob
• 改完后必须关闭并重新打开整个工作区，热重载不加载新配置
• 如果仍卡，检查include里是否误写了不存在的目录（比如拼错srcc），Pylance 会静默跳过但继续扫其父目录

typeCheckingMode别设strict

strict不只是“更严”，它是让Pylance加载完整类型系统：泛型约束、协议匹配、Literal 推导全开。遇到pydantic.BaseModel或numpy.ndarray这类 heavily-annotated 类型时，解析时间呈指数增长。

• 日常开发一律用basic：能抓str传给期待int的函数这类硬错误，但跳过高成本推导
• CI 或提交前用pyright CLI 单独跑一次strict，不拖慢编辑器
• 千万别在全局settings.json里设strict，Pylance 一打开site-packages里的大包就卡死
• 配合"python.analysis.diagnosticMode": "openFilesOnly"，只检查当前打开的文件，进一步减负

Pylance 的缓存机制本身没问题，问题出在它默认把“整个世界”当缓存目标。真正要动的不是清理缓存，而是精准划定它的边界——autoSearchPaths关不掉，其他所有优化都只是打补丁。