Firestore规则提示users未定义但实际存在的权限问题排查

问题描述 #

在Firebase模拟器中使用onSnapshot读取集合时，遭遇permission-denied错误，规则校验报错提示：

Property users is undefined on object. for 'list' @ L9, Property users is undefined on object. for 'list' @ L14

当前Firestore规则如下：

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {


    // Rules for specific collections
    match /users/{userId}/organizations/{docId} {
      allow read: if request.auth != null && resource.data.users != null && (request.auth.token.email in resource.data.users);
      allow write: if false;
    }

    match /{document=**} {
      allow read: if (request.auth != null) && resource.data.users != null && (request.auth.token.email in resource.data.users);
      allow write: if false;
    }
  }
}

触发错误的前端代码：

snapshot => {
  let items = <any>[];
  snapshot.forEach(doc => {
    console.log('docData')
    console.log(doc.data())
    items.push(doc.data())
  })
  debugItems.value = items
},

注：将规则改为allow read: if true;时，可正常获取所有包含users字段的文档。

问题根源 #

Firestore的集合查询（list操作）会对匹配规则路径下的所有文档执行权限校验，只要其中任意一个文档不存在users字段，就会触发Property users is undefined的错误，进而导致整个查询被拒绝。

具体可能的原因：

• 模拟器中存在无users字段的测试文档（通配规则/{document=**}会匹配所有文档，包括你未关注的其他路径下的文档）；
• 查询路径匹配到了/{document=**}规则，该路径下存在不符合要求的文档；
• 部分目标文档的users字段被误删除或未正确初始化。

解决方案 #

1. 缩小规则匹配范围
   移除或修改/{document=**}的通配规则，仅针对需要的集合设置权限，避免无关文档触发校验错误。比如只保留/users/{userId}/organizations/{docId}的规则，确保查询仅匹配该路径。

2. 清理模拟器数据
   打开Firestore模拟器控制台，检查所有文档：

   • 删除无users字段的文档；
   • 为缺失users字段的文档补充该字段（即使是空数组）。

3. 增强规则健壮性
   在规则中明确判断users字段是否存在，再进行后续校验：

   allow read: if request.auth != null && 'users' in resource.data && (request.auth.token.email in resource.data.users);
   

4. 定位问题文档
   使用Firebase控制台的规则模拟器，模拟list操作并输入对应auth信息（含email的token），查看具体是哪个文档触发了权限校验失败，精准定位问题。

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