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

# GCSFilesystem

將檔案儲存在 Google Cloud Storage。有關介面詳情，請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/gcs
```

**pnpm**:

```bash
pnpm add @mastra/gcs
```

**Yarn**:

```bash
yarn add @mastra/gcs
```

**Bun**:

```bash
bun add @mastra/gcs
```

## 用法

將 `GCSFilesystem` 加入 Workspace，並指派給 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

### 使用 Application Default Credentials

若在 Google Cloud 上運行，或已設定 `gcloud` CLI，便可省略憑證：

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})
```

[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) 會按以下次序自動尋找憑證：

1. `GOOGLE_APPLICATION_CREDENTIALS` 環境變數（服務帳戶 key 檔案的路徑）
2. 在 GCP（Compute Engine、Cloud Run、GKE 等）上運行時的預設服務帳戶
3. 來自 `gcloud auth application-default login` 的使用者憑證（用於本機開發）

### 使用 key 檔案路徑

你亦可傳入服務帳戶 key 檔案的路徑：

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})
```

## 建構函式參數

**bucket** (`string`): GCS bucket 名稱

**projectId** (`string`): GCS 項目 ID。使用服務帳戶憑證時必須提供。

**credentials** (`object | string`): 服務帳戶 key JSON 物件或 key 檔案路徑。若未提供，則使用 Application Default Credentials。

**prefix** (`string`): 所有 key 的選用前綴（作用類似子目錄）

**id** (`string`): 此檔案系統實例的唯一識別碼 (Default: `自動產生`)

**displayName** (`string`): 在 UI 中顯示、方便使用者理解的名稱

**icon** (`FilesystemIcon`): UI 的圖示識別碼

**description** (`string`): 此檔案系統在 UI 中顯示的簡短說明

**readOnly** (`boolean`): 若為 true，所有寫入操作都會遭到封鎖 (Default: `false`)

**endpoint** (`string`): 自訂 API endpoint URL。用於透過模擬器進行本機開發。

## 屬性

**id** (`string`): 檔案系統實例識別碼

**name** (`string`): Provider 名稱（'GCSFilesystem'）

**provider** (`string`): Provider 識別碼（'gcs'）

**bucket** (`string`): GCS bucket 名稱

**readOnly** (`boolean | undefined`): 檔案系統是否處於唯讀模式

## 方法

GCSFilesystem 實作 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)，並提供所有標準檔案系統方法：

- `readFile(path, options?)` - 讀取檔案內容
- `writeFile(path, content, options?)` - 將內容寫入檔案
- `appendFile(path, content)` - 將內容附加至檔案
- `deleteFile(path, options?)` - 刪除檔案
- `copyFile(src, dest, options?)` - 複製檔案
- `moveFile(src, dest, options?)` - 移動檔案或重新命名
- `mkdir(path, options?)` - 建立目錄
- `rmdir(path, options?)` - 移除目錄
- `readdir(path, options?)` - 列出目錄內容
- `exists(path)` - 檢查路徑是否存在
- `stat(path)` - 取得檔案或目錄的 metadata

### `init()`

初始化檔案系統。驗證 bucket 存取權及憑證。

```typescript
await filesystem.init()
```

### `getInfo()`

傳回此檔案系統實例的 metadata。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
```

### `getMountConfig()`

傳回掛載設定，供支援掛載此檔案系統類型的 Sandbox 使用。

```typescript
const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }
```

## 掛載至 E2B Sandbox

GCSFilesystem 可掛載至 E2B Sandbox，讓 bucket 能以本機目錄形式存取：

```typescript
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

有關掛載的更多詳情，請參閱 [E2BSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/e2b-sandbox)。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)
- [ArchilFilesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/archil-filesystem)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/s3-filesystem)
- [AzureBlobFilesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/azure-blob-filesystem)
- [E2BSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/e2b-sandbox)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)