JavaScript SDK：快速上手与客户端

本页记录的是 @squarecloud/api v6，这是 SDK 的一次重写。正从 v5 升级？请阅读 v5 → v6 迁移指南。

要求

Node.js 22 或更新版本、Deno、Bun 或边缘运行时。SDK 只需要 fetch、FormData、Blob 和 Web Streams。
一个 API 密钥（参见 API 密钥与作用域）。

该包同时提供 ESM 和 CommonJS 构建，没有运行时依赖，并自带 TypeScript 类型：你不再需要 @squarecloud/api-types。

安装

npm
pnpm
yarn
bun
deno

npm install @squarecloud/api

pnpm add @squarecloud/api

yarn add @squarecloud/api

bun add @squarecloud/api

deno add npm:@squarecloud/api

API 密钥与作用域

在 squarecloud.app/account/security 创建密钥。SDK 会将其原样放入 Authorization 请求头发送（不带 Bearer 前缀）。密钥可以限制为特定的作用域（apps:read、apps:deploy、apps:control、ai:chat……）以及特定的应用或数据库：

超出这些限制的调用会抛出 SquareCloudAPIError，状态为 403，代码为 MISSING_SCOPE 或 RESOURCE_NOT_ALLOWED。
列表方法（account.me()、apps.statusAll()……）只返回该密钥可见的资源。
未知、已撤销或已过期的密钥会返回 401 ACCESS_DENIED。

请将密钥保存在服务器端。SDK 也可以在浏览器中运行，但这会将密钥暴露给每一位访问者。

示例从环境变量 SQUARECLOUD_API_KEY 读取密钥。请在运行示例的终端中设置它：

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

创建客户端

TypeScript / ESM
CommonJS

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!);

const { user, applications } = await api.account.me();
console.log(`Hi ${user.name}, you have ${applications.length} apps`);

const { SquareCloudAPI } = require("@squarecloud/api");

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);

第一个示例会打印你的账户名称，以及该密钥可以看到的应用数量：

Hi Jane, you have 3 apps

空密钥或仅含空白字符的密钥会在构造函数中抛出 TypeError，早于任何请求。

选项

import { BASE_URL, SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!, {
    baseUrl: BASE_URL, // "https://api.squarecloud.app/v2" (default)
    timeoutMs: 30_000,
    maxRetries: 2,
    userAgent: "my-bot/1.0",
    fetch, // any fetch-compatible function (proxy, tracing, tests)
});

选项	默认值	说明
`baseUrl`	`https://api.squarecloud.app/v2`	API 基础 URL。末尾的 `/` 会被去除。也以 `BASE_URL` 导出。
`timeoutMs`	`30000`	每次尝试的超时，覆盖整个响应。参见超时。
`maxRetries`	`2`	仅针对安全失败的重试次数（最多 3 次尝试）。负值视为 `0`。参见重试。
`userAgent`	`squarecloud-sdk-js/<version>`	替换整个 `User-Agent` 请求头。
`fetch`	全局 `fetch`	用于代理、追踪或测试的自定义 `fetch`。

API 密钥以普通属性的形式存储在客户端对象上。不要对客户端使用 console.log 或将其序列化。

模块

属性	涵盖内容	页面
`api.account`	`me()`、`snapshots({ scope })`	账户和 Snapshots
`api.service`	`status()`	平台状态
`api.apps`	获取、删除、状态、生命周期、日志、指标、域名、负载均衡器	管理应用
`api.apps.create` / `commit`	上传	Commit 与上传
`api.apps.files`	文件管理器	管理文件
`api.apps.envs`	环境变量	环境变量
`api.apps.deploys`	Webhook 和 GitHub App deploy	Deploys
`api.apps.network`	分析、日志、DNS、自定义域名、缓存	网络
`api.apps.realtime`	实时日志和状态	实时
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	备份	Snapshots
`api.databases`	托管数据库	数据库
`api.workspaces`	Workspace、成员和共享应用	Workspaces
`api.ai`	`chat()`	AI

仅有的运行时导出是 SquareCloudAPI、SquareCloudAPIError 和 BASE_URL。其他所有导出（App、RuntimeStats、ErrorCode……）都是类型：

import type { App, Snapshot } from "@squarecloud/api";

约定

ID 在前，返回纯数据

每个方法都以资源 ID 作为第一个参数，并返回纯数据（没有类，没有缓存）。字段名与 API 自身一致（created_at、version_id、lastModified、joinedAt、netIO……），因此 API 参考可直接适用。

