vscode默认不启用python类型检查，必须显式设置python.languageserver为pylance且python.analysis.typecheckingmode为basic或strict；确认方式是悬停函数名显示完整类型签名，而非仅函数名。
VSCode 默认不会主动检查 Python 类型注解，必须显式启用类型检查引擎（Pylance 或 Pyright），否则 def foo(x: int) -> str: 这类注解只是“装饰”，不报错也不提示。
怎么确认 Pylance 已启用并接管类型检查
很多人以为装了 Python 扩展就自动有类型检查，其实不是。VSCode 的 Python 扩展默认用的是旧版 Jedi 语言服务器，它几乎不处理类型注解。
- 打开 VSCode 设置（
Ctrl+,），搜索python.languageServer，确保值是"Pylance"（不是"Jedi"或空） - 再搜
python.analysis.typeCheckingMode，设为"basic"或"strict"—— 这个开关才是触发类型校验的真正开关 - 重启 VSCode 后，把光标悬停在任意带注解的函数名上，如果能看到
(function) foo(x: int) -> str，说明 Pylance 已生效；如果只显示(function) foo，大概率没启对
pyrightconfig.json 比 settings.json 更可靠
项目级配置写在 pyrightconfig.json 里，比全局或用户级的 settings.json 更稳定，尤其当你有多个 Python 项目时，避免互相干扰。
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 在项目根目录新建
pyrightconfig.json，内容至少包含"include"和"typeCheckingMode" -
"include": ["**/*.py"]是必须的，否则 Pylance 可能跳过子目录里的文件 - 排除虚拟环境：加
"exclude": ["**/venv", "**/.venv", "**/__pycache__"]，否则类型检查会卡顿甚至崩溃 - 不要依赖
settings.json里的python.analysis.typeCheckingMode单独生效 —— 它只在没有pyrightconfig.json时才 fallback 生效
为什么有些第三方库类型不识别？
比如 import requests 后，requests.get(...).json() 的返回值标成 Any，不是 dict 或 list —— 这不是你配置错了，是 requests 本身没提供类型存根（stub files）。
- 优先安装官方类型包：
pip install types-requests、pip install types-redis等（PyPI 上以types-开头的包） - 若无对应
types-包，可在pyrightconfig.json中加"stubPath": "./typings"，然后手动放存根文件进去 - 临时绕过：在出问题那行末尾加
# type: ignore，但别滥用，这会掩盖真实问题 - 注意：mypy 和 Pyright 对存根的支持程度不同，Pyright（Pylance）通常更宽容，能从源码做一定推断；mypy 则更依赖显式存根
strict 模式下最常见的误报和应对
开 "typeCheckingMode": "strict" 后，reportOptionalMemberAccess、reportCallIssue 这类诊断会变活跃，但部分提示其实是“过度防御”。
-
reportOptionalMemberAccess报"Cannot access member 'xxx' for optional type 'X | None'：多数情况只需加if obj is not None:或assert obj is not None -
reportUntypedFunctionDecorator报装饰器没类型：第三方装饰器（如@dataclass、@cached_property）常触发，可在pyrightconfig.json中设"reportUntypedFunctionDecorator": "none" - 动态属性（如通过
__getattr__注入的字段）会被标红：用# type: ignore[attr-defined]精准忽略，比全行# type: ignore更安全 - 别为了过 strict 而删掉有用的运行时逻辑，比如把
getattr(obj, 'field', None)强改成obj.field—— 那是在用类型检查换运行时稳定性
类型检查不是越严越好，而是要让提示落在你真可能出错的地方。一个没配 pyrightconfig.json 的项目，即使开了 strict，也可能漏检子目录；而一个配了但没排除 venv 的项目，又可能假阳性满天飞。关键是让配置落地到文件系统层级，而不是只改设置界面。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
