> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# GoogleDriveFilesystem

将文件存储在单个 Google Drive 文件夹中。每个目录都会映射到已配置根目录下的一个 Drive 文件夹，路径遵循 POSIX 语义（例如 `/notes/todo.txt`）。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

## 安装

**npm**:

```bash
npm install @mastra/google-drive
```

**pnpm**:

```bash
pnpm add @mastra/google-drive
```

**Yarn**:

```bash
yarn add @mastra/google-drive
```

**Bun**:

```bash
bun add @mastra/google-drive
```

## 用法

将 `GoogleDriveFilesystem` 添加到 Workspace，并将其分配给 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const workspace = new Workspace({
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
  }),
})

const agent = new Agent({
  id: 'drive-agent',
  name: 'Drive Agent',
  model: 'openai/gpt-5-mini',
  workspace,
})
```

### 身份验证

请提供以下身份验证选项之一：

- **`accessToken`**：预先获取的 OAuth access token。请使用 `https://www.googleapis.com/auth/drive` scope，以便令牌能够查看与已验证身份共享的文件夹。
- **`getAccessToken`**：返回令牌的回调。适用于在外部刷新令牌的情况。
- **`serviceAccount`**：Google service account。请与该 service account 的电子邮件地址共享目标文件夹。

#### Service account

对于后端 Agent，推荐使用 service account 身份验证。它不需要用户授权流程，也不需要处理令牌刷新。你只需从 service account JSON 密钥文件中获取**两个值**：`client_email` 和 `private_key`。

##### 设置 service account

1. 打开 [Google Cloud Console](https://console.cloud.google.com/)，选择或创建一个项目。
2. 前往 **APIs & Services > Library**，搜索 **Google Drive API**，然后选择 **Enable**。
3. 前往 **APIs & Services > Credentials**，选择 **Create credentials > Service account** 并填写表单。role 可以留空：Drive 权限通过共享文件夹授予，而非通过 IAM role 授予。
4. 打开新建的 service account，前往 **Keys** 标签页，然后选择 **Add key > Create new key > JSON**。浏览器会下载一个 JSON 密钥文件。
5. 从 JSON 文件中复制 `client_email` 值。该地址就是共享 Drive 文件夹时要使用的地址。

##### 与 service account 共享 Drive 文件夹

Service account 本身是一个独立的 Google 身份。在你显式与其共享内容之前，它无法看到 Drive 中的任何内容。

1. 在 [Google Drive](https://drive.google.com/) 中打开目标文件夹。
2. 选择 **Share**。
3. 粘贴 service account 的 `client_email` 地址。
4. 将 role 设置为 **Editor**（读写）或 **Viewer**（只读）。选择 **Send**。
5. 从 URL 中复制文件夹 ID。在 `https://drive.google.com/drive/folders/<folderId>` 中，它是 `/folders/` 之后的部分。

> **注意:** Service account 无法在标准的“My Drive”文件夹中创建文件。Service account 没有个人 Drive 存储配额，因此它创建的所有文件都必须由具备配额的实体拥有。如果只共享个人 Drive 文件夹，读取操作可以正常执行，但写入会因配额错误而失败。
>
> 如需写入权限，请将文件夹放到**共享云端硬盘**（以前称为 Team Drive）中，并将 service account 添加为该共享云端硬盘的成员。共享云端硬盘会为 service account 创建的文件提供所需存储配额。
>
> 对于个人 Drive 文件夹的只读工作负载不受此限制。

##### 配置文件系统

将 JSON 文件中的 `client_email` 和 `private_key` 复制到环境变量中：

```bash
GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"
```

```typescript
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const filesystem = new GoogleDriveFilesystem({
  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
  serviceAccount: {
    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
  },
})
```

你**不需要**复制整个 JSON 文件，也不需要传入 `project_id`、`client_id`、`private_key_id` 或 `token_uri` 等其他字段。这些字段不会被使用。只有 `clientEmail` 和 `privateKey` 是必需的。`privateKeyId`、`scopes` 和 `subject` 为可选项。`scopes` 默认为 `['https://www.googleapis.com/auth/drive']`，这是 service account 查看与其共享的文件夹时所需的 scope。权限更窄的 `drive.file` scope 只能访问应用自身创建的文件，因此与 service account 共享的文件夹会返回 `404 Not Found`。

`GoogleDriveFilesystem` 在签名前会自动规范化 `privateKey` 字符串。它会移除两侧引号（包括 JSON 包装值中的转义引号），并将字面量 `\n` 序列转换为真正的换行符。它还会规范化 `\r\n` 行尾并移除末尾逗号。无论 `.env` 加载器如何处理该值，密钥都能正常使用。

##### 故障排除

- **`404 File not found: <folderId>`**：service account 无权访问该文件夹。确认已与准确的 `client_email` 地址共享文件夹，并且文件夹 ID 与 URL 匹配。
- **写入时出现 `storageQuotaExceeded`**：文件夹位于个人“My Drive”中。将文件夹移动到共享云端硬盘，并将 service account 添加为成员。
- **`error:1E08010C:DECODER routines::unsupported`**：`privateKey` 值格式错误。确认该值包含完整 PEM block，且换行符得以保留（使用字面量 `\n` 也可以）。

### 只读模式

传入 `readOnly: true` 可阻止写入操作（`writeFile`、`appendFile`、`deleteFile`、`copyFile`、`moveFile`、`mkdir`、`rmdir`）。

```typescript
const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})
```

## 构造函数参数

**folderId** (`string`): 用作 Workspace 根目录的 Google Drive 文件夹 ID。所有路径都会在此文件夹内解析。

**accessToken** (`string`): 可访问该文件夹的 OAuth access token。

**getAccessToken** (`() => string | Promise<string>`): 返回新 OAuth access token 的回调。每个需要授权的请求都会调用它。

**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): 通过 OAuth 2.0 JWT 流程签发 access token 的 service account 凭据。

**id** (`string`): 此文件系统实例的唯一标识符 (Default: `` `google-drive:${folderId}` ``)

**readOnly** (`boolean`): 设为 true 时，所有写入操作都会被阻止。 (Default: `false`)

**instructions** (`InstructionsOption`): 覆盖返回给 Tool 描述的默认指令。

## 属性

**id** (`string`): 文件系统实例标识符

**name** (`string`): Provider 名称（'GoogleDriveFilesystem'）

**provider** (`string`): Provider 标识符（'google-drive'）

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式

## 方法

GoogleDriveFilesystem 实现了 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)，提供所有标准文件系统方法：

