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

# AzureBlobFilesystem

将文件存储在 Azure Blob Storage 容器中。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

## 安装

**npm**:

```bash
npm install @mastra/azure
```

**pnpm**:

```bash
pnpm add @mastra/azure
```

**Yarn**:

```bash
yarn add @mastra/azure
```

**Bun**:

```bash
bun add @mastra/azure
```

## 用法

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

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const workspace = new Workspace({
  filesystem: new AzureBlobFilesystem({
    container: 'my-container',
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  }),
})

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

### 账户密钥

如果不想传入完整连接字符串，请使用账户名称和账户密钥：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY,
})
```

### 共享访问签名令牌

将共享访问签名（SAS）令牌与 `accountName` 或 `endpoint` 搭配使用：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  sasToken: process.env.AZURE_STORAGE_SAS_TOKEN,
})
```

### DefaultAzureCredential

当环境提供 Azure 身份凭据时，请使用 `DefaultAzureCredential`：

```typescript
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  useDefaultCredential: true,
})
```

使用 `DefaultAzureCredential` 时，请安装 `@azure/identity`：

**npm**:

```bash
npm install @azure/identity
```

**pnpm**:

```bash
pnpm add @azure/identity
```

**Yarn**:

```bash
yarn add @azure/identity
```

**Bun**:

```bash
bun add @azure/identity
```

## 构造函数参数

**container** (`string`): Azure Blob Storage 容器名称

**connectionString** (`string`): 完整的 Azure Storage 连接字符串。优先级高于其他身份验证选项。

**accountName** (`string`): Azure Storage 账户名称。除非使用 connectionString 或 endpoint，否则必填。

**accountKey** (`string`): Azure Storage 账户密钥。

**sasToken** (`string`): 共享访问签名令牌。需要 accountName 或 endpoint。

**useDefaultCredential** (`boolean`): 使用 @azure/identity 中的 DefaultAzureCredential。 (Default: `false`)

**endpoint** (`string`): 自定义 Blob 服务 endpoint URL。用于通过 Azurite 进行本地开发。

**prefix** (`string`): 应用于所有键的可选前缀（作用类似子目录）。

**id** (`string`): 此文件系统实例的唯一标识符。 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称。

**icon** (`FilesystemIcon`): UI 中使用的图标标识符。

**description** (`string`): 在 UI 中显示的此文件系统的简短说明。

**readOnly** (`boolean`): 设为 true 时，所有写入操作都会被阻止。 (Default: `false`)

## 属性

**id** (`string`): 文件系统实例标识符。

**name** (`string`): Provider 名称（'AzureBlobFilesystem'）。

**provider** (`string`): Provider 标识符（'azure-blob'）。

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式。

## 方法

AzureBlobFilesystem 实现了 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/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()`

初始化文件系统。验证容器访问权限和凭据。

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

### `getInfo()`

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

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'AzureBlobFilesystem', provider: 'azure-blob', status: 'ready' }
```

### `getContainer()`

返回底层 Azure Blob Storage `ContainerClient`。

```typescript
const container = await filesystem.getContainer()
```

### `getMountConfig()`

返回支持 Azure Blob 文件系统挂载的 Sandbox Provider 所需的挂载配置。

```typescript
const config = filesystem.getMountConfig()
// { type: 'azure-blob', container: 'my-container', ... }
```

> **备注:** Azure Blob Sandbox 挂载依赖 Sandbox 对 `azure-blob` 挂载配置的支持。如果 Sandbox Provider 不支持 Azure Blob 挂载，请使用 `filesystem` 直接执行 Workspace 文件操作。

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [S3Filesystem 参考](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [GCSFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)