> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# getFileSystemManager

获取文件系统管理器。

## 扫码预览

![扫码预览 getFileSystemManager](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Ffile-system%252Fget-file-system-manager%252Findex)

## 支持版本

前端库版本不低于 `0.0.31`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 接入准备

### 前置条件

- 无额外前置条件，直接调用 getFileSystemManager 获取管理器实例后再调用其方法

## 使用说明

- readFile、readFileSync 省略 encoding 时默认返回 Base64 字符串，writeFile、appendFile 省略 encoding 时默认按 UTF-8 写入；需要明确编码时请显式传入 encoding。

## 调用方式

### 同步 API

```typescript
getFileSystemManager(): FileSystemManager
```

## 入参

无。

## 调用示例

```typescript
import { getFileSystemManager } from '@doubao-dev/framework/api';

const fs = getFileSystemManager();
const { data } = await fs.readFile({
  filePath: '/tmp/profile.json',
  encoding: 'utf-8'
});

console.log(data);
```

## 返回值

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>access</code></td><td><code>(params: AccessParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>判断文件或目录是否存在（异步）。存在时 Promise 兑现，不存在时 Promise 拒绝。</td></tr>
<tr><td><code>accessSync</code></td><td><code>(params: AccessParams) =&gt; void</code></td><td>是</td><td>判断文件或目录是否存在（同步）。不存在时抛出异常。</td></tr>
<tr><td><code>appendFile</code></td><td><code>(params: AppendFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>在文件末尾追加内容（异步）。文件不存在则创建，不会覆盖已有内容。</td></tr>
<tr><td><code>appendFileSync</code></td><td><code>(params: AppendFileParams) =&gt; void</code></td><td>是</td><td>在文件末尾追加内容（同步）。文件不存在则创建，不会覆盖已有内容。</td></tr>
<tr><td><code>copyFile</code></td><td><code>(params: CopyFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>复制文件（异步）。仅支持文件，目标已存在同名文件时覆盖。</td></tr>
<tr><td><code>copyFileSync</code></td><td><code>(params: CopyFileParams) =&gt; void</code></td><td>是</td><td>复制文件（同步）。仅支持文件，目标已存在同名文件时覆盖。</td></tr>
<tr><td><code>getFileInfo</code></td><td><code>(params: GetFileInfoParams) =&gt; Promise&lt;GetFileInfoResult&gt;</code></td><td>是</td><td>获取文件信息（异步）；返回 GetFileInfoResult，含字节大小和可选的摘要。</td></tr>
<tr><td><code>getSavedFileList</code></td><td><code>() =&gt; Promise&lt;GetSavedFileListResult&gt;</code></td><td>是</td><td>获取已保存的本地文件列表（异步）；返回 GetSavedFileListResult，每项含路径、字节大小和毫秒级保存时间。</td></tr>
<tr><td><code>mkdir</code></td><td><code>(params: MkdirParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>创建目录（异步）。recursive 为 true 时一并创建缺失的上级目录。</td></tr>
<tr><td><code>mkdirSync</code></td><td><code>(params: MkdirParams) =&gt; void</code></td><td>是</td><td>创建目录（同步）。recursive 为 true 时一并创建缺失的上级目录。</td></tr>
<tr><td><code>readdir</code></td><td><code>(params: ReaddirParams) =&gt; Promise&lt;ReaddirResult&gt;</code></td><td>是</td><td>读取目录内容（异步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）。</td></tr>
<tr><td><code>readdirSync</code></td><td><code>(params: ReaddirParams) =&gt; ReaddirResult</code></td><td>是</td><td>读取目录内容（同步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）。</td></tr>
<tr><td><code>readFile</code></td><td><code>(params: ReadFileParams) =&gt; Promise&lt;ReadFileResult&gt;</code></td><td>是</td><td>读取文件内容（异步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。</td></tr>
<tr><td><code>readFileSync</code></td><td><code>(params: ReadFileParams) =&gt; ReadFileResult</code></td><td>是</td><td>读取文件内容（同步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。</td></tr>
<tr><td><code>removeSavedFile</code></td><td><code>(params: RemoveSavedFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除通过 saveFile 保存的本地文件（异步）。</td></tr>
<tr><td><code>rename</code></td><td><code>(params: RenameParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>重命名或移动文件（异步）。目标已存在同名文件时覆盖。</td></tr>
<tr><td><code>renameSync</code></td><td><code>(params: RenameParams) =&gt; void</code></td><td>是</td><td>重命名或移动文件（同步）。目标已存在同名文件时覆盖。</td></tr>
<tr><td><code>rmdir</code></td><td><code>(params: RmdirParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除目录（异步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容。</td></tr>
<tr><td><code>rmdirSync</code></td><td><code>(params: RmdirParams) =&gt; void</code></td><td>是</td><td>删除目录（同步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容。</td></tr>
<tr><td><code>saveFile</code></td><td><code>(params: SaveFileParams) =&gt; Promise&lt;SaveFileResult&gt;</code></td><td>是</td><td>将临时文件保存到本地持久化存储（异步）；返回 SaveFileResult，含实际保存路径。</td></tr>
<tr><td><code>saveFileSync</code></td><td><code>(params: SaveFileParams) =&gt; SaveFileResult</code></td><td>是</td><td>将临时文件保存到本地持久化存储（同步）；返回 SaveFileResult，含实际保存路径。</td></tr>
<tr><td><code>stat</code></td><td><code>(params: StatParams) =&gt; Promise&lt;StatResult&gt;</code></td><td>是</td><td>获取文件或目录状态（异步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录。</td></tr>
<tr><td><code>statSync</code></td><td><code>(params: StatParams) =&gt; StatResult</code></td><td>是</td><td>获取文件或目录状态（同步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录。</td></tr>
<tr><td><code>truncate</code></td><td><code>(params: TruncateParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>截断文件到指定长度（异步）。短于原长度时截断，长于原长度时以 \0 填充。</td></tr>
<tr><td><code>truncateSync</code></td><td><code>(params: TruncateParams) =&gt; void</code></td><td>是</td><td>截断文件到指定长度（同步）。短于原长度时截断，长于原长度时以 \0 填充。</td></tr>
<tr><td><code>unlink</code></td><td><code>(params: UnlinkParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除文件（异步）。只能删除文件，删除目录请使用 rmdir。</td></tr>
<tr><td><code>unlinkSync</code></td><td><code>(params: UnlinkParams) =&gt; void</code></td><td>是</td><td>删除文件（同步）。只能删除文件，删除目录请使用 rmdir。</td></tr>
<tr><td><code>unzip</code></td><td><code>(params: UnzipParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>解压 zip 文件到指定目录（异步）。目标目录须已存在。</td></tr>
<tr><td><code>writeFile</code></td><td><code>(params: WriteFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>写入文件内容（异步）。文件和父目录不存在则创建，文件已存在则覆盖。</td></tr>
<tr><td><code>writeFileSync</code></td><td><code>(params: WriteFileParams) =&gt; void</code></td><td>是</td><td>写入文件内容（同步）。文件和父目录不存在则创建，文件已存在则覆盖。</td></tr>
</tbody>
</table>

## 错误处理

同步调用失败时抛出错误。错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 203,
  "errMsg": "file does not exist"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>203</code></td><td><code>file does not exist</code></td><td>Android、iOS</td><td>readFile、stat、getFileInfo、copyFile、rename、truncate、unlink、rmdir、removeSavedFile、unzip 等操作的目标文件或目录不存在</td><td>确认路径存在或先创建后重试。</td></tr>
<tr><td><code>213</code></td><td><code>invalid file path</code></td><td>Android、iOS</td><td>传入的路径不是合法的沙箱内 appletfile 路径，或试图越过沙箱根目录访问</td><td>使用应用沙箱内的合法本地路径后重试。</td></tr>
<tr><td><code>208</code></td><td><code>total size limit exceeded</code></td><td>Android、iOS</td><td>readFile、writeFile、appendFile、copyFile 时单次读写超过单文件大小上限，或写入后超出沙箱存储配额</td><td>减小单次读写数据量或清理已保存文件后重试。</td></tr>
<tr><td><code>1901001</code></td><td><code>target is a directory</code></td><td>Android、iOS</td><td>对目录执行了仅适用于文件的操作（如 readFile、writeFile、appendFile、copyFile、truncate、getFileInfo、unzip 的源文件），或 rmdir 删除非空目录时未开启 recursive</td><td>改为对文件操作，或删除目录时开启 recursive。</td></tr>
<tr><td><code>1901002</code></td><td><code>target is not a directory</code></td><td>Android、iOS</td><td>对文件执行了仅适用于目录的操作（如 readdir），或 mkdir 目标已存在同名文件、unzip 的 targetPath 不是目录</td><td>确认目标为目录后重试。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android</td></tr>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>参数不合法</td><td>Android、iOS</td></tr>
</tbody>
</table>
