仅使用Cloud Functions时，如何升级FCM至API HTTP V1版本？

你不需要手动调用FCM HTTP V1的POST接口，Firebase Admin SDK已经完成了底层适配，只需要做以下几步就能完成迁移：

1. 升级Firebase Admin SDK到最新稳定版 #

旧版本的Admin SDK可能仍在调用已废弃的FCM Legacy API，执行以下命令升级：

npm install firebase-admin@latest --save

部署前确认package.json中firebase-admin的版本至少在11.0.0以上（该版本开始全面切换到HTTP V1）。

2. 调整Payload格式以适配V1规范 #

虽然sendToDevice方法名保持不变，但V1 API对payload的格式有更严格的要求：

• data字段的所有值必须是字符串类型，不能传入数字、布尔值或对象；
• 针对Android/iOS的自定义配置，建议放在android/apns字段下，而非直接嵌套在notification中；
• 移除Legacy API特有的参数（如priority字段的high/normal，V1改用android.priority或apns.headers.apns-priority）。

示例适配后的payload：

const payload = {
  notification: {
    title: '新帖子提醒',
    body: `${postData.author}发布了新内容`,
  },
  android: {
    notification: {
      channelId: 'post_updates', // 对应Android客户端的通知渠道ID
      priority: 'high'
    }
  },
  apns: {
    payload: {
      aps: {
        sound: 'default',
        badge: 1
      }
    },
    headers: {
      'apns-priority': '10'
    }
  },
  data: {
    postId: context.params.postId, // 必须是字符串
    authorId: postData.authorId.toString() // 数字转字符串
  }
};

3. 确认Cloud Functions服务账号权限 #

默认情况下，Cloud Functions使用的服务账号已拥有firebase.messaging.send权限，但如果自定义过角色或权限，需确保：

• 服务账号被授予Firebase Cloud Messaging Sender角色；
• 权限范围覆盖项目所有资源（或特定设备令牌）。

4. 处理失效令牌与错误 #

V1 API的错误返回更明确，建议在代码中处理常见失败场景：

const response = await admin.messaging().sendToDevice(tokens, payload);
// 收集失效令牌（过期、无效或未注册）
const invalidTokens = response.results
  .map((result, index) => ({ token: tokens[index], error: result.error }))
  .filter(item => item.error)
  .map(item => item.token);

// 可选：从数据库中移除失效令牌，避免重复发送
if (invalidTokens.length > 0) {
  // 示例：更新用户文档中的tokens数组
  await admin.firestore()
    .collection('users')
    .where('fcmTokens', 'array-contains-any', invalidTokens)
    .get()
    .then(snapshot => {
      snapshot.forEach(doc => {
        const updatedTokens = doc.data().fcmTokens.filter(t => !invalidTokens.includes(t));
        doc.ref.update({ fcmTokens: updatedTokens });
      });
    });
}

关键说明 #

admin.messaging().sendToDevice在新版SDK中是对HTTP V1 API的封装，底层会自动构造符合V1规范的请求，你无需手动处理HTTP请求头、认证等细节，保持原有调用逻辑即可。

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