- `readFile(path, options?)` - 下载文件内容
- `writeFile(path, content, options?)` - 上传或覆盖文件
- `appendFile(path, content)` - 读取并重新上传文件，从而追加内容
- `deleteFile(path, options?)` - 删除文件
- `copyFile(src, dest, options?)` - 使用 Drive `files.copy` API 复制文件
- `moveFile(src, dest, options?)` - 通过更换 parent 在文件夹之间移动文件
- `mkdir(path, options?)` - 创建文件夹
- `rmdir(path, options?)` - 删除文件夹
- `readdir(path, options?)` - 列出文件夹内容（支持 `recursive` 和 `extension` 筛选）
- `stat(path)` - 返回文件或文件夹的 Drive 元数据
- `exists(path)` - 检查文件或文件夹是否存在

## 注意事项

- Google Drive 允许一个文件夹中存在多个同名文件。`GoogleDriveFilesystem` 解析路径时会选择第一个匹配项，因此依赖基于路径的查找时，请确保每个文件夹内的名称唯一。
- 未设置 `recursive`（默认）或将其设为 `true` 时，`writeFile` 会自动创建 parent 文件夹。设置 `recursive: false` 可要求 parent 文件夹必须已经存在。
- 支持 `WriteOptions` 中的 `expectedMtime`。当存储的 `modifiedTime` 不同时，写入会被拒绝并抛出 `StaleFileError`，以支持乐观并发控制。
- 该 Provider 仅通过内置 `fetch` 调用 Drive REST endpoint（`https://www.googleapis.com/drive/v3` 和 `https://www.googleapis.com/upload/drive/v3`），无需额外依赖。