从Firebase迁移至Firestore后查询出现‘Unexpectedly found nil’致命错误

这种情况我之前迁移项目时也碰到过——明明打印document.data()看起来有数据，但实际取值时却触发nil崩溃，大概率是Firestore和旧Realtime Database的细节差异导致的，咱们一步步排查：

1. 先盯紧字段名的大小写和拼写 #

Firestore的字段名是严格大小写敏感的！旧的Realtime Database在某些场景下会自动兼容大小写差异，但Firestore完全不吃这一套。比如你旧代码里用的是"userName"，但Firestore控制台里存的是"username"，这时候document.data()?["userName"]就会返回nil，哪怕你打印整个data能看到"username"字段的内容。

解决小技巧：

• 直接从Firestore控制台复制字段名到代码里，避免手动拼写出错
• 打印所有字段名对比：print("所有字段：", document.data()?.keys)，和你代码里用的字段逐一核对

2. 检查数据类型是否匹配 #

Firestore的数据类型和Realtime Database有细微差别，类型不匹配时，哪怕字段存在，强制转换也会返回nil，触发崩溃：

• 数字类型：Realtime Database可能存为NSNumber，但Firestore会区分Int/Double，如果你用as! Int但实际是Double类型，直接崩
• 日期类型：Firestore用Timestamp，旧库可能存字符串或时间戳数字，直接转Date会失败

举个错误示例：

// 旧Realtime Database代码能正常运行，但Firestore里会崩溃
let age = document.data()!["age"] as! Int

改成安全的写法：

if let data = document.data(), let age = data["age"] as? Int {
    // 正常使用age
} else {
    print("要么没有数据，要么age字段类型不对")
}

日期处理要注意转换：

if let timestamp = data["createdAt"] as? Timestamp {
    let createDate = timestamp.dateValue()
}

3. 嵌套字段的读取方式别搞错 #

如果用户数据是嵌套结构（比如user.address.city），旧Realtime Database可以用路径直接读取，但Firestore需要逐层解析：

// 错误写法：直接用路径当键
let city = document.data()?["address/city"] as? String

// 正确写法：先取外层字典，再取内层字段
if let data = document.data(), 
   let address = data["address"] as? [String: Any], 
   let city = address["city"] as? String {
    // 使用city
}

4. 彻底抛弃强制解包！ #

你遇到的「Unexpectedly found nil」90%都是强制解包（!）导致的。哪怕你坚信数据一定存在，也要用可选绑定或空合运算符兜底：

// 不安全的写法：强制解包风险极高
let userName = document.data()!["userName"] as! String

// 安全写法：可选绑定+默认值
let userName = (document.data()?["userName"] as? String) ?? "匿名用户"

如果按上面的步骤排查后还是有问题，可以把打印的document.data()具体内容和你的读取代码贴出来，就能更快定位问题啦！

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