python 3.10启用pep 604后，str | int替代typing.union[str, int]，但混用或旧环境未兼容会导致importerror；应统一用|、字符串注解或typing_extensions，避免直接导入union。
Union类型写法变更导致ImportError
Python 3.10 默认启用 PEP 604，允许用 str | int 替代 typing.Union[str, int]。但如果你的代码里混用了两种写法，又没统一导入策略，就容易在运行时或类型检查阶段报 ImportError: cannot import name 'Union' from 'typing'——尤其当项目同时支持 Python 3.9 以下版本时，typing.Union 在某些旧环境里已被标记为弃用，而你又没做兼容兜底。
根本原因不是语法错了，而是解释器对 typing 模块的加载行为变了：3.10 开始，部分类型构造器（如 Union）被移入 typing 的内部实现，不再保证始终可直接导入；而 | 运算符由解释器原生支持，不依赖 typing 模块。
- 只在类型注解中使用
|时，完全不需要from typing import Union - 若仍需显式调用
Union（比如动态构造类型），应改用typing.Union（3.10+ 仍存在，但已不推荐）或升级到typing.Union的替代方案types.UnionType（仅限 3.10+，且不能用于字符串化注解） - 跨版本兼容写法：用字符串字面量绕过导入，例如
def parse(data: "str | int") -> "dict | None":，这样连typing都不用碰
typing.Union 和 | 在mypy/pyright中的行为差异
静态类型检查器对这两种写法的处理并不完全一致。mypy 0.98+ 默认把 str | int 当作等价于 Union[str, int]，但 pyright（VS Code 默认）在某些嵌套场景下会更严格：比如 List[str | int] 可能被拒绝，而 List[Union[str, int]] 被接受——这其实暴露了 PEP 604 规范尚未覆盖所有边界情况。
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 遇到
error: Invalid type alias类型别名错误，优先检查是否在泛型参数里用了裸|，尝试加括号：Dict[str, (int | None)]而非Dict[str, int | None] - 如果项目强制要求 mypy 兼容 3.9 以下版本，必须禁用 PEP 604 支持：在
mypy.ini中添加disallow_unions: true或使用命令行参数--disallow-unions -
typing_extensions包可提供向后兼容：安装后可用from typing_extensions import Union替代原生typing.Union，它在 3.7–3.12 全版本稳定
虚拟环境中typing模块版本错乱引发的冲突
很多项目会手动安装 typing-extensions 或误装第三方 typing 包（比如过时的 typing PyPI 包），导致 import typing 实际加载的是第三方副本而非标准库内置模块。这种情况下，即使 Python 是 3.10，typing.Union 也可能不可用或行为异常。
- 执行
python -c "import typing; print(typing.__file__)"，确认输出路径是标准库目录（如/usr/lib/python3.10/typing.py），而非site-packages下的路径 - 清理可疑包：
pip uninstall typing typing-extensions（除非你明确需要它），再重装干净的typing-extensions（仅用于兼容旧版本） - 在
pyproject.toml中显式约束：requires-python = ">=3.10"，并移除对typing的任何手动依赖声明
从3.9迁移到3.10时Union相关CI失败的典型修复路径
CI 流水线突然报 NameError: name 'Union' is not defined，大概率是因为某处写了 Union[str, int] 却忘了 from typing import Union，而之前靠 IDE 自动补全或旧版解释器宽容侥幸通过。3.10 对未声明的名称更严格，尤其在 from __future__ import annotations 开启后，类型注解不执行求值，但名称解析照常进行。
- 全局搜索
Union\[（注意转义方括号），定位所有显式使用Union的地方，逐个补上from typing import Union或直接替换为| - 对
type: ignore注释要警惕：有些团队用它掩盖Union导入缺失问题，升级后这些忽略变成“真忽略”，反而掩盖真实错误 - 检查
setup.py或pyproject.toml中的python_requires是否仍设为>=3.8，如果是，CI 可能仍在用旧解释器跑测试，需同步更新
真正麻烦的不是语法改写，而是那些藏在类型别名、文档字符串、配置文件里的隐式 Union 引用——它们不会报错，但会让类型检查器静默失效。动手前先跑一遍 mypy --show-traceback，比盲目替换更省时间。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
