GCP中Cloud Function无法被Pub/Sub Topic触发的排查求助

1. 检查Pub/Sub订阅的推送权限配置 #

Pub/Sub要触发Cloud Function，需要Pub/Sub的服务主体拥有该函数的roles/cloudfunctions.invoker权限。生产环境中常遗漏这个配置：

• 确认Pub/Sub服务主体格式：service-<你的项目编号>@gcp-sa-pubsub.iam.gserviceaccount.com
• 检查该主体是否被添加到Cloud Function的权限列表中，权限类型为「Cloud Functions Invoker」
• 注意：部署函数时不会自动配置此权限，尤其是使用自定义服务账号部署的场景

2. 验证函数服务账号的必要权限 #

部署成功不代表运行时权限齐全：

• 函数的服务账号需要pubsub.subscriptions.consume权限（默认推送模式下Pub/Sub会自动确认消息，但部分自定义逻辑仍需此权限）
• 检查服务账号是否被授予roles/pubsub.subscriber角色，或对应细粒度权限

3. 核对订阅核心配置 #

• 确认订阅的推送端点是否正确指向生产环境Cloud Function的URL（避免和开发环境地址混淆）
• 检查订阅是否设置了消息过滤规则，规则过严会导致消息无法推送到函数
• 查看订阅的死信队列配置，若消息多次推送失败被转入死信队列，也会出现未确认消息增加但函数未触发的情况
• 确认订阅类型为PUSH（Cloud Function仅支持推送触发Pub/Sub消息）

4. 通过日志定位根因 #

• 查看Cloud Function日志：搜索是否有Pub/Sub推送的请求记录，若存在则排查函数执行时的错误（如初始化失败、代码异常）；若无则说明Pub/Sub未发起推送请求
• 查看Pub/Sub订阅日志：过滤「推送失败」相关日志，常见错误如403（权限不足）、404（端点不存在）、500（函数内部错误），这些都会直接导致消息无法触发函数

5. 排查环境差异 #

• 对比开发与生产环境的函数配置：包括内存分配、超时时间、环境变量（是否存在生产环境缺失的配置导致函数启动失败）
• 检查生产环境VPC配置：若函数部署在VPC内，确认防火墙规则允许Pub/Sub的IP段访问函数端点

内容的提问来源于stack exchange，提问作者Peter van Leeuwen