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

# GCSFilesystem

在 Google Cloud Storage 中存储文件。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/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`): 所有 key 的可选前缀（作用类似于子目录）

**id** (`string`): 此文件系统实例的唯一标识符 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称

**icon** (`FilesystemIcon`): UI 的图标标识符

**description** (`string`): 在 UI 中显示的此文件系统的简短描述

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

**endpoint** (`string`): 自定义 API endpoint URL。用于通过 emulator 进行本地开发。

## 属性

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

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

**provider** (`string`): Provider 标识符（'gcs'）

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

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

## 方法

GCSFilesystem 实现了 [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?)` - 复制文件
- `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/reference/workspace/e2b-sandbox)。

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [ArchilFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/archil-filesystem)
- [S3Filesystem 参考](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [AzureBlobFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)
- [E2BSandbox 参考](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)