升级firebase_functions至6.3.2后返回DocumentReference触发栈溢出错误

变更原因 #

firebase-functions 6.x系列调整了Gen 1云函数中onCall返回值的序列化逻辑：

• 旧版本（如4.2.1）会自动将Firestore的DocumentReference对象序列化为客户端可解析的结构化对象（包含path、id等核心字段），且内部处理了对象的循环引用问题。
• 新版本的序列化器更严格遵循标准JSON规则，不再对Firebase特定类型做自动转换。当返回包含DocumentReference数组的对象时，序列化器会递归遍历对象内部属性，触发DocumentReference与关联Firestore实例之间的循环引用，最终导致栈溢出错误。

可行解决方案 #

方案1：手动转换DocumentReference为兼容格式 #

编写工具函数遍历文档数据，将所有DocumentReference转换为旧版本返回的结构，确保客户端无需修改即可解析：

// 转换函数：将DocumentReference转为旧版本兼容的对象
function convertRefs(obj) {
  if (obj instanceof Array) {
    return obj.map(item => convertRefs(item));
  }
  if (obj && typeof obj === 'object') {
    if (obj._firestore && obj._path) { // 识别DocumentReference
      return {
        path: obj.path,
        id: obj.id,
        parent: obj.parent ? convertRefs(obj.parent) : null
      };
    }
    for (const key in obj) {
      obj[key] = convertRefs(obj[key]);
    }
  }
  return obj;
}

// 修改后的云函数
exports.getItem = functions.https.onCall(async (data, context) => {
  let id = data.id;
  let result = {};

  const itemDoc = await db.collection("items").doc(id).get(); 
  result.item = convertRefs(itemDoc.data()); // 转换后返回
  return result;
});

方案2：降级firebase-functions至兼容版本 #

如果暂时无法修改云函数代码，可将firebase-functions版本降级到生产环境验证正常的版本（如4.2.1），注意需确认与Node.js 22、firebase-admin 13.4.0的兼容性：

// package.json中修改依赖
"firebase-functions": "^4.2.1"

执行npm install更新依赖后重新部署或启动模拟器。

方案3：使用自定义序列化逻辑 #

利用JSON.stringify的第二个参数自定义序列化过程，跳过循环引用并转换DocumentReference：

exports.getItem = functions.https.onCall(async (data, context) => {
  let id = data.id;
  let result = {};

  const itemDoc = await db.collection("items").doc(id).get(); 
  const serializedData = JSON.stringify(itemDoc.data(), (key, value) => {
    if (value && value._firestore && value._path) { // 识别DocumentReference
      return { path: value.path, id: value.id };
    }
    return value;
  });
  result.item = JSON.parse(serializedData);
  return result;
});

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