Python 3.12 新增 PEP 695 泛型语法（如 class Config[T]:）、type 别名泛型（type Tree[T] = ...）、TypeVar default 参数及 Annotated 元数据机制，需解释器 3.12+ 与 Pyright≥1.1.350/mypy≥1.10.0 双向兼容支持。
Python 3.12 的类型注释本身没有破坏性变更，但新增的泛型语法（PEP 695）和类型变量能力（如 default 参数、更宽松的约束）让类型声明更简洁、表达力更强；静态检测工具需更新到支持 PEP 695 的版本，否则会误报或跳过新语法。
Python 3.12 新增的类型语法有哪些必须知道的
这些不是“可选糖”，而是影响类型检查器能否正确解析的关键点：
-
class Config[T]:替代旧式class Config(Generic[T]):—— 不再需要导入Generic，也不用继承；但若使用Generic仍合法，只是冗余 -
type Tree[T] = Node[T] | None是合法类型别名定义，而旧版只允许Tree = TypeVar("Tree")这类占位写法 -
TypeVar("T", default=int)现在被 Pyright 1.1.330+ 和 mypy 1.10+ 正式支持；未指定default时行为不变，但加了之后能缓解泛型参数未绑定时的Unknown推断 -
Annotated[T, meta]中的T若为未约束TypeVar（如Ta = TypeVar("Ta")），静态检查器将忽略其类型语义，仅保留元数据 —— 这是实现「运行时元数据 + 零干扰类型检查」的核心机制
Pyright / mypy 要升级到什么版本才认得 class[T] 语法
低版本会直接报错，比如 Unexpected token "[" 或把 class Box[T]: 当作语法错误。必须满足：
- Pyright：至少
1.1.320（2025年11月发布），推荐用1.1.350+；可通过pyright --version检查 - mypy：至少
1.9.0（2025年10月），但1.10.0+才完整支持default=...和嵌套泛型推导 - VS Code 用户注意：
python扩展内置的 Pyright 版本可能滞后，建议手动安装 Pyright CLI 并在设置中指定路径："python.typeChecking.pyright.path": "./node_modules/.bin/pyright"
为什么 pip install mypy 后 still get “invalid syntax” 报错
这不是 mypy 本身的 bug，而是你运行的是旧版 Python 解释器去执行含 class[T] 的代码 —— Python 解释器在 import 或 AST 解析阶段就拒绝了该语法，根本没走到 mypy。
立即学习“Python免费学习笔记（深入）”；
- 确认
python --version输出确实是3.12.x，不是系统残留的 3.11 或更早版本 - 虚拟环境中执行
which python和python -c "import sys; print(sys.version)"，双验证 - 常见陷阱：用
pyenv global 3.12.0切换后，VS Code 终端未重启，仍加载旧 shell 环境；或pip install mypy装到了系统 site-packages，但项目用的是 venv 且未激活 - 临时验证方法：写一行
class A[T]: pass，直接运行python file.py—— 若报SyntaxError: invalid syntax，说明解释器不支持，跟 mypy 无关
搭建最小可行静态检测环境的三步实操
绕开 IDE 插件、配置文件等干扰，先确保底层链路通：
- 用
pyenv install 3.12.3 && pyenv local 3.12.3固定解释器版本（macOS/Linux）；Windows 用户用py -3.12显式调用 - 新建空目录，
python -m venv .venv && source .venv/bin/activate（macOS/Linux）或.venv\Scripts\activate（Windows） - 装工具：
pip install "pyright>=1.1.350" "mypy>=1.10.0"，然后创建test.py写class Box[T]: ...，分别跑pyright test.py和mypy test.py看是否静默通过
真正容易被忽略的是：Python 解释器版本和静态检查器版本必须**双向兼容**——解释器要能 parse 新语法，检查器要能 semantic-analyze 新结构；任一端卡住，都会表现为“语法错误”或“无法识别泛型参数”。
