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

# 迁移到 v5

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

## 要求

与 v4 相同：**Node.js 20.0.0** 或更新版本，同时支持 ESM 和 CJS。

## 破坏性变更概览

| v4.x                                                         | v5.x                                                            |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| `client.users.*`（已弃用的代理）                                     | 已移除。请使用 `client.user.*`                                         |
| `app.backup` / `app.backups`                                 | 已移除。请使用 `app.snapshots`                                         |
| `Backup` 导出                                                  | 已移除。请使用 `Snapshot` / `DatabaseSnapshot`                         |
| `api.applications.create(file)` 返回 `{ id, name, lang, ram }` | 返回 `{ id, name, ram, cpu, language, description?, subdomain? }` |
| `app.network.dns()` 返回 `{ ownership, ssl }`                  | 返回一个由 DNS 记录组成的数组                                               |

## `client.users` 被移除

与 v3 到 v4 的迁移不同，这次没有已弃用的代理。`client.users` 已不再存在，调用它会抛出异常。

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

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

## Backups 被移除

`app.backup` 和 `app.backups` 已被移除，`Backup` 导出也一并移除。对于应用和数据库，snapshot 是唯一受支持的方案。

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

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

对应用 snapshot 使用 `Snapshot` 类，对数据库 snapshot 使用 `DatabaseSnapshot` 类。

## `api.applications.create(file)` 返回结构

创建应用现在会返回更丰富的语言与资源数据，而不再是扁平的 `lang`/`ram` 组合。

```typescript theme={null}
// v4
const { id, name, lang, ram } = await api.applications.create(file);

// v5
const { id, name, ram, cpu, language, description, subdomain } =
    await api.applications.create(file);

// language is now an object, e.g. { name: "javascript", version: "22" }
// cpu is the allocated CPU shares (number)
// description and subdomain are only present when set in squarecloud.config
```

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

`dns()` 现在返回一个由 DNS 记录组成的数组，而不再是单一的 `{ ownership, ssl }` 对象。

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

// v5
const records = await app.network.dns();
// [{ type: "txt", name, value, status }, { type: "cname", name, value: "cname.squareweb.app", status }]
```

`txt` 记录同时涵盖所有权验证和 SSL 验证，`cname` 记录则是流量记录。`status` 反映验证状态（`pending`、`pending_validation`、`active` 等）。

## 其他变化

* `ApplicationLanguage` 现在包含 `ruby`，与 javascript、typescript、python、java、elixir、go、rust、php、dotnet 和 static 并列。
* 错误代码已标准化。新名称通过 `APIErrorCode` 导出；旧名称仍作为已弃用的类型别名保留。完整的重命名对照表参见[错误代码](/zh/sdks/js/client)。