跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

Vercel Files

Stores files in any storage backend supported by FilesSDK: a unified abstraction over S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, the local filesystem, and more. For interface details, see WorkspaceFilesystem Interface.

Use FilesSDKFilesystem when you want a single adapter that can target multiple storage backends with the same code. Swap the underlying driver without changing the workspace setup. If you only target one backend and want first-class options for that backend, prefer the dedicated provider (for example S3Filesystem or GCSFilesystem).

Installation
Installation的直接链接

npm install @mastra/files-sdk files-sdk

files-sdk is a peer dependency you configure with the adapter you want to use.

Usage
Usage的直接链接

Create a Files instance from FilesSDK with the adapter of your choice, then pass it to FilesSDKFilesystem:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'

const files = new Files({
  adapter: s3({
    bucket: 'my-bucket',
    region: 'us-east-1',
  }),
})

const workspace = new Workspace({
  filesystem: new FilesSDKFilesystem({ files }),
})

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

Swapping adapters
Swapping adapters的直接链接

The same FilesSDKFilesystem works with any FilesSDK adapter. Replace the driver factory to switch backends:

import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'

// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })

// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })

// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })

// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })

See the FilesSDK documentation for the full adapter catalog and configuration options.

Read-only mounts
Read-only mounts的直接链接

const filesystem = new FilesSDKFilesystem({
  files,
  readOnly: true,
})

All write operations (writeFile, appendFile, deleteFile, copyFile, moveFile, mkdir, rmdir) throw WorkspaceReadOnlyError while reads succeed.

Constructor parameters
Constructor parameters的直接链接

files:

Files
A pre-configured FilesSDK Files instance bound to the adapter and credentials you want to use.

id?:

string
= Auto-generated
Unique identifier for this filesystem instance.

displayName?:

string
Human-friendly display name for the UI.

icon?:

FilesystemIcon
Icon identifier for the UI.

description?:

string
Short description of this filesystem for the UI.

readOnly?:

boolean
= false
When true, all write operations are blocked.

Properties
Properties的直接链接

id:

string
Filesystem instance identifier.

name:

string
Provider name ('FilesSDKFilesystem').

provider:

string
Provider identifier ('files-sdk').

readOnly:

boolean | undefined
Whether the filesystem is in read-only mode.

Methods
Methods的直接链接

FilesSDKFilesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

  • readFile(path, options?) - Read file contents
  • writeFile(path, content, options?) - Write content to a file
  • appendFile(path, content) - Append content to a file
  • deleteFile(path, options?) - Delete a file
  • copyFile(src, dest, options?) - Copy a file
  • moveFile(src, dest, options?) - Move or rename a file
  • mkdir(path, options?) - Create a directory (no-op for object stores)
  • rmdir(path, options?) - Remove a directory
  • readdir(path, options?) - List directory contents
  • exists(path) - Check if a path exists
  • stat(path) - Get file or directory metadata

init()
init的直接链接

Initialize the filesystem. Verifies that the configured adapter can list keys with the supplied credentials.

await filesystem.init()

getInfo()
getinfo的直接链接

Returns metadata about this filesystem instance.

const info = filesystem.getInfo()
// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }

files
files的直接链接

The underlying FilesSDK Files instance is exposed as a public property if you need to call adapter-specific APIs directly.

const url = await filesystem.files.url('reports/q3.pdf')

Object-store semantics
Object-store semantics的直接链接

FilesSDKFilesystem treats the configured backend as an object store, even when the underlying adapter is hierarchical (such as fs). This keeps behavior consistent across adapters:

  • mkdir is a no-op. Directories exist implicitly when keys with that prefix exist.
  • exists returns true only when an exact key is present as a file, or when the path is a prefix that contains at least one child key. Empty leftover directories on hierarchical adapters don't count.
  • deleteFile throws FileNotFoundError when the key doesn't exist, unless { force: true } is passed.
  • deleteFile on a directory delegates to rmdir({ recursive: true }), matching the S3Filesystem and GCSFilesystem behavior.
  • moveFile is implemented as copyFile followed by deleteFile. It isn't atomic. If the source delete fails after a successful copy, the destination remains and the source isn't removed.
  • appendFile is a read-modify-write operation. Concurrent appends to the same key may overwrite each other. This is inherent to object storage and not specific to FilesSDK.
  • readdir({ recursive: true }) emits intermediate directory entries (for example, a/b is emitted alongside a/b/c.txt).
On this page