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

# GoogleDriveFilesystem

將檔案儲存在單一 Google Drive 資料夾中。每個目錄都會對應到已設定根目錄下的 Drive 資料夾，路徑則採用 POSIX 語意（例如 `/notes/todo.txt`）。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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 存取 Token。使用 `https://www.googleapis.com/auth/drive` scope，讓 Token 能查看與已驗證身分共用的資料夾。
- **`getAccessToken`**：傳回 Token 的回呼函式，適合在外部重新整理 Token 時使用。
- **`serviceAccount`**：Google 服務帳戶。請將目標資料夾與服務帳戶電子郵件地址共用。

#### 服務帳戶

對後端 Agent 而言，建議使用服務帳戶身分驗證。它不需要使用者同意流程，也不需要處理 Token 更新。你只需要服務帳戶 JSON 金鑰檔案中的**兩個值**：`client_email` 和 `private_key`。

##### 設定服務帳戶

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**，並完成表單。角色可以留空，因為 Drive 權限是透過共用資料夾授予，而不是透過 IAM 角色。
4. 開啟新的服務帳戶，前往 **Keys** 分頁，依序選取 **Add key > Create new key > JSON**。瀏覽器會下載 JSON 金鑰檔案。
5. 從 JSON 檔案複製 `client_email` 值。這就是與 Drive 資料夾共用時使用的地址。

##### 與服務帳戶共用 Drive 資料夾

服務帳戶具有獨立的 Google 身分。除非你明確與它共用，否則它無法查看 Drive 中的任何內容。

1. 在 [Google Drive](https://drive.google.com/) 中開啟目標資料夾。
2. 選取 **Share**。
3. 貼上服務帳戶的 `client_email` 地址。
4. 將角色設為 **Editor**（讀寫）或 **Viewer**（唯讀存取），然後選取 **Send**。
5. 從 URL 複製資料夾 ID。它是 `https://drive.google.com/drive/folders/<folderId>` 中 `/folders/` 後面的區段。

> **警告:** 服務帳戶無法在標準的「My Drive」資料夾中建立檔案。服務帳戶沒有個人 Drive 儲存空間配額，因此它建立的任何檔案都必須由具有配額的實體擁有。如果只共用個人 Drive 資料夾，讀取操作可以正常執行，但寫入操作會因配額錯誤而失敗。
>
> 若要提供寫入權限，請將資料夾放在**共用雲端硬碟**（舊稱 Team Drive）中，並將服務帳戶加入該共用雲端硬碟成為成員。共用雲端硬碟能提供服務帳戶建立檔案所需的儲存空間配額。
>
> 針對個人 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']`，這是服務帳戶查看與其共用資料夾所需的 scope。範圍較小的 `drive.file` scope 只能存取應用程式自行建立的檔案，因此與服務帳戶共用的資料夾會傳回 `404 Not Found`。

`GoogleDriveFilesystem` 會在簽署前自動正規化 `privateKey` 字串。它會移除前後引號，包括 JSON 包裝值中的逸出引號，並將字面值 `\n` 序列轉換為實際換行。它也會正規化 `\r\n` 行尾，並移除結尾逗號。無論 `.env` 載入器如何處理該值，金鑰都可正常運作。

##### 疑難排解

- **`404 File not found: <folderId>`**：服務帳戶沒有該資料夾的存取權。確認資料夾已與完全相符的 `client_email` 地址共用，且資料夾 ID 與 URL 相符。
- **寫入時發生 `storageQuotaExceeded`**：資料夾位於個人的「My Drive」中。請將資料夾移至共用雲端硬碟，並將服務帳戶加入成為成員。
- **`error:1E08010C:DECODER routines::unsupported`**：`privateKey` 值的格式不正確。確認該值包含完整 PEM 區塊，且換行已保留（可使用字面值 `\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 存取 Token。

**getAccessToken** (`() => string | Promise<string>`): 傳回新 OAuth 存取 Token 的回呼函式。每次需要授權的要求都會呼叫此函式。

**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): 透過 OAuth 2.0 JWT 流程簽發存取 Token 所使用的服務帳戶認證資訊。

**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/zh-TW/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?)` - 透過更換上層資料夾，在資料夾間移動檔案
- `mkdir(path, options?)` - 建立資料夾
- `rmdir(path, options?)` - 移除資料夾
- `readdir(path, options?)` - 列出資料夾內容（支援 `recursive` 和 `extension` 篩選）
- `stat(path)` - 傳回檔案或資料夾的 Drive 中繼資料
- `exists(path)` - 檢查檔案或資料夾是否存在

## 注意事項

- Google Drive 允許同一個資料夾中存在多個同名檔案。`GoogleDriveFilesystem` 會選取第一個相符項目來解析路徑，因此依賴路徑查詢時，請讓每個資料夾內的名稱保持唯一。
- 當 `recursive` 未設定（預設值）或設為 `true` 時，`writeFile` 會自動建立上層資料夾。設為 `recursive: false`，即可要求上層資料夾必須已存在。
- 系統會遵循 `WriteOptions` 上的 `expectedMtime`。當儲存的 `modifiedTime` 不同時，寫入會因 `StaleFileError` 而遭到拒絕，以支援樂觀並行控制。
- 此 Provider 僅透過內建 `fetch` 存取 Drive REST 端點（`https://www.googleapis.com/drive/v3` 和 `https://www.googleapis.com/upload/drive/v3`），不需要其他 dependency。