Python 3.10 中 Union[str, None] 报错是因类型检查器弃用旧写法，推荐改用 str | None 或 Optional[str]；运行时仍合法，但 mypy 等工具会警告，需调整注解并配置或忽略检查。

Python 3.10 中 Union[str, None] 报错是因为类型检查器不推荐旧写法

Python 3.10 默认启用 PEP 604，允许用 | 写联合类型（如 str | None），但同时对 Union 的使用更严格——尤其在注解中直接写 Union[str, None] 时，部分类型检查器（如 mypy 0.950+、pyright）会警告或报错，提示应改用 | 或 Optional。

这不是语法错误，而是类型检查层面的弃用提示。运行时 Union[str, None] 仍合法，但工具链已倾向新式写法。

哪些地方必须改？优先替换这三类写法

以下写法在 3.10+ 环境中容易触发 warning 或 error，建议统一调整：

• Union[str, None] → 改为 str | None（最直接）或 Optional[str]
• Union[int, str, None] → 改为 int | str | None（Optional 只支持单类型，不适用）
• 函数返回注解里写 -> Union[Dict[str, Any], None] → 改为 -> dict[str, Any] | None（注意：Python 3.9+ 已支持 dict 和 list 等内置泛型）

myPy 报 error: Use 'X | Y' instead of 'Union[X, Y]' 怎么关或绕过

如果你暂时不能全量迁移，又想让 mypy 不报这个错，可在配置中关闭该检查：

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

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

在 mypy.ini 或 pyproject.toml 中添加：

[mypy]
warn_return_any = False
disallow_untyped_defs = True
# 关键项：
disable_error_code = "misc"

但更稳妥的做法是局部忽略：

• 在出问题的行末加 # type: ignore[union-alias]（myPy 1.0+）
• 或整行加 # type: ignore（粗粒度，不推荐）
• 注意：Union 在运行时仍需从 typing 导入（如做 isinstance 判断），此时不能删掉导入语句

兼容 Python

如果代码要跑在 3.9 及更早版本，| 会直接语法报错。这时必须保留 Union 或用字符串字面量注解：

• Python 3.9–3.10 兼容写法：from typing import Union + Union[str, None]
• Python 3.7–3.9 安全写法：from typing import Optional + Optional[str]
• 跨版本最稳方案（推荐）："str | None"（字符串字面量注解），3.7+ 都支持，且 mypy/pyright 能正常解析

垂直线符号不是万能胶——它只在类型注解上下文中有效；一旦进入运行时类型判断（比如 get_args(YourType)），就得靠 typing.get_origin 和 get_args 解析，而它们对字符串字面量无能为力。