GCP Firestore环境下如何为服务账号授予storage.buckets.list权限

• Principal（身份主体）：所有可请求GCP资源的实体统称，不仅包含普通用户，还包括服务账号、用户组、GCP内部服务代理等，你报错中提到的<user>@<project>.iam.gserviceaccount.com就属于服务账号类型的Principal。
• 角色（Role）：是一组离散权限的打包集合，比如storage.buckets.list就是单条权限，GCP官方提供了大量预定义角色，无需手动逐条配置权限。
• IAM绑定：IAM的核心规则就是将「Principal、角色、作用资源（可细化到单个存储桶、项目级等）」三者绑定，完成授权。

你遇到的报错如下：

<user>@<project>.iam.gserviceaccount.com does not have storage.buckets.list access to the Google Cloud project

该报错是服务账号缺少项目级的存储桶列表权限导致的。Firestore Service Agent是GCP内部供Firestore服务自身调用其他资源的代理角色，无需你手动绑定给自定义服务账号。

1. 登录GCP控制台，进入「IAM与管理」→「IAM」页面，顶部项目选择器切换到你的Firestore对应项目。
2. 在主体列表中找到报错中的服务账号<user>@<project>.iam.gserviceaccount.com，点击右侧的铅笔图标进入编辑页面。
3. 点击「添加角色」，在角色搜索框输入存储即可找到官方预定义的存储相关角色：
   • 仅需满足列出存储桶需求：选择存储查看者（roles/storage.viewer）即可，该角色默认包含storage.buckets.list权限。
   • 后续需要对存储桶/存储对象做增删改操作：选择存储管理员（roles/storage.admin）。
4. 保存配置后等待1-2分钟权限生效，再重试操作即可。

如果搜索不到上述角色，可以按以下规则排查：

• 确认你当前登录GCP控制台的账号拥有该项目的Owner或IAM管理员权限，无IAM修改权限的账号无法看到完整的预定义角色列表。
• 确认你是在「添加角色」的弹窗搜索框中检索，角色管理页面默认仅展示自定义角色，需要切换到「预定义角色」标签页才能看到官方提供的存储类角色。

你提供的操作界面对应截图：

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