本文详解 Firestore 安全规则单元测试中 @firebase/rules-unit-testing 与 firebase/firestore 模块的协同机制，澄清测试是否依赖模拟器、为何需引入现代 SDK，以及如何在规则测试中正确使用 or() 等高级查询功能。
本文详解 firestore 安全规则单元测试中 `@firebase/rules-unit-testing` 与 `firebase/firestore` 模块的协同机制，澄清测试是否依赖模拟器、为何需引入现代 sdk，以及如何在规则测试中正确使用 `or()` 等高级查询功能。
Firestore 安全规则的单元测试是保障数据访问安全的关键环节。官方推荐的 @firebase/rules-unit-testing 包并非独立运行的“黑盒”，而是一个基于本地 Firestore 模拟器（Emulator）的测试协调层——它本身不启动模拟器，但必须配合已运行的 firestore-emulator 才能执行真实规则校验。这意味着：你无法完全脱离模拟器进行规则测试；initializeTestEnvironment() 底层会通过 gRPC 连接本地模拟器实例（默认 localhost:8080），所有 getDoc、getDocs 等操作均触发实际规则评估，而非仅做语法模拟。
值得注意的是，该测试包的历史设计采用了 *`firebase/compat/兼容层**，以支持旧版 namespaced SDK（如firestore().collection(...)）的写法。这解释了为何文档中既出现testEnv.authenticatedContext(uid).firestore().collection(...)（兼容语法），又出现getDocs(collection(db, 'users'))（现代模块化语法）——二者可共存，但**语义不同**：前者返回一个“规则上下文封装的引用”，后者返回标准CollectionReference或Query，需配合firebase/firestore的函数（如getDocs,or,query`）才能构造符合规则引擎识别的请求。
因此，要启用 or() 查询等现代特性（Firestore 规则 v2+ 支持 || 逻辑运算符，但客户端必须发送合法的 OR 查询结构），必须显式导入并使用 firebase/firestore 模块：
import {
assertFails,
assertSucceeds,
initializeTestEnvironment
} from "@firebase/rules-unit-testing";
import {
collection,
doc,
getDoc,
getDocs,
or,
query,
where
} from "firebase/firestore";初始化环境时，传入项目 ID 和规则路径即可：
const testEnv = await initializeTestEnvironment({
projectId: "demo-project-1234",
firestore: {
rules: fs.readFileSync("firestore.rules", "utf8"),
},
});
const userAuthed = testEnv.authenticatedContext("user-abc");
const db = userAuthed.firestore(); // 返回兼容层封装的 db 实例，但可被现代函数消费此时，你可以自由组合现代查询 API 进行规则验证：
✅ 测试单文档读取（用户自有数据）：
const userDoc = doc(collection(db, "users"), "user-abc"); await assertSucceeds(getDoc(userDoc));
✅ 测试集合查询（无权限的公开集合）：
const publicCol = collection(db, "public_posts"); await assertFails(getDocs(publicCol));
✅ 测试含 or() 的复合查询（规则中需允许 || 条件）：
const messagesRef = collection(db, "messages");
const unreadOrMentioned = query(
messagesRef,
where("recipient", "==", "user-abc"),
or(
where("read", "==", false),
where("mentionedRecipient", "==", true)
)
);
await assertSucceeds(getDocs(unreadOrMentioned));⚠️ 关键注意事项：
- @firebase/rules-unit-testing 不提供 or()、query() 等函数，它们仅来自 firebase/firestore；
- assertSucceeds / assertFails 接收的是 Promise（如 getDocs(q)），务必 await 或 .then() 处理，否则测试可能提前通过；
- 规则文件中必须明确允许 OR 查询逻辑，例如：
match /messages/{id} { allow read: if request.auth != null && resource.data.recipient == request.auth.uid && (resource.data.read == false || resource.data.mentionedRecipient == true); } - 若使用 TypeScript，确保 @types/firebase 或 firebase/firestore 类型已正确安装，避免类型缺失报错。
总结：@firebase/rules-unit-testing 是规则测试的“指挥官”，而 firebase/firestore 是构建合规请求的“武器库”。抛弃“非此即彼”的二分思维，将二者按职责协同使用——用前者管理身份上下文与环境，用后者构造真实、现代、规则可解析的读写操作——才是高效、可靠、面向未来的 Firestore 安全测试实践。
