JavaScript SDK：应用文件管理器

文件管理器位于 api.apps.files 上。每个方法都以应用 ID 作为第一个参数，然后是应用内部的路径。路径最多 256 个字符。示例使用创建客户端中的 api 客户端。appId 是你的某个应用的 ID：api.account.me() 会列出它们。

列出目录

files.list(appId, path?) 列出一个目录（省略 path 时为应用根目录）。

for (const entry of await api.apps.files.list(appId, "/src")) {
    console.log(entry.type, entry.name, entry.size, entry.lastModified);
}

字段	类型	说明
`name`	`string`	条目名称
`type`	`"file" \| "directory"`	条目类型
`size`	`number?`	大小（字节）。部分目录条目中不存在
`lastModified`	`number \| null?`	Unix 毫秒（可能带有小数部分）；无法读取时为 `null`

不存在的目录会返回 404 FILE_NOT_FOUND。文件管理器不公开的路径会返回 403 BLOCKED_PATH。

读取文件

files.read(appId, path) 以 Uint8Array 返回文件的字节。文件限制为 10 MB：更大的文件会返回 413 FILE_TOO_LARGE。

const bytes = await api.apps.files.read(appId, "/config.json");
const text = new TextDecoder().decode(bytes);

console.log(JSON.parse(text));

写入文件

files.write(appId, path, content, { signal }) 创建或覆盖一个文件。

string 以纯文本形式发送。
Uint8Array 以 base64 形式发送，因此任何二进制内容都能完整往返。
空内容（"" 或空字节）会创建一个空文件。

// Text
await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false }));

// Binary
const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer());
await api.apps.files.write(appId, "/assets/logo.png", image);

超过 10 MB 的内容会在发送任何内容之前于本地以 FILE_TOO_LARGE（状态 0）失败。超过 1 MiB 的内容会像上传一样在没有超时的情况下发送：传入 { signal } 即可取消。对于更大的文件，请使用 apps.commit()。

写入不会重启应用。调用 apps.restart() 以使更改生效。

移动或重命名文件

await api.apps.files.move(appId, "/config.json", "/config.old.json");

删除文件

await api.apps.files.delete(appId, "/config.old.json");

错误

状态	代码	触发条件
0	`FILE_TOO_LARGE`	`write` 的内容超过 10 MB（本地检查）
400	`INVALID_PATH`	路径未通过验证（路径穿越、无效字符、过长），或 `move` 到相同路径
400	`DELETE_FAILED`, `RENAME_FAILED`	集群无法删除或重命名该文件
403	`BLOCKED_PATH`	该路径未由文件管理器公开
403	`PERMISSION_DENIED`	你的 workspace 角色无法操作受限文件（例如 `.env`）
404	`FILE_NOT_FOUND`	文件或目录不存在
413	`FILE_TOO_LARGE`	`read` 超过 10 MB 的文件
429	`KEEP_CALM`	5 秒内写入超过 10 次

每个调用都可能返回的代码请参见错误。

后续步骤

环境变量

读取和修改应用的变量。

文件管理器 API 参考

这些方法背后的 REST 端点。

用 CLI 管理文件

在终端中完成同样的操作。

CLI

VS Code

SDKs

JavaScript SDK：应用文件管理器

列出目录

读取文件

写入文件

移动或重命名文件

删除文件

错误

后续步骤

环境变量

文件管理器 API 参考

用 CLI 管理文件

​列出目录

​读取文件

​写入文件

​移动或重命名文件

​删除文件

​错误

​后续步骤

环境变量

文件管理器 API 参考

用 CLI 管理文件

列出目录

读取文件

写入文件

移动或重命名文件

删除文件

错误

后续步骤