跳转到主要内容
本文涵盖的最新补丁版本：v4.0.1（发布于 2026-05-30）。

​
要求

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

​
破坏性变更概览

v3.xv4.x
client.users.*client.user.*
app.backup / app.backupsapp.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 === undefinedapp.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

// v3
await api.users.get();

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

​
Backups → Snapshots

// 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 之后手动重启： 
// 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 = "/")。迁移方式： 
// 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() 结构

// 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()

// v3
const records: DnsRecord[] = await app.network.dns();

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

​
app.network.analytics()

// 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()

// 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

// 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）
  • Workspaces —— 通过邀请码和角色进行团队协作（Workspaces）
  • Environment variables —— 列出 / 设置 / 替换 / 删除（Environment variables）
  • Application metrics —— 24 小时的 CPU/RAM/网络采样（Managing applications）
  • Real-time SSE stream —— app.realtime()（Realtime）
  • Edge analytics —— 分析、错误、日志和延迟百分位数（Network）
  • GitHub App integration —— app.deploys.linkGithubApp({ ... })（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 的错误处理使用