FCM 发送 iOS 报 Invalid APNs credential 如何排查
结论: Invalid APNs credential 说明 FCM 后端用当前 Firebase 项目的 Apple 凭据向 APNs 鉴权时被拒绝,不是普通的 device token 失效。核对 key、Team ID、App ID 后,优先查三处:Admin SDK 实际使用的 Firebase 项目/服务账号与 iOS app 的 Firebase 项目是否一致;发送的 token 是否同一项目的 FCM registration token,有没有误用 APNs token;Firebase 项目里是否还留着旧 APNs 证书、重复 key,或 key 绑定关系有问题。FCM 对这个错误只返回通用文案。要拿到更多信息,最好直接通过 HTTP v1 调 FCM,再用同一个 .p8 直接请求 APNs,做一次隔离排查。
1. 先确认 Admin SDK 项目和 App 项目完全一致
这是最常见也最容易被忽略的问题。FCM token 是项目级资源:Admin SDK 的 service account 属于哪个项目,就会用哪个项目的 APNs 配置发送。
import firebase_admin
from firebase_admin import credentials
cred = credentials.Certificate('service-account.json')
app = firebase_admin.initialize_app(cred)
print(cred.project_id)
print(app.project_id)
把输出与 iOS 工程里的 GoogleService-Info.plist 对比:PROJECT_ID、GCM_SENDER_ID、GOOGLE_APP_ID 必须对应同一个 Firebase 项目。如果 Admin SDK 使用的是另一个项目的 service account,即使 APNs key 上传得完全正确,也会报 Invalid APNs credential。
另外确认 token 是在这个项目下拿到的 FCM token,而不是别的项目、别的 app 或 APNs token。
2. 确认 token 类型和 APNs token 状态
messaging.send() 的 token 参数必须是 FCM registration token,不是 APNs device token。APNs token 通常是 64 位十六进制字符串;FCM token 更长,形如 eX...:APA91b...。
如果是原生 iOS,确认 APNs token 已经交给 Firebase Messaging:
func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
Messaging.messaging().apnsToken = deviceToken
}
如果是 Flutter,在取 FCM token 前先确认 APNs token 不为空:
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken == null) {
throw Exception('APNs token is null');
}
final fcmToken = await FirebaseMessaging.instance.getToken();
如果 APNs token 为空,FCM 侧就无法建立 APNs 映射,后续发送容易出现凭据类错误。
3. 清理 Firebase 里的 APNs 配置
进入 Firebase Console → Project Settings → Cloud Messaging → Apple app configuration,重点检查:
- 不要同时保留旧 APNs certificate 和 APNs Authentication Key。使用 auth key 时,把旧的 Development/Production APNs Certificates 删掉,避免 FCM 命中旧证书或冲突配置。
- 只保留一个当前有效的 APNs Authentication Key,删除重复项。
- 检查 Key ID 和 Team ID 有没有填反。两者都是 10 位左右字符串,很容易看混。
- 确认 key 上传在正确的 Firebase 项目里,而不是同名或测试项目的控制台。
- 如果有多个 iOS app,确认当前 bundle ID 对应的 app 使用的 Team ID 与 key 的 Team ID 一致。
Spark 套餐本身不是原因,FCM 在 Spark 下可用。不要因为 Spark 去怀疑 APNs 凭据。
4. 检查 APNs 环境是否匹配
Debug/Xcode 直接安装通常走 sandbox;TestFlight、App Store 或 release 包走 production。APNs Authentication Key 本身可用于两边,但 APNs token 是分环境的。
用 FCM 发送时一般不需要手动指定环境,但如果你在直接测试 APNs,调试包要打 https://api.sandbox.push.apple.com,发布包要打 https://api.push.apple.com。环境用错常见结果是 BadDeviceToken,不是 Invalid APNs credential,但仍建议一起排除。
5. 获取更详细错误
先让 Admin SDK 异常把细节打出来:
from firebase_admin import messaging, exceptions
try:
messaging.send(message)
except exceptions.FirebaseError as e:
print(type(e).__name__)
print(getattr(e, 'code', None))
print(getattr(e, 'detail', None))
print(getattr(e, 'http_response', None))
如果还是只有一句通用错误,直接走 FCM HTTP v1,看返回 JSON 里的 error.details[].errorCode:
import requests
from google.oauth2 import service_account
from google.auth.transport.requests import Request
credentials = service_account.Credentials.from_service_account_file(
'service-account.json',
scopes=['https://www.googleapis.com/auth/firebase.messaging'],
)
credentials.refresh(Request())
access_token = credentials.token
url = 'https://fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send'
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json',
}
body = {
'message': {
'token': 'FCM_TOKEN',
'notification': {'title': 'test', 'body': 'test'},
'apns': {
'payload': {'aps': {'sound': 'default', 'badge': 1}}
},
}
}
r = requests.post(url, headers=headers, json=body)
print(r.status_code)
print(r.text)
如果返回里是 THIRD_PARTY_AUTH_ERROR,说明 FCM 仍然认为 APNs 鉴权失败。这个信息比 Admin SDK 的文案多一点,但还不足以定位是 key、项目还是环境。
6. 用同一个 .p8 直接打 APNs 做隔离
这是最有效的分界测试。用原生 app 日志里的 APNs device token,不要用 FCM token:
import time
import jwt
import httpx
key_id = 'KEY_ID'
team_id = 'TEAM_ID'
bundle_id = 'com.example.app'
apns_token = 'APNS_DEVICE_TOKEN' # 64 hex,不是 FCM token
private_key = open('AuthKey_XXXXXXXXXX.p8', 'rb').read()
token = jwt.encode(
{'iss': team_id, 'iat': int(time.time())},
private_key,
algorithm='ES256',
headers={'kid': key_id},
)
headers = {
'authorization': f'bearer {token}',
'apns-topic': bundle_id,
'apns-push-type': 'alert',
}
payload = {'aps': {'alert': {'title': 'test', 'body': 'test'}, 'sound': 'default'}}
# 调试包用 sandbox;发布包用 https://api.push.apple.com
with httpx.Client(http2=True) as client:
r = client.post(
f'https://api.sandbox.push.apple.com/3/device/{apns_token}',
headers=headers,
json=payload,
)
print(r.status_code)
print(r.text)
需要先安装依赖:
pip install 'httpx[http2]' pyjwt
结果判断:
- 返回 200:说明
.p8、Key ID、Team ID、bundle ID 和 APNs token 基本没问题,问题更可能在 FCM 项目映射、token 所属项目或 Firebase APNs 配置。 - 返回 403
InvalidProviderToken:重点查.p8是否对应这个 Key ID、Team ID 是否填错、key 是否被撤销、bundle ID 是否属于该 team。 - 返回 400
BadDeviceToken:APNs token 与环境不匹配,或 token 已失效。
7. 其他容易漏掉的点
可以补上 APNs headers,虽然它通常不会导致 Invalid APNs credential,但能避免 iOS 13+ 的推送类型问题:
apns=messaging.APNSConfig(
headers={
'apns-push-type': 'alert',
'apns-priority': '10',
},
payload=messaging.APNSPayload(aps=messaging.Aps(sound='default', badge=1))
)
还要确认 Cloud Messaging API 已启用、service account 具备发送 FCM 的权限。权限问题通常会返回 permission denied,而不是 Invalid APNs credential,但排查时可以顺手确认。
如果直接打 APNs 返回 200,而 FCM HTTP v1 仍然稳定返回 THIRD_PARTY_AUTH_ERROR,基本可以判定是 FCM 项目侧 APNs 凭据关联异常。此时建议保留这些信息再找 Firebase 支持:项目 ID、bundle ID、Team ID、Key ID、APNs token 环境、FCM HTTP v1 返回 JSON、直接 APNs 测试结果。FCM 不会把 APNs 的原始错误完整透出,所以直接 APNs 测试是最有价值的证据。
备注:内容仅供参考。
