在使用Firebase进行应用开发时，部分开发者会碰到数据字段名被自动添加下划线前缀的情况，这种异常会直接导致前后端字段匹配出现偏差，影响业务逻辑的正常运转。
问题出现的常见场景
该问题多发生在使用Firebase SDK进行数据读写操作时，比如将本地对象存储到Firestore，或者从Realtime Database读取数据映射为本地实体类的时候。原本定义的字段名userName，实际存储或者读取后变成了_userName，给后续的数据处理带来麻烦。
核心诱因分析
- 序列化框架默认规则：如果项目中使用了Gson、Jackson等序列化工具，并且配置了字段名转换策略，可能会自动给字段名添加下划线前缀。
- Firebase SDK的注解配置错误：使用了错误的注解标记字段，导致SDK在序列化时自动修改字段名格式。
- Kotlin或Java的字段可见性设置：部分可见性修饰符会让SDK默认在字段名前添加下划线，避免和内部字段冲突。
对应解决方案
方案一：调整序列化工具配置
如果使用Gson进行序列化，需要检查是否设置了FieldNamingPolicy，若配置了带下划线前缀的策略，可修改为默认策略：
// 错误配置示例，会导致字段名添加下划线前缀
Gson gson = new GsonBuilder()
.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE_WITH_UNDERSCORES)
.create();
// 正确配置，使用默认字段名规则
Gson gson = new GsonBuilder()
.setFieldNamingPolicy(FieldNamingPolicy.IDENTITY)
.create();
方案二：正确使用Firebase注解
如果是Firestore的实体类，使用@PropertyName注解明确指定字段名，避免SDK自动修改：
import com.google.firebase.firestore.PropertyName;
public class User {
// 明确指定存储的字段名，避免自动添加前缀
@PropertyName("userName")
private String userName;
public User() {}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
}
方案三：调整Kotlin/Java字段可见性
如果是Kotlin开发的实体类，避免使用private修饰符搭配默认的getter/setter，可改为使用var声明字段，或者添加@JvmField注解：
import com.google.firebase.firestore.JvmField
import com.google.firebase.firestore.PropertyName
data class User(
// 添加JvmField注解避免序列化时添加前缀
@JvmField
@PropertyName("userName")
var userName: String = ""
)
验证修复效果
修改配置后，可以编写简单的读写测试代码验证字段名是否恢复正常：
FirebaseFirestore db = FirebaseFirestore.getInstance();
User user = new User();
user.setUserName("testUser");
// 写入数据
db.collection("users").document("testDoc").set(user).addOnSuccessListener(aVoid -> {
// 读取数据验证字段名
db.collection("users").document("testDoc").get().addOnSuccessListener(documentSnapshot -> {
User result = documentSnapshot.toObject(User.class);
System.out.println(result.getUserName()); // 输出testUser，字段名无下划线前缀即修复成功
});
});
按照上述步骤排查和调整后，Firebase字段名自动添加下划线前缀的问题通常都能得到解决，开发者可以根据自己项目的技术栈选择对应的方案实施。