GCS是对象存储而非数据库，PHP无法用mysqli或PDO连接；应使用google/cloud-storage SDK或spatie/flysystem-google-cloud-storage SDK通过REST API读写文件，需配置service account密钥及必要PHP扩展。
GCS 不是数据库，不能用 PHP “连接” —— 它是对象存储（Object Storage），没有 SQL 接口、不支持 SELECT 或 mysqli_connect()。你真正需要的是：用 PHP 读写 GCS 中的文件（如 JSON、CSV、日志、备份包），而不是“连数据库”。
为什么 mysqli 或 PDO 会失败
常见错误现象：SQLSTATE[HY000] [2002] Connection refused、Unknown MySQL server host 'storage.googleapis.com'、或直接超时 —— 因为 GCS 根本不监听 3306 端口，也不解析 SQL 协议。
- GCS 提供的是 HTTP/HTTPS REST API（XML 或 JSON 格式），不是 MySQL 协议
- 没有用户名/密码登录流程，只有 service account 密钥或 HMAC key 认证
- 不存在“数据库名”“表名”概念，只有
bucket和object path
PHP 正确对接 GCS 的两种主流方式
推荐按项目现状选择：
- 新项目或可升级依赖：用官方
google/cloud-storageSDK（基于 Guzzle + PSR-7） - 旧项目（Flysystem v1）、Laravel 8 及以下、或需统一本地/GCS/S3 接口：用
spatie/flysystem-google-cloud-storage
两者都要求你提前在 GCP 控制台创建 service account，下载 JSON 密钥，并设好权限（至少 roles/storage.objectAdmin）。
立即学习“PHP免费学习笔记（深入）”；
关键配置项（必须设置）：
-
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json（环境变量） - 确保 PHP 进程有该文件的读取权限（
chmod 600） - PHP 需启用
openssl、json、curl扩展
用 google/cloud-storage 上传一个文件（最小可行示例）
安装：composer require google/cloud-storage
<?php
putenv('GOOGLE_APPLICATION_CREDENTIALS=/var/www/gcs-key.json');
use Google\Cloud\Storage\StorageClient;
$storage = new StorageClient([
'projectId' => 'your-gcp-project-id'
]);
$bucket = $storage->bucket('your-bucket-name');
// 上传字符串内容
$bucket->upload('Hello GCS!', [
'name' => 'test.txt',
'predefinedAcl' => 'publicRead' // 如需公开访问
]);
// 或上传本地文件
$bucket->upload(fopen('/tmp/report.pdf', 'r'), [
'name' => 'reports/20260927.pdf'
]);
注意：predefinedAcl 默认是私有（private），不设就不会生成公开 URL；若要生成签名 URL，得调用 $object->signedUrl()，且需额外配置服务账号密钥和时间窗口。
用 Flysystem 统一操作（适合已有本地文件逻辑的项目）
安装：composer require spatie/flysystem-google-cloud-storage
<?php
putenv('GOOGLE_APPLICATION_CREDENTIALS=/var/www/gcs-key.json');
use League\Flysystem\Filesystem;
use Spatie\FlysystemGoogleCloudStorage\GoogleCloudStorageAdapter;
use Google\Cloud\Storage\StorageClient;
$storageClient = new StorageClient(['projectId' => 'your-gcp-project-id']);
$adapter = new GoogleCloudStorageAdapter($storageClient, 'your-bucket-name', 'optional-prefix/');
$filesystem = new Filesystem($adapter);
// 和本地操作一样
$filesystem->write('notes/hello.txt', 'world');
$contents = $filesystem->read('notes/hello.txt');
$filesystem->delete('notes/hello.txt');
重点：Flysystem 不暴露底层认证细节，所有方法签名与本地适配器一致，迁移成本极低 —— 但无法直接调用 GCS 特有功能（如对象版本控制、生命周期策略），这些得绕过 Flysystem 直接调用 StorageClient。
最容易被忽略的一点：GCS 没有“目录”，folder/subfolder/file.txt 只是对象名里的斜杠；listObjects 用 prefix 模拟目录，但不会自动创建中间路径。别指望 $filesystem->createDir('logs/2026/09') 产生真实层级 —— 它什么也不会做。
