> ## 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.

# 迁移到 v4

> @squarecloud/api v3 和 v4 之间的变化 —— 破坏性变更、重命名以及升级所需的最小改动。

<Info>
  本文涵盖的最新补丁版本：**v4.0.1**（发布于 2026-05-30）。
</Info>

## 要求

* **Node.js 20.0.0** 或更新版本（v3 支持 Node 18）

## 破坏性变更概览

| v3.x                                         | v4.x                                                            |
| -------------------------------------------- | --------------------------------------------------------------- |
| `client.users.*`                             | `client.user.*`                                                 |
| `app.backup` / `app.backups`                 | `app.snapshots`                                                 |
| `Backup` 导出                                  | `Snapshot` 导出                                                   |
| `app.deploys.list()` 返回扁平的 `Deployment[]`    | 返回 `Deployment[][]`（调用 `.flat()` 得到旧结构）                         |
| `Deployment.id` 格式化为 `` `git-${string}` ``   | 纯粹的提交 SHA-1（40 位十六进制字符）                                         |
| `app.network.dns()` 返回一个数组                   | 返回 `{ ownership, ssl }`                                         |
| `app.network.analytics()` 不接受参数              | 要求 `{ start, end }`（ISO 字符串或 `Date`）                            |
| `app.network.purgeCache(paths?)`             | `purgeCache()` —— 参数在 **v4.0.1** 中被移除，始终清除整个缓存                  |
| `app.custom === undefined`                   | `app.custom === null`                                           |
| `workspace.members` / `.applications` 持有数据数组 | 重命名为 `workspace.memberList` / `.applicationList`；原来的名称现在是**模块** |
| `app.commit(file, name, restart)`            | `app.commit(file, name)` —— 移除了第三个参数                            |
| `app.files.create(content, fullPath)`        | `app.files.create(content, fileName, path)`                     |

## 重命名

### `client.users` → `client.user`

```typescript theme={null}
// v3
await api.users.get();

// v4
await api.user.get();
```

`api.users` 仍作为一个已弃用的 getter 导出，代理到 `api.user`，但它会在运行时打印一条警告。

### Backups → Snapshots

```typescript theme={null}
// v3
await app.backups.create();
await app.backup.list();

// v4
await app.snapshots.create();
await app.snapshots.list();
```

`Backup` 导出现在是 `Snapshot` 的一个已弃用别名。

## Application

### `Application.custom`

当未绑定自定义域名时，`app.custom` 现在为 `null`（在 v3 中为 `undefined`）。

### `app.commit(file, fileName, restart)`

第三个 `restart` 参数已被移除。在 commit 之后手动重启：

```typescript theme={null}
// v3
await app.commit(buffer, "index.js", true);

// v4
await app.commit(buffer, "index.js");
await app.restart();
```

### `app.files.create(content, path)`

签名现在是 `create(content, fileName, path = "/")`。迁移方式：

```typescript theme={null}
// v3 — single combined path
await app.files.create(content, "./folder/test_file.txt");

// v4 — separate file name and directory
await app.files.create(content, "test_file.txt", "/folder");
```

## Deploys

### `app.deploys.list()` 结构

```typescript theme={null}
// v3
const events: Deployment[] = await app.deploys.list();

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // same shape as v3
```

### `Deployment.id`

现在是一个纯粹的提交 SHA-1（40 位十六进制字符），而不是 `` `git-…` `` 格式的字符串。

## Network

### `app.network.dns()`

```typescript theme={null}
// v3
const records: DnsRecord[] = await app.network.dns();

// v4
const { ownership, ssl } = await app.network.dns();
```

### `app.network.analytics()`

```typescript theme={null}
// v3
const data = await app.network.analytics();

// v4 — { start, end } is now required (ISO string or Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});
```

### `app.network.purgeCache()`

```typescript theme={null}
// v3 and v4.0.0
await app.network.purgeCache(["/static/old.js"]);

// v4.0.1 and later — selective purge removed
await app.network.purgeCache();
```

## Workspaces

```typescript theme={null}
// v3
workspace.members;      // raw member data
workspace.applications; // raw application data

// v4
workspace.memberList;        // raw member data
workspace.applicationList;   // raw application data
workspace.members.add(...);  // members module
workspace.applications.add(...); // applications module
```

## v4 的新功能

除了上述的重命名和签名变更，v4 还新增了大量功能：

* **Databases** —— 完整的生命周期、凭据、snapshot 和指标（[Databases](/zh/sdks/js/databases)）
* **Workspaces** —— 通过邀请码和角色进行团队协作（[Workspaces](/zh/sdks/js/workspaces)）
* **Environment variables** —— 列出 / 设置 / 替换 / 删除（[Environment variables](/zh/sdks/js/environment_variables)）
* **Application metrics** —— 24 小时的 CPU/RAM/网络采样（[Managing applications](/zh/sdks/js/managing_application)）
* **Real-time SSE stream** —— `app.realtime()`（[Realtime](/zh/sdks/js/realtime)）
* **Edge analytics** —— 分析、错误、日志和延迟百分位数（[Network](/zh/sdks/js/network)）
* **GitHub App integration** —— `app.deploys.linkGithubApp({ ... })`（[Deploys](/zh/sdks/js/deploys)）
* **Snapshot restore** —— `app.snapshots.restore({ snapshotId, versionId })` 和 `db.snapshots.restore(snapshotId, versionId)`
* **Status-all endpoints** —— `api.applications.statusAll()`、`api.databases.statusAll()`
* **Service status** —— `api.service.status()`
* **User scoped snapshots** —— `api.user.snapshots(scope)`
* **New User fields** —— `User.locale`、`User.createdAt`、`User.databases`
* **New BaseApplication fields** —— `domain`、`custom`、`createdAt`
* **`SquareCloudAPIError.code`** —— 公开供基于 `switch` 的错误处理使用