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

# S3Filesystem

將檔案儲存在 Amazon S3，或 Cloudflare R2、MinIO、DigitalOcean Spaces 與 Tigris 等 S3 相容儲存服務中。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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 package：

**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`（提供自訂 endpoint 時，預設值為 `true`）。請從 [Tigris 儀表板](https://console.tigris.dev/) 建立憑證。access key 的前綴為 `tid_`，secret 的前綴為 `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 access key ID。與 secretAccessKey 和 credentials 一併省略時，會使用 SDK 預設憑證 Provider 鏈。

**secretAccessKey** (`string`): AWS secret access key。與 accessKeyId 和 credentials 一併省略時，會使用 SDK 預設憑證 Provider 鏈。

**sessionToken** (`string`): 用於靜態暫時憑證的 AWS session token。僅在手動傳入完整暫時憑證集時，與 accessKeyId/secretAccessKey 一併使用。對於自動更新的 SSO、AssumeRole 或容器憑證，請使用 credentials Provider 參數或 SDK 預設憑證 Provider 鏈。

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

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

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

**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-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: '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-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)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-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)