Firebase Admin与客户端SDK的DocumentReference类型兼容问题求助

在Firebase v9模块化版本后，客户端firebase/firestore和服务端firebase-admin/firestore的DocumentReference类型定义出现差异，导致共享模型时出现类型错误。以下是几种优雅的解决思路：

1. 定义通用联合类型 #

直接创建兼容两端的联合类型别名，让两端的DocumentReference都能赋值给模型中的字段：

import type { DocumentReference as ClientDocRef } from "firebase/firestore";
import type { DocumentReference as AdminDocRef } from "firebase-admin/firestore";
import type { DocumentData } from "firebase/firestore";

// 兼容客户端和Admin端的通用文档引用类型
type UniversalDocRef<T = DocumentData> = ClientDocRef<T> | AdminDocRef<T>;

// 共享模型使用该通用类型
type Profile = {
  name: string;
  ref: UniversalDocRef;
};

2. 提取核心属性定义基础接口 #

如果只用到DocumentReference的核心功能，可以定义一个仅包含必要属性/方法的接口，利用TypeScript的结构类型系统，两端的实例都能自动适配：

import type { DocumentData } from "firebase/firestore";

// 定义基础文档引用接口，只保留业务中实际用到的成员
interface BaseDocumentReference<T = DocumentData> {
  id: string;
  path: string;
  get(): Promise<{ data(): T | undefined }>;
  update(data: Partial<T>): Promise<void>;
  // 根据需求添加其他需要的方法
}

// 共享模型使用该接口
type Profile = {
  name: string;
  ref: BaseDocumentReference;
};

3. 用类型工具抹平差异属性 #

针对两端类型的差异（Admin端多了converter和type属性），使用Omit或Partial工具类型来统一类型：

import type { DocumentReference as ClientDocRef } from "firebase/firestore";
import type { DocumentReference as AdminDocRef } from "firebase-admin/firestore";
import type { DocumentData } from "firebase/firestore";

// 将Admin端的差异属性设为可选，让两端类型兼容
type CompatibleDocRef<T = DocumentData> = ClientDocRef<T> & Partial<Pick<AdminDocRef<T>, "converter" | "type">>;

// 或者移除Admin端的差异属性，对齐客户端类型
// type CompatibleDocRef<T = DocumentData> = Omit<AdminDocRef<T>, "converter" | "type">;

type Profile = {
  name: string;
  ref: CompatibleDocRef;
};

4. 封装类型转换函数 #

如果不想修改共享模型的类型，可以封装一个安全的类型转换函数，替代零散的类型断言或@ts-expect-error：

import type { DocumentReference as AdminDocRef } from "firebase-admin/firestore";
import type { DocumentReference as ClientDocRef } from "firebase/firestore";
import type { Profile } from "./your-shared-model";

// 封装统一的类型转换函数，集中处理类型兼容逻辑
function toProfileDocRef<T>(ref: AdminDocRef<T> | ClientDocRef<T>) {
  return ref as unknown as ClientDocRef<T>;
}

// 服务端使用示例
const adminRef = admin.firestore().doc("profiles/user1");
const profile: Profile = {
  name: "张三",
  ref: toProfileDocRef(adminRef)
};

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