使用PHP从Cloud Firestore嵌套集合中获取文档失败

我之前也碰到过类似的嵌套集合访问问题，咱们一步步来排查和解决这个问题。

先还原下你的问题场景：

按照官方示例操作时，直接访问顶层集合cities可以正常运行，但访问嵌套集合countries/USA/cities时抛出HTTP Error 500，代码片段如下：

$db = new FirestoreClient([ 'projectId' => $projectId, ]);
// 正常运行的顶层集合访问代码
//$citiesRef = $db->collection('cities'); 
// 抛出500错误的嵌套集合访问代码
$citiesRef = $db->collection('countries')->document('USA')->collection('cities'); 
$documents = $citiesRef->documents();

下面是几个常见的排查方向和解决方案：

1. 先确认路径和资源的存在性 #

Firestore对路径的匹配是严格到极致的，哪怕一点小错误都会导致找不到资源：

• 检查countries集合下是否真的存在USA这个文档（注意大小写，比如写成usa就会找不到）；
• 确认USA文档下确实创建了cities子集合，并且子集合里有至少一个文档；
• 可以直接在Firestore控制台手动导航到countries > USA > cities路径，验证资源是否存在。

2. 检查Firestore安全规则权限 #

很多时候500错误的本质是权限被拒绝，但PHP客户端会封装成通用的服务器错误：

• 临时在开发环境设置宽松的测试规则（测试完记得改回去），验证是否是权限问题：

  rules_version = '2';
  service cloud.firestore {
    match /databases/{database}/documents {
      match /{document=**} {
        allow read, write: if true;
      }
    }
  }
  

• 如果设置后能正常获取文档，就说明是原规则限制了嵌套集合的读取权限，再调整为符合业务需求的规则即可。

3. 更新PHP客户端依赖版本 #

旧版本的google/cloud-firestore包可能存在嵌套集合路径处理的bug：

• 用Composer更新到最新版本：

  composer update google/cloud-firestore
  

• 同时检查grpc和protobuf扩展的版本是否符合包的要求，这些底层扩展的问题也可能引发HTTP 500错误。

4. 捕获异常查看具体错误信息 #

别只盯着500，把代码包在try-catch里，获取Firestore返回的具体错误：

try {
  $db = new FirestoreClient([ 'projectId' => $projectId, ]);
  $citiesRef = $db->collection('countries')->document('USA')->collection('cities');
  $documents = $citiesRef->documents();
  
  foreach ($documents as $document) {
      if ($document->exists()) {
          printf('文档%s的数据：', $document->id());
          print_r($document->data());
      } else {
          printf('文档%s不存在！', $document->id());
      }
  }
} catch (\Google\Cloud\Core\Exception\GoogleException $e) {
  echo '具体错误：' . $e->getMessage();
}

通过具体错误信息，你能直接定位是路径不存在、权限不足还是其他问题，比盲目排查高效多了。

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