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

# GCSFilesystem

將檔案儲存在 Google Cloud Storage。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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` 環境變數（服務帳戶金鑰檔案的路徑）
2. 在 GCP 上執行時的預設服務帳戶（Compute Engine、Cloud Run、GKE 等）
3. 透過 `gcloud auth application-default login` 取得的使用者認證資訊（供本機開發使用）

### 使用金鑰檔案路徑

你也可以傳入服務帳戶金鑰檔案的路徑：

```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`): 服務帳戶金鑰 JSON 物件或金鑰檔案路徑。如未提供，則使用 Application Default Credentials。

**prefix** (`string`): 所有鍵可使用的選用前綴（作用如同子目錄）。

**id** (`string`): 此檔案系統執行個體的唯一識別碼 (Default: `Auto-generated`)

**displayName** (`string`): 在 UI 中顯示的易讀名稱

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

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

**readOnly** (`boolean`): 設為 true 時，會封鎖所有寫入操作 (Default: `false`)

**endpoint** (`string`): 自訂 API 端點 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-TW/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)` - 取得檔案或目錄的中繼資料

### `init()`

初始化檔案系統。確認 bucket 存取權與認證資訊。

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

### `getInfo()`

傳回此檔案系統執行個體的中繼資料。

```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-TW/reference/workspace/e2b-sandbox)。

## 相關內容

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