Firebase 初始化应避免明文密钥文件，推荐将 base64 编码的服务账号密钥存入环境变量 FIREBASE_AUTH_KEY；初始化需传入带超时（建议10秒）的 context；FCM Send() 仅表示入队而非送达，须检查 error 类型如 Unregistered；iOS 需显式设置 apns.Production；高并发下应异步发送并重试；主题推送必须用 SendToTopic() 且主题名仅支持字母、数字、下划线和连字符；本地调试优先用 beeep.Notify() 快速验证；上线前务必用有效 token 实测并检查 FCM 响应体。

用 firebase.google.com/go 初始化服务时，别直接读 JSON 文件

很多开发者一上来就写 option.WithCredentialsFile("serviceAccount.json")，本地跑得通，上线就报错——因为生产环境通常不允许挂载明文密钥文件。更安全也更通用的做法是把服务账号密钥 base64 编码后存进环境变量，运行时解码加载。

• FIREBASE_AUTH_KEY 必须是标准 base64（无换行、无空格），可用 base64 -w 0 serviceAccount.json 生成
• 解码失败常见于：环境变量未生效、base64 尾部多了 = 导致长度不对、或用了 URL-safe 变种编码
• 初始化必须传入有效的 context.Context，超时控制建议设为 10 秒，避免阻塞整个服务启动

发通知前先确认 fcmClient.Send() 的返回值不是“成功”而是“已入队”

FCM 的 Send() 方法只表示消息已提交到 Firebase 后端，并不保证设备收到。它返回的是一个 string（message ID）或 error，但即使返回 ID，也可能因 token 失效、设备离线、APNs 配置错误等被静默丢弃。

• 务必检查 error 是否为 messaging.Unregistered 或 messaging.InvalidArgument，这类错误需清理旧 token
• 对 iOS 设备，apns.Production 字段必须显式设为 true 或 false，默认值会导致沙箱/生产环境错配，无声失败
• 不要在 HTTP handler 中同步调用 Send() 并等待响应，高并发下容易拖垮服务；建议异步加重试（最多 2 次）+ 死信记录

主题订阅和设备组推送，别混用 SendAll() 和 Send()

向单个设备发通知用 Send()，向多个 token 发批量消息用 SendAll()，而向主题（如 "news"）推送必须用 SendToTopic() —— 这三者底层走的 FCM 接口完全不同，参数结构也不兼容。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• 误用 SendAll() 推送主题会报 InvalidArgument: mismatched topic name
• 主题名不能含大写字母、空格或特殊符号，只支持字母、数字、下划线和连字符，且长度 ≤ 100
• 设备订阅主题是客户端行为（Android/iOS SDK 调用），服务端无法主动“绑定”，只能发；取消订阅也需客户端配合

本地调试时，beeep.Notify() 是比 FCM 更快的验证路径

FCM 从服务端发到手机常有 2–10 秒延迟，且依赖网络、证书、token 状态，不适合快速验证逻辑是否跑通。桌面端用 beeep.Notify() 可以秒级弹窗，帮你聚焦业务流程而非推送通道。

立即学习“go语言免费学习笔记（深入）”；

• 安装只需 go get github.com/gen2brain/beeep，Windows/macOS/Linux 全支持
• 它不依赖任何后台服务，但注意 macOS 需手动开启“辅助功能”权限，否则静默失败
• 建议在开发阶段封装统一 Notifier 接口，FCM 实现用于生产，beeep 实现用于本地，切换只改一行注入

FCM 推送里最隐蔽的坑不是代码写错，而是服务账号权限不足、APNs 证书过期、或 Android 包名与 Firebase 项目配置不一致——这些错误不会在 Go 侧抛异常，只会让消息石沉大海。每次上线前，拿一个已知有效的 token 单独跑一次 Send() 并抓取 FCM 响应体，比看日志更直接。