Firebase V9 SDK中TypeScript泛型Firestore转换器报错排查

使用Firebase JavaScript Version 9 SDK时，尝试通过withConverter()结合TypeScript接口转换Firestore数据，实现可复用泛型转换器后调用出现TypeScript错误，代码及错误信息如下：

interface User {
  id?: string;
  name: string;
}

const converter = <T>() => ({
  toFirestore: (data: Partial<T>) => data,
  fromFirestore: (snap: FirebaseFirestore.QueryDocumentSnapshot) =>
    snap.data() as T,
});

const userDocRef = doc(db, 'users', 'my-user-id').withConverter(
  converter<User>() // <-- 错误位置
);

错误提示：

No overload matches this call.
  Overload 1 of 2, '(converter: null): DocumentReference<DocumentData>', gave the following error.
  Overload 2 of 2, '(converter: FirestoreDataConverter<User>): DocumentReference<User>', gave the following error. ts(2769)

错误原因 #

核心问题是自定义转换器类型与Firebase官方定义的FirestoreDataConverter接口不兼容：

1. toFirestore方法参数类型不匹配
   FirestoreDataConverter接口中，toFirestore方法包含两种重载：

   • 处理新增数据：接受Partial<T>类型
   • 处理更新数据：接受Partial<UpdateData<T>>类型
     你实现的toFirestore只声明了Partial<T>作为参数，无法匹配接口要求的联合类型，导致TypeScript无法识别这是合法的FirestoreDataConverter<User>实例。

2. 类型推导缺失
   没有显式指定转换器的返回类型为FirestoreDataConverter<T>，TypeScript无法自动推导出自定义对象符合官方接口规范，进一步加剧了类型不匹配问题。

修正方案 #

显式约束转换器返回类型，并兼容toFirestore的两种参数类型：

import { FirestoreDataConverter, UpdateData, QueryDocumentSnapshot } from "firebase/firestore";

interface User {
  id?: string;
  name: string;
}

const converter = <T>(): FirestoreDataConverter<T> => ({
  toFirestore: (data: Partial<T> | UpdateData<T>) => data,
  fromFirestore: (snap: QueryDocumentSnapshot) => ({
    ...snap.data(),
    id: snap.id // 可选：自动将文档ID注入到数据中
  }) as T,
});

const userDocRef = doc(db, 'users', 'my-user-id').withConverter(converter<User>());

修正后转换器完全符合FirestoreDataConverter接口规范，TypeScript错误会消失。

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