React中useRef的T|null函数重载为何呈现反向匹配逻辑？

在React的类型定义文件中，useRef存在两个函数重载声明：

function useRef<T>(initialValue: T): MutableRefObject<T>;
// convenience overload for refs given as a ref prop as they typically start with a null value
/**
 * ...
 *
 * Usage note: if you need the result of useRef to be directly mutable, include `| null` in the type
 * of the generic argument.
 *
 * ...
 */
function useRef<T>(initialValue: T|null): RefObject<T>;

实际使用中会出现看似反直觉的匹配结果：

• 当显式声明useRef<T|null>时，匹配的是第一个返回MutableRefObject<T>的重载；
• 当声明useRef<T>时，却匹配第二个返回RefObject<T>的重载。

核心原因解析 #

这是TypeScript的重载解析优先级与类型兼容性共同作用的结果：

1. 显式指定带null的泛型参数时
   当你显式传入T|null作为泛型参数，TypeScript会优先尝试将其代入第一个重载的类型约束：第一个重载的参数类型为泛型T（此时会被替换为你传入的T|null），参数类型完全匹配，因此直接命中第一个重载，返回可变的MutableRefObject<T|null>。

2. 指定非null泛型参数时
   当你使用useRef<T>，如果初始值是null（这是ref作为组件props传递的常见场景），null并不兼容纯T类型（除非T本身包含null），因此第一个重载不满足匹配条件。此时TypeScript会尝试匹配第二个重载：第二个重载的参数类型为T|null，null完全兼容该类型，泛型参数T会被推断为目标类型，最终返回只读的RefObject<T>。

3. 重载的设计意图
   这组重载是为了适配React中两种常见的ref使用场景：

• 场景一：需要可变的ref容器（比如存储定时器ID、临时DOM引用），此时显式指定T|null作为泛型，就能拿到可直接修改.current属性的MutableRefObject；
• 场景二：将ref作为props传递给组件，这类ref通常初始值为null，TypeScript会自动匹配第二个重载，返回只读的RefObject，符合ref传递的最佳实践。

内容的提问来源于stack exchange，提问作者홍우지