GCP存储桶UI可访问但Cloud Shell用gcsfuse挂载缺失目标目录

常见原因 #

• IAM权限不足：当前Cloud Shell关联的账号对目标目录缺少storage.objects.list权限，gcsfuse会静默过滤无权限的对象，不会抛出权限错误
• 空模拟目录：GCS不存在原生目录结构，仅通过对象路径前缀模拟目录，若目标目录下没有任何有效对象，gcsfuse默认不会展示这类空目录
• 挂载参数配置问题：gcsfuse默认关闭隐式目录推断（--implicit-dirs=false），仅展示明确创建的目录对象，不会根据文件路径自动生成上层目录
• 路径包含特殊字符：目标目录的路径包含非UTF-8编码字符、不可见控制字符，gcsfuse无法正常识别并展示
• 对象被软删除/归档：存储桶开启软删除、对象版本控制或归档存储策略时，目标目录关联的对象被标记删除或进入归档层，默认挂载时不会展示

排查操作步骤 #

1. 验证基础权限
   直接使用gsutil命令访问目标路径，确认是否有权限读取：
   gsutil ls gs://<存储桶名称>/<目标目录路径>/
   如果返回403错误，直接在GCP IAM控制台给当前Cloud Shell账号授予覆盖目标路径的Storage Object Viewer权限即可。

2. 确认目录是否为空
   如果上一步命令返回空结果，说明目标目录下无有效对象，可先上传一个测试文件到该路径：
   touch test.txt && gsutil cp test.txt gs://<存储桶名称>/<目标目录路径>/
   再刷新挂载目录查看是否能展示目标目录。

3. 带隐式目录参数重新挂载
   先卸载原有挂载点：
   fusermount -u <本地挂载路径>
   加上--implicit-dirs参数重新挂载：
   gcsfuse --implicit-dirs <存储桶名称> <本地挂载路径>
   该参数会强制gcsfuse根据所有对象的路径前缀自动推断层级目录结构，无需目录对象单独存在即可展示。

4. 检查路径特殊字符
   执行以下命令查看目标路径前缀的所有对象，确认是否存在特殊字符：
   gsutil ls -b gs://<存储桶名称>/<目标目录前缀>*
   如果路径包含异常字符，重命名对应对象路径后重新验证即可。

5. 验证对象状态
   如果存储桶开启了版本控制或软删除，执行命令查看已标记删除的对象：
   gsutil ls -a gs://<存储桶名称>/<目标目录路径>/
   如果确认目标目录关联对象被删除，恢复对应对象即可正常展示。

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