Firebase Admin Node 中 Firestore 写入数据时出现 NOT_FOUND 错误的解决方案

问题背景

在使用 Firebase Admin Node SDK 进行 Firestore 数据写入操作时，开发者可能会遇到一个令人困惑的错误："Error: 5 NOT_FOUND"。这个错误通常发生在尝试向空数据库写入数据时，错误信息缺乏明确的解释，给调试带来了困难。

错误表现

当开发者尝试执行基本的写入操作时，例如：

const docRef = db.collection('users').doc('alovelace');
await docRef.set({
    first: 'Ada',
    last: 'Lovelace',
    born: 1815
});

系统会返回以下错误信息：

Firestore (7.9.0) [WriteBatch.commit]: Sending 1 writes
Firestore (7.9.0) [ClientPool.acquire]: Creating a new client
Firestore (7.9.0) [clientFactory]: Initialized Firestore GAPIC Client
Firestore (7.9.0) [Firestore.request]: Sending request...
Firestore (7.9.0) [Firestore.request]: Received error: Error: 5 NOT_FOUND:

根本原因分析

这个错误通常与以下几个潜在问题相关：

1. 数据库未正确初始化：Firestore 数据库可能尚未在 Firebase 控制台中创建或启用
2. 服务账号权限不足：使用的服务账号可能缺少必要的 Firestore 访问权限
3. 项目配置问题：Firebase 项目配置可能存在问题，导致无法正确访问数据库
4. 网络连接问题：可能存在网络限制阻止了与 Firestore 服务的通信

解决方案

1. 检查 Firestore 数据库状态

首先确保在 Firebase 控制台中已经创建了 Firestore 数据库：

1. 登录 Firebase 控制台
2. 选择对应项目
3. 在左侧菜单中找到 Firestore 数据库
4. 确认数据库已创建并处于活动状态

2. 验证服务账号权限

确保使用的服务账号具有足够的权限访问 Firestore：

1. 检查服务账号 JSON 文件是否完整且有效
2. 在 Google Cloud IAM 控制台中确认服务账号具有以下角色：
   • Cloud Datastore Owner
   • Firebase Admin SDK Administrator Service Agent

3. 检查项目配置

确认 Firebase 项目配置正确：

1. 确保初始化代码中使用的项目ID与服务账号匹配
2. 验证初始化代码是否正确加载了服务账号凭据

4. 网络连接检查

如果是本地开发环境，检查网络连接：

1. 确保开发机器可以访问 Firestore 服务
2. 检查防火墙设置是否阻止了相关端口
3. 尝试使用其他网络环境测试

最佳实践

为了避免类似问题，建议开发者：

1. 在初始化代码中添加错误处理和日志记录
2. 使用环境变量管理敏感信息，而不是硬编码在代码中
3. 定期检查服务账号的权限状态
4. 在开发初期就设置详细的日志级别，便于调试

总结

Firebase Admin Node SDK 中的 NOT_FOUND 错误通常与数据库访问权限或配置问题相关。通过系统地检查数据库状态、服务账号权限和项目配置，大多数情况下可以解决这个问题。开发者应该养成良好的调试习惯，利用日志工具和错误处理机制，以便快速定位和解决类似问题。