使用typing模块编写类型提示时，何时该用TypeVar，何时不该用？

算力阿峰

2026-5-7

TypeVar vs Union：核心差异与适用场景

这个问题问得非常好——很多刚接触Python类型提示的开发者都会混淆TypeVar和Union的用法，尤其是在这种二选一的类型场景里。咱们直接从核心差异和实际场景来拆解：

1. 类型一致性约束：TypeVar强制“同类型”，Union允许“任意选”

这是两者最本质的区别：

TypeVar 定义的是一个“类型变量”，它代表某个特定的类型（要么是str，要么是int），并且在同一个函数的多个位置（参数、返回值）会保持这个类型的一致性。
Union 只是表示“这个位置可以是几种类型中的任意一种”，不同位置之间不需要保持类型统一。

举个直观的例子：

from typing import TypeVar

StrOrInt = TypeVar('StrOrInt', str, int)

def combine(a: StrOrInt, b: StrOrInt) -> StrOrInt:
    return a + b

这里类型检查器会强制要求：a和b必须同时是str，或者同时是int。如果你传a="hello"和b=123，类型检查工具（比如mypy）会直接报错，因为违反了类型一致性。

from typing import Union

StrOrInt = Union[str, int]

def combine(a: StrOrInt, b: StrOrInt) -> StrOrInt:
    return a + b

此时类型检查器不会阻止你传a="hello"和b=123——它只关心每个参数是str或int，不要求两者类型统一。虽然这段代码运行时会抛出TypeError，但类型提示不会提前拦截。

如果你需要写泛型函数/类，让类型可以“复用”和“关联”，TypeVar是必不可少的，Union完全做不到这一点。比如：

from typing import TypeVar, List

# 定义一个通用类型变量T
T = TypeVar('T')

def get_first_element(lst: List[T]) -> T:
    return lst[0]

这里TypeVar的作用是告诉类型检查器：返回值的类型和列表中元素的类型完全一致。不管你传List[str]还是List[int]，函数都会返回对应的类型。如果用Union的话，你只能写成Union[str, int, ...]，无法动态关联输入输出的类型。

回到你给出的单参数例子：

def foo(bar: str_or_int): pass

如果只是单个参数，没有其他位置需要复用这个类型，TypeVar和Union在类型检查的表层效果上看起来差不多，但语义完全不同：

用TypeVar：表示bar是某一种确定的类型（要么全是str，要么全是int），适合未来可能扩展函数（比如加参数、让返回值和bar同类型）的场景。
用Union：表示bar可以是str或int中的任意一个，适合函数内部逻辑对两种类型分别处理，且不需要类型一致性的场景。

内容的提问来源于stack exchange，提问作者actual_panda