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

# S3Filesystem

將檔案儲存於 Amazon S3，或 Cloudflare R2、MinIO、DigitalOcean Spaces 及 Tigris 等 S3 相容儲存服務。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/s3
```

**pnpm**:

```bash
pnpm add @mastra/s3
```

**Yarn**:

```bash
yarn add @mastra/s3
```

**Bun**:

```bash
bun add @mastra/s3
```

## 使用方法

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

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
})

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

### AWS 憑證 Provider 鏈

如果未有提供憑證，`S3Filesystem` 會使用 AWS SDK 的預設憑證 Provider 鏈。它會自動從環境變數、`~/.aws` 設定檔、ECS 容器憑證、EC2 執行個體設定檔，以及其他標準來源探索憑證。

```typescript
import { S3Filesystem } from '@mastra/s3'

// SDK discovers credentials from the environment automatically
const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
})
```

傳入憑證 Provider 函式，以自動重新整理憑證。這適用於 ECS、Lambda 上的部署，或使用 SSO/AssumeRole 而臨時憑證會過期並需要重新整理的情況。

直接呼叫 `fromNodeProviderChain()` 時，請安裝 AWS SDK 憑證 Provider 套件：

**npm**:

```bash
npm install @aws-sdk/credential-providers
```

**pnpm**:

```bash
pnpm add @aws-sdk/credential-providers
```

**Yarn**:

```bash
yarn add @aws-sdk/credential-providers
```

**Bun**:

```bash
bun add @aws-sdk/credential-providers
```

```typescript
import { S3Filesystem } from '@mastra/s3'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: fromNodeProviderChain(),
})
```

Provider 函式只適用於 `S3Filesystem` API 呼叫。將檔案系統掛載至 E2B Sandbox 時，掛載設定只支援靜態 `accessKeyId`、`secretAccessKey` 及 `sessionToken` 值，因此必須在掛載以外處理憑證重新整理。

### Cloudflare R2

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-r2-bucket',
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
})
```

### MinIO

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
})
```

### Tigris

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
  forcePathStyle: false,
})
```

Tigris 使用虛擬主機樣式定址，因此必須將 `forcePathStyle` 設為 `false`（提供自訂端點時，預設值為 `true`）。請在 [Tigris Dashboard](https://console.tigris.dev/) 建立憑證。存取金鑰以 `tid_` 為前綴，而秘密金鑰則以 `tsec_` 為前綴。

## 建構函式參數

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

**region** (`string`): AWS 區域（R2 請使用 'auto'）

**credentials** (`AwsCredentialIdentity | AwsCredentialIdentityProvider`): AWS 憑證或憑證 Provider 函式。接受靜態憑證，或會自動重新整理憑證的 Provider（例如來自 @aws-sdk/credential-providers 的 fromNodeProviderChain()）。其優先順序高於 accessKeyId/secretAccessKey/sessionToken。如省略所有憑證選項，便會使用 SDK 的預設憑證 Provider 鏈。

**accessKeyId** (`string`): AWS 存取金鑰 ID。如連同 secretAccessKey 及 credentials 一併省略，便會使用 SDK 的預設憑證 Provider 鏈。

**secretAccessKey** (`string`): AWS 秘密存取金鑰。如連同 accessKeyId 及 credentials 一併省略，便會使用 SDK 的預設憑證 Provider 鏈。

**sessionToken** (`string`): 靜態臨時憑證所用的 AWS session token。只有在手動傳入一套完整臨時憑證時，才應與 accessKeyId/secretAccessKey 一併使用。如要自動重新整理 SSO、AssumeRole 或容器憑證，請使用 credentials Provider 參數，或 SDK 的預設憑證 Provider 鏈。

**endpoint** (`string`): S3 相容儲存空間（R2、MinIO、Tigris 等）的自訂端點 URL

**forcePathStyle** (`boolean`): 強制使用路徑樣式 URL，而非虛擬主機樣式。MinIO 等部分 S3 相容服務需要此設定。提供自訂端點時，預設為 true。 (Default: `true（設定 endpoint 時）`)

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

**id** (`string`): 此檔案系統執行個體的唯一識別碼 (Default: `自動產生`)

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

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

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

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

## 屬性

**id** (`string`): 檔案系統執行個體識別碼

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

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

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

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

## 方法

S3Filesystem 實作 [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: 'S3Filesystem', provider: 's3', status: 'ready' }
```

### `getMountConfig()`

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

```typescript
const config = filesystem.getMountConfig()
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
```

## 掛載至 E2B Sandbox

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

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_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)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/gcs-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)