本文涵盖的最新补丁版本:v4.0.1(发布于 2026-05-30)。
要求
- Node.js 20.0.0 或更新版本(v3 支持 Node 18)
破坏性变更概览
重命名
client.users → client.user
api.users 仍作为一个已弃用的 getter 导出,代理到 api.user,但它会在运行时打印一条警告。
Backups → Snapshots
Backup 导出现在是 Snapshot 的一个已弃用别名。
Application
Application.custom
当未绑定自定义域名时,app.custom 现在为 null(在 v3 中为 undefined)。
app.commit(file, fileName, restart)
第三个 restart 参数已被移除。在 commit 之后手动重启:
app.files.create(content, path)
签名现在是 create(content, fileName, path = "/")。迁移方式:
Deploys
app.deploys.list() 结构
Deployment.id
现在是一个纯粹的提交 SHA-1(40 位十六进制字符),而不是 `git-…` 格式的字符串。
Network
app.network.dns()
app.network.analytics()
app.network.purgeCache()
Workspaces
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的错误处理使用

