> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理文件

> 通过 FilesModule 在应用内浏览、读取、创建、移动和删除文件。

本页的每个方法都位于 `app.files` 上：

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");
app.files; // FilesModule
```

## 列出目录中的文件

`app.files.list(path?)` 返回一个目录的条目。路径默认为 `"/"`。

```typescript theme={null}
const entries = await app.files.list("/");
console.log(entries);
// [
//   { type: "file",      name: "index.js", size: 123, lastModified: 1717084800000 },
//   { type: "directory", name: "src",      size: 0,   lastModified: 1717084800000 },
// ]
```

## 读取文件

`app.files.read(path)` 返回一个包含文件内容的 Node.js `Buffer`，当文件不存在时返回 `undefined`。

```typescript theme={null}
const buffer = await app.files.read("/index.js");
console.log(buffer?.toString("utf8"));
```

## 创建或覆盖文件

`app.files.create(file, fileName, path?)` 在 `path/fileName` 处写入一个文件。路径默认为 `"/"`。

| 参数         | 类型                 | 描述                          |
| ---------- | ------------------ | --------------------------- |
| `file`     | `string \| Buffer` | 本地文件路径或原始 `Buffer` 内容       |
| `fileName` | `string`           | 带扩展名的文件名（例如 `"version.ts"`） |
| `path`     | `string`           | 应用内的绝对目录路径（默认 `"/"`）        |

<Tabs>
  <Tab title="来自 Buffer">
    ```typescript theme={null}
    const content = Buffer.from("export default 1\n");
    await app.files.create(content, "version.ts", "/src");
    ```
  </Tab>

  <Tab title="来自本地路径">
    ```typescript theme={null}
    import { join } from "node:path";

    const localPath = join(__dirname, "version.ts");
    await app.files.create(localPath, "version.ts", "/src");
    ```
  </Tab>
</Tabs>

<Warning>
  签名在 v4 中发生了变化。之前的版本接受 `create(content, fullPath)` —— v4 要求 `create(content, fileName, path)`。
</Warning>

## 移动或重命名文件

`app.files.move(path, newPath)` 移动或重命名文件或目录。

```typescript theme={null}
await app.files.move("/version.ts", "/src/version.ts");
```

## 删除文件或目录

`app.files.delete(path)` 删除一个文件或整个目录。

```typescript theme={null}
await app.files.delete("/src/version.ts");
```