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

# FilesSDKFilesystem

將檔案儲存在 [FilesSDK](https://files-sdk.dev) 支援的任何儲存後端。FilesSDK 為 S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、本機檔案系統等提供統一的抽象層。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)。

若想以相同程式碼透過單一 Adapter 使用多種儲存後端，請使用 `FilesSDKFilesystem`。你可以更換底層驅動程式，而不必變更 Workspace 設定。如果只使用一種後端，且需要該後端的完整設定選項，建議使用專用 Provider（例如 [`S3Filesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem) 或 [`GCSFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)）。

## 安裝

**npm**:

```bash
npm install @mastra/files-sdk files-sdk
```

**pnpm**:

```bash
pnpm add @mastra/files-sdk files-sdk
```

**Yarn**:

```bash
yarn add @mastra/files-sdk files-sdk
```

**Bun**:

```bash
bun add @mastra/files-sdk files-sdk
```

`files-sdk` 是 peer dependency，你需要為它設定要使用的 Adapter。

## 使用方式

使用你選擇的 Adapter 建立 FilesSDK `Files` 執行個體，再將它傳給 `FilesSDKFilesystem`：

```typescript
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,
})
```

### 更換 Adapter

同一個 `FilesSDKFilesystem` 可搭配任何 FilesSDK Adapter 使用。只要替換驅動程式工廠函式，即可切換後端：

```typescript
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' }) })
```

如需完整的 Adapter 清單與設定選項，請參閱 [FilesSDK 文件](https://files-sdk.dev)。

### 唯讀掛載

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

所有寫入操作（`writeFile`、`appendFile`、`deleteFile`、`copyFile`、`moveFile`、`mkdir`、`rmdir`）都會擲回 `WorkspaceReadOnlyError`，讀取操作則可正常執行。

## 建構函式參數

**files** (`Files`): 已預先設定並繫結至所需 Adapter 與認證資訊的 FilesSDK Files 執行個體。

**id** (`string`): 此檔案系統執行個體的唯一識別碼。 (Default: `Auto-generated`)

**displayName** (`string`): 在 UI 中顯示的易讀名稱。

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

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

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

## 屬性

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

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

**provider** (`string`): Provider 識別碼（'files-sdk'）。

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

## 方法

`FilesSDKFilesystem` 實作 [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()`

初始化檔案系統。確認已設定的 Adapter 能使用所提供的認證資訊列出鍵。

```typescript
await filesystem.init()
```

### `getInfo()`

傳回此檔案系統執行個體的中繼資料。

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

### `files`

底層 FilesSDK `Files` 執行個體會公開為屬性，供你直接呼叫 Adapter 專用 API。

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

## 物件儲存語意

`FilesSDKFilesystem` 會將已設定的後端視為物件儲存，即使底層 Adapter 採用階層式結構（例如 `fs`）也是如此。這可讓各 Adapter 的行為保持一致：

- **`mkdir`** 不執行任何操作。只要存在具有該前綴的鍵，就會隱含存在對應目錄。
- **`exists`** 只有在完全相符的鍵以檔案形式存在，或該路徑是包含至少一個子鍵的前綴時，才會傳回 `true`。階層式 Adapter 上殘留的空目錄不算在內。
- **`deleteFile`** 會在鍵不存在時擲回 `FileNotFoundError`，除非傳入 `{ force: true }`。
- 對目錄呼叫 **`deleteFile`** 時，會委派給 `rmdir({ recursive: true })`，其行為與 [`S3Filesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem) 和 [`GCSFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem) 一致。
- **`moveFile`** 的實作方式是先執行 `copyFile`，再執行 `deleteFile`。此操作不是**原子操作**。如果複製成功後刪除來源失敗，目的地會保留，來源也不會被移除。
- **`appendFile`** 是讀取、修改再寫入的操作。同時將內容附加至同一個鍵時，可能會彼此覆寫。這是物件儲存的固有限制，並非 FilesSDK 特有。
- **`readdir({ recursive: true })`** 會產生中間目錄項目（例如除了 `a/b/c.txt`，也會產生 `a/b`）。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/azure-blob-filesystem)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)
- [FilesSDK 文件](https://files-sdk.dev)