跳转到主要内容
一个面向 Laravel 的 Google Sheets API v4 扩展包。它屏蔽了 Google PHP 客户端库的复杂性，提供了直观且富有表现力的方法链 API。

​
特性

  • 支持多种认证方式 —— OAuth 2.0（面向单个用户的访问）、Service Account（服务器间通信）、API key（公开数据）
  • 流畅的 API —— 通过方法链直观地操作数据
  • 与 Laravel Collection 集成 —— 将 Google Sheets 的数据转换为 Laravel Collection，方便进行数组处理
  • 可扩展 —— 通过 macro 系统可以为 facade 添加自定义方法
  • 与 Google Drive 集成 —— 支持电子表格的管理与列表查询

​
常见使用场景

  • 用户仪表盘 —— 展示与操作 Google Sheets 中的数据
  • 数据导入 / 导出 —— 在 Laravel 应用与 Google Sheets 之间迁移大量数据
  • 自动生成报表 —— 通过程序生成和更新报表
  • 多用户应用 —— 让用户各自管理自己的 Google Sheets

​
设计理念

本包的主要目的是 从 Google Sheets 读取数据。它并不鼓励在读取前指定复杂条件，而是先将全部数据取回作为 Laravel Collection，然后在 Laravel 一侧进行后续处理。

​
系统要求

  • PHP >= 8.3
  • Laravel >= 12.0

​
安装

1

用 Composer 安装

composer require revolution/laravel-google-sheets
2

发布配置文件

php artisan vendor:publish --tag="google-config"
3

启用 Google API

在 Google Cloud Console 中启用以下 API：
  • Google Sheets API
  • Google Drive API
4

选择并配置认证方式

从下列三种方式中选择：
  • Service Account —— 面向服务器间通信 / 自动化任务
  • OAuth 2.0 —— 面向单个用户的访问
  • API key —— 仅公开数据

​
认证方式对比

方式用途用户操作访问范围难度
Service Account服务器间通信 / 自动化不需要已共享的电子表格中
OAuth 2.0面向用户的应用需要同意用户各自的表格高
API key仅公开数据不需要只能访问公开电子表格低

​
基本用法

以下面的电子表格结构为例。
idnamemail
1name1mail1
2name2mail2
电子表格 URL: https://docs.google.com/spreadsheets/d/{spreadsheetID}/... 请从 URL 中取出 spreadsheetId。

​
使用 Service Account

使用 Service Account 认证时，不需要额外设置 token。 
use Revolution\Google\Sheets\Facades\Sheets;

// Service Account 认证会在初始化时自动完成
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]

​
使用 OAuth

使用 OAuth 认证时，需要设置用户的 access token。 
use Revolution\Google\Sheets\Facades\Sheets;

$user = $request->user();

$token = [
    'access_token'  => $user->access_token,
    'refresh_token' => $user->refresh_token,
    'expires_in'    => $user->expires_in,
    'created'       => $user->updated_at->getTimestamp(),
];

// all() 返回数组
$values = Sheets::setAccessToken($token)->spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name1', 'mail2']
// ]

​
用表头作为 key 获取数据（推荐）

Collection 的转换比较方便，后续处理也更灵活，因此推荐这种方式。 
use Revolution\Google\Sheets\Facades\Sheets;

// get() 返回 Laravel Collection
$rows = Sheets::sheet('Sheet 1')->get();

$header = $rows->pull(0);
$values = Sheets::collection(header: $header, rows: $rows);
$values->toArray()
// [
//   ['id' => '1', 'name' => 'name1', 'mail' => 'mail1'],
//   ['id' => '2', 'name' => 'name2', 'mail' => 'mail2']
// ]
Blade 
@foreach($values as $value)
  {{ data_get($value, 'name') }}
@endforeach

​
使用 A1 表示法

use Revolution\Google\Sheets\Facades\Sheets;

$values = Sheets::sheet('Sheet 1')->range('A1:B2')->all();
// [
//   ['id', 'name'],
//   ['1', 'name1'],
// ]

​
关于 A1 表示法

A1 表示法是 Google 电子表格中指定单元格或范围的标准方式（例如 “A1”、“A1:B2”）。
  • “A1” 指的是 A 列第 1 行的单元格。
  • “A1:B2” 指的是从 A1 到 B2 的矩形范围。
  • “A:B” 指的是 A 列和 B 列的全部行。
如果你对 A1 表示法不太熟悉，或者范围是动态的、比较复杂，通常先获取全部数据、再在 Laravel 中通过 Collection 处理/过滤，会更简单。

​
后续步骤

​
在线演示

你可以通过 Laravel Google Sheets Demo 查看实际运行效果。
最后修改于 2026年7月13日

相关主题

Google Sheets API for Laravel