使用Unreal Engine蓝图将数据写入Firebase Firestore的最佳方案

前置准备 #

• 首先安装官方Firebase UE4 SDK，选择和你UE4版本完全匹配的SDK包，导入项目后启用Firebase Core、Firebase Firestore两个插件，重启编辑器生效
• 完成Firebase控制台的项目配置：将UE4项目的包名填入Firebase控制台，下载google-services.json（安卓）/GoogleService-Info.plist（iOS）放到项目对应平台配置目录，桌面端的话直接将配置文件放到项目Binaries对应架构目录下
• 首次运行时先调用Firebase初始化节点，确认初始化成功后再执行后续Firestore操作，避免空引用报错

蓝图写入数据核心实现步骤 #

步骤1：获取Firestore实例 #

• 打开你需要实现写入逻辑的蓝图（比如GameInstance、PlayerController或者自定义的存储管理类蓝图）
• 初始化Firebase完成后，调用Get Firestore Instance节点，拿到当前项目对应的Firestore实例引用，存储为变量备用

步骤2：构造要写入的文档数据 #

Firestore的文档为键值对结构，UE蓝图中用Firestore Document Data类型构造数据：

• 调用Create Firestore Document Data节点，根据你要存储的字段类型调用对应的Set Field节点：
  • 字符串类型字段：调用Set String Field，输入字段名和对应字符串值
  • 数字类型字段：调用Set Integer Field/Set Double Field，输入字段名和对应数值
  • 布尔类型字段：调用Set Boolean Field，输入字段名和布尔值
  • 数组/嵌套对象可以对应调用Set Array Field/Set Map Field实现

注意：字段名不要用特殊字符、空格或者Firestore保留关键字，避免写入失败

步骤3：执行写入操作 #

Firestore写入分两种常用场景，分别对应不同的节点：

场景1：写入到指定集合的自定义ID文档

• 调用Firestore实例的Collection节点，输入你要写入的集合名（比如user_scores）
• 调用返回的Collection引用的Document节点，输入你要指定的文档ID（比如用户的唯一UID）
• 调用Document引用的Set Data节点，将之前构造好的Firestore Document Data传入，选择是否合并已有数据（Merge参数设为true则仅覆盖传入的字段，不删除文档原有其他字段，设为false则完全覆盖整个文档）
• 绑定Set Data节点的成功/失败回调：成功回调可以加你的后续业务逻辑，失败回调可以读取Error Code和Error Message排查问题（比如权限不足、网络不通等）

场景2：写入到指定集合，自动生成文档ID

• 前面的Collection节点调用后，直接调用Collection引用的Add Document节点，传入构造好的文档数据即可，Firestore会自动生成唯一的文档ID，成功回调中可以拿到生成的文档ID存储到本地备用

步骤4：测试验证 #

• 打包测试或者在编辑器内运行，触发写入逻辑后，打开Firebase控制台的Firestore页面，刷新后即可看到写入的文档数据
• 如果写入失败，优先检查：Firebase初始化是否成功、安全规则是否允许当前用户写入对应集合、网络是否能正常访问Firebase服务

常见问题优化 #

• 高频写入的场景建议做写入队列，避免短时间内大量请求触发Firebase限流，每次写入失败后可以加指数退避重试逻辑，不要立即重复请求
• 敏感数据不要直接明文写入，写入前先做加密处理
• 不需要实时同步的场景可以开启Firestore的本地缓存，离线时写入的内容会在网络恢复后自动同步，不需要额外写离线处理逻辑

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