变更操作解析为 void，除非 API 返回数据（envs.*、deploys.setWebhook、deploys.linkGithubApp、databases.resetCredentials 以及各 create 方法）。
字符串结果绝不会是 undefined：当 API 未返回时为 ""。
列表一次调用即完整返回：没有分页。

方法都是箭头函数，因此可以解构使用：

const { restart, logs } = api.apps;

await restart(appId);
console.log(await logs(appId));

Workspace 应用

每个 appId 也接受组合形式 <appId>-<workspaceId>，用于操作通过 workspace 与你共享的应用。workspaces.get() 和 workspaces.list() 返回原始 ID；组合 ID 需要你自行构建：

await api.apps.restart(`${appId}-${workspaceId}`);

ID 会被编码

URL 路径中的 ID 会进行百分号编码。空的、. 或 .. 的 ID 会到达不同的路由，因此会在发送任何内容之前于本地以 INVALID_ID（状态 0）失败。Workspace 路由则将 ID 放在请求体中发送：在那里，INVALID_ID（400）来自服务器。

日期

start 和 end 参数（参见网络）接受 ISO 8601 字符串或 Date。响应中的日期保持 API 发送时的原样（ISO 字符串，或在 API 使用时为 Unix 毫秒）。

超时

调用	超时
其他所有调用	每次尝试 `timeoutMs`（30 秒）
服务器保持连接的调用：应用的 `start`/`stop`/`restart`、数据库的 `start`/`stop`、`databases.create`、snapshot 的 `create`/`restore`、`ai.chat`	至少 120 秒（更大的 `timeoutMs` 优先）
上传（`apps.create`、`apps.commit`）、超过 1 MiB 的 `files.write`、`downloadSnapshot`	无：传入 `signal` 以取消
`apps.realtime`	仅在响应头到达之前

timeoutMs 为 0 或更小、Infinity 或 >= 2^31 时，会禁用所有超时，包括 120 秒的下限。只有五个方法接受 AbortSignal：apps.create、apps.commit、files.write、apps.realtime 和 downloadSnapshot。

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await api.apps.commit(appId, "./build.zip", { signal: controller.signal });

被中止的调用会以该 signal 的 reason 拒绝，而不是 SquareCloudAPIError。被中止的 realtime() 循环会直接结束。

账户

api.account.me() 返回已认证的用户，以及该密钥可见的应用和数据库。

const { user, applications, databases } = await api.account.me();

console.log(user.id, user.name, user.email, user.plan.name);
console.log(user.plan.memory); // { limit, available, used } in MB
console.log(user.plan.duration ? new Date(user.plan.duration) : "never expires");

字段	说明
`user`	`id`、`name`、`email`、`locale`、`created_at` 和 `plan`（`name`、`memory`、`duration`：套餐到期时的 Unix 毫秒时间，永不到期时为 `null`）
`applications`	`{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }` 数组
`databases`	`{ id, name, ram, type, cluster, created_at }` 数组

api.account.snapshots({ scope }) 列出账户的所有 snapshot：参见 Snapshots。

平台状态

api.service.status() 返回公开的平台状态。该路由不需要有效密钥，但客户端仍要求提供一个非空密钥。

const status = await api.service.status();

console.log(status.status); // "online" | "degraded" | "unknown"
console.log(status.message);

for (const [name, service] of Object.entries(status.services ?? {})) {
    console.log(name, service.status); // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown 表示检查本身无法运行：这并不代表发生了故障。

后续步骤

管理应用

状态、生命周期、日志和指标。

错误

错误类、重试和速率限制。

API 简介

基础 URL、身份验证和第一个请求。

CLI 快速开始

在终端中部署和管理应用。

CLI

VS Code

SDKs

JavaScript SDK：快速上手与客户端

要求

安装

API 密钥与作用域

创建客户端

选项

模块

约定

ID 在前，返回纯数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

后续步骤

管理应用

错误

API 简介

CLI 快速开始

​要求

​安装

​API 密钥与作用域

​创建客户端

​选项

​模块

​约定

​ID 在前，返回纯数据

​Workspace 应用

​ID 会被编码

​日期

​超时

​账户

​平台状态

​后续步骤

管理应用

错误

API 简介

CLI 快速开始

要求

安装

API 密钥与作用域

创建客户端

选项

模块

约定

ID 在前，返回纯数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

后续步骤