Firestore 从服务端返回的 Timestamp 在 JSON 序列化后会丢失类型信息，仅保留 _seconds 和 _nanoseconds 字段；客户端需手动将其转换为 JavaScript Date 对象，否则调用 toDate() 会报错。
firestore 从服务端返回的 timestamp 在 json 序列化后会丢失类型信息，仅保留 `_seconds` 和 `_nanoseconds` 字段；客户端需手动将其转换为 javascript `date` 对象，否则调用 `todate()` 会报错。
当你通过 Firestore SDK（如 Node.js Admin SDK）读取文档时，Timestamp 字段会被自动反序列化为 firestore.Timestamp 实例，因此可直接调用 .toDate() 方法。但一旦数据被序列化为 JSON（例如通过 HTTP API 发送给浏览器），原始类型信息即被丢弃——Timestamp 被扁平化为一个普通对象：
{
"_seconds": 1698460669,
"_nanoseconds": 951000000
}
此时它已不再是 firestore.Timestamp，自然无法调用 .toDate()，从而触发 TypeError: toDate is not a function。
✅ 正确的客户端解析方式
在浏览器等纯 JSON 环境中，需手动重建 Date 对象。注意：
- _seconds 是 Unix 时间戳（秒级），而 Date() 构造函数接受毫秒级时间戳；
- _nanoseconds 需转换为毫秒（除以 1,000,000），并与 _seconds * 1000 相加，以获得更高精度（可选）。
基础方案（秒级精度，推荐多数场景）：
const timestampObj = obj.data.dateUpdated; const date = new Date(timestampObj._seconds * 1000); console.log(date.toISOString()); // e.g. "2023-10-27T14:37:49.000Z"
高精度方案（含纳秒，适用于对毫秒级一致性有要求的场景）：
const { _seconds, _nanoseconds } = obj.data.dateUpdated;
const milliseconds = _seconds * 1000 + Math.floor(_nanoseconds / 1_000_000);
const date = new Date(milliseconds);
console.log(date.toISOString()); // 更精确的时间表示
⚠️ 注意事项与最佳实践
- 避免在服务端做无意义的 .toDate() 调用：若使用 Admin SDK 查询并直接处理数据（未 JSON 序列化），应确保 dateUpdated 确实是 firestore.Timestamp 类型（可通过 instanceof firestore.Timestamp 校验）；
- 传输层设计建议：若前后端频繁交互时间字段，可考虑在写入时统一存为毫秒时间戳（Date.now()）或 ISO 字符串（new Date().toISOString()），规避类型丢失问题；
- 服务端反序列化（补充）：若需在 Node.js 环境中将 JSON 中的 _seconds/_nanoseconds 还原为 Timestamp，可使用 new firestore.Timestamp(_seconds, _nanoseconds)；
- 前端 SDK 替代方案：若项目允许，推荐直接在浏览器中使用 @firebase/firestore 客户端 SDK（而非 Admin SDK + 自定义 API），它会自动处理 Timestamp 的序列化/反序列化。
总之，该错误并非 Bug，而是 JSON 类型系统固有限制所致。理解 Firestore 的序列化行为，并在 JSON 边界处主动做类型重建，是保障时间字段可靠性的关键。
