跳到主要内容

GCSFilesystem

在 Google Cloud Storage 中存储文件。有关接口详情，请参阅 WorkspaceFilesystem 接口。

安装
安装的直接链接

npm install @mastra/gcs

用法
用法的直接链接

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

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
使用 Application Default Credentials的直接链接

如果在 Google Cloud 上运行，或已配置 gcloud CLI，可以省略凭据：

import { GCSFilesystem } from '@mastra/gcs'

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

Application Default Credentials（ADC）会按以下顺序自动发现凭据：

  1. GOOGLE_APPLICATION_CREDENTIALS 环境变量（指向服务账号密钥文件的路径）
  2. 在 GCP（Compute Engine、Cloud Run、GKE 等）上运行时使用的默认服务账号
  3. gcloud auth application-default login 提供的用户凭据（用于本地开发）

使用密钥文件路径
使用密钥文件路径的直接链接

也可以传入服务账号密钥文件的路径：

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
= 自动生成
此文件系统实例的唯一标识符

displayName?:

string
在 UI 中显示的易读名称

icon?:

FilesystemIcon
UI 的图标标识符

description?:

string
在 UI 中显示的此文件系统的简短描述

readOnly?:

boolean
= false
设为 true 时，阻止所有写入操作

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 接口，提供所有标准文件系统方法：

  • 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()
init的直接链接

初始化文件系统，并验证 bucket 访问权限和凭据。

await filesystem.init()

getInfo()
getinfo的直接链接

返回此文件系统实例的元数据。

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

getMountConfig()
getmountconfig的直接链接

返回挂载配置，供支持挂载此文件系统类型的 Sandbox 使用。

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

在 E2B Sandbox 中挂载
在 E2B Sandbox 中挂载的直接链接

GCSFilesystem 可以挂载到 E2B Sandbox 中，从而让 bucket 可作为本地目录访问：

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 参考。

On this page