# @exedev/sdk 中文文档

规范地址：https://npmcn.com/package/%40exedev/sdk/

版本：0\.4\.1
npm 元数据更新时间：2026-10-19T22:05:29.959Z
中文译文更新时间：2026-11-14T03:28:18.976Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40exedev/sdk
原文对照：https://npmcn.com/package/%40exedev/sdk/?lang=original
项目主页：https://exe.dev/docs/https-api
源码仓库：https://github.com/boldsoftware/exe-sdk-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：263 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-05-07T20:12:34.309Z
- 最新版本发布：2026-10-19T22:05:29.820Z
- 近 30 天下载量：12961（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Exe.dev API 的官方 JavaScript/ TypeScript SDK

## 安装

```sh
npm install @exedev/sdk
```

也可以使用：`pnpm add @exedev/sdk`、`yarn add @exedev/sdk`、`bun add @exedev/sdk`

## README

# @ exedev/ sdk

官方 Java 脚本/ Type 脚本 SDK [exe.dev (英语)](https://exe.dev/) HTTPS API. (英语).

```sh
npm install @exedev/sdk
```

## 快开始

```ts
import exedev from "@exedev/sdk";

const exe = exedev({ token: process.env.EXE_TOKEN! });
const vm = await exe.new({ name: "my-vm", image: "ubuntu:24.04", tag: ["dev"] });
// new waits for SSH by default. No create-then-ssh retry loop is needed.
try {
  console.log(vm.name, vm.httpsUrl);
  const result = await vm.ssh("uname -a");
  console.log(result.exitCode, result.stdout, result.stderr);
  await vm.shareAdd("friend@example.com", { message: "have a look" });
} finally {
  await vm.rm();
}
```

## 客户端和VM API

`exedev({ token, baseURL?, fetch? })` 创建客户端. `baseURL` 默认为 `https://exe.dev`· ; `fetch` 默认执行。 已命名的进口 联 合 国 `exedev`, (中文(简体) ), `ExedevClient`,以及 `VM` 也可查阅.

-   `exe.new(options?)` 创建 VM 并返回 a `VM` 对象.
-   `exe.ls(nameOrPattern?, options?)` 返回时 `VM[]`。 。 。 .
-   `exe.vm(name)` 引用一个不提出请求的现有 VM .
-   `vm.refresh(options?)` 刷新其元数据并返回同一对象.
-   `vm.ssh(command, options?)` 运行一个贝壳命令 在VM.
-   `vm.cp({ name?, ...options })` 复制并返回一个新的 `VM` 对象.
-   `exe.rm(vms)` 删除一个请求中的 VM 或名称数组; 服务器 一次删除数个。 它决心 `{ deleted, failed, not_found, errors }` 而不是丢入 VM , 它不能删除 .
-   生命周期和VM-扫描指令是VM上的方法: `vm.rm()`, (中文(简体) ), `vm.pause()`, (中文(简体) ), `vm.resume()`, (中文(简体) ), `vm.restart()`, (中文(简体) ), `vm.rename(newName)`, (中文(简体) ), `vm.resize(options)`, (中文(简体) ), `vm.stat(options)`, (中文(简体) ), `vm.tag(tags)`, (中文(简体) ), `vm.comment(text)`, (中文(简体) ), `vm.shareShow()`, (中文(简体) ), `vm.sharePort(port)`,其他生成的 VM 命令.
-   客户端仍保留账户命令 : `exe.whoami()`, (中文(简体) ), `exe.sshKeyList()`, (中文(简体) ), `exe.integrationsList()`, (中文(简体) ), `exe.billingPlan()`等 (中文(简体) ).

没有平行的原始命令 API 或客户端级别 `ssh` 或者说 `cp`。 。 。 . `vm.rm()` 掷出 `ExeAPIError` 如果 VM 不删除,则 `status` 404 如果不是的话 已存在. 生成命令的选项保留 CLI 旗帜名称( 例如, ), `{ "no-email": true }`; 每种方法都带有服务器的帮助文本. 除了每个 VM 命令 `grantSupportRoot`,以及 `whoami`拥有一个已知的JSON 反应:它的方法拒绝其他任何东西,并解决反应 类型。 电线类型(`VMRecord`, (中文(简体) ), `NewResponse`, (中文(简体) ), `ShareShowResponse`,(...)为 导出。 少数报告结果是问题而不是错误: `domainAdd` 当 DNS 尚未指向 exe.dev 时 `shelleyInstall` 何时 舍利失踪; 窄与 `"error" in result`。其他账户命令 可能返回 JSON 或文本,并输入为 `unknown`。 。 。 .

`vm.name` 是当前名称. `vm.httpsUrl`, (中文(简体) ), `vm.sshDest`,以及 `vm.tags` 曝光 普通元数据. `vm.info` 是一个只读快照 `status`, (中文(简体) ), `region`, (中文(简体) ), `comment`, (中文(简体) ), `createdAt`,以及 `promptError` (为什么) `new`是因为 `prompt` 未达到 舍利来时. 参考来源 `exe.vm(name)` 最初只知道 名称, 无标签; 调用 `refresh()` 去拿剩下的东西 副本来自 `cp()` 有标记和网络 URL 服务器报告它。 SDK自己的行动 更新快照:通过备战等待的 VM 是 `running`,以及 `pause()`, (中文(简体) ), `resume()`, (中文(简体) ), `comment()`,以及 `tag()` 记录他们改变了什么。 A 类 已经成功 `rename()` 更新同一对象,并使用新的 SSH 对象和 网络 URL 服务器报告 . 其他参考资料和其他地方所作的改动,需要 `refresh()`。 。 。 .

## 准备和取消

`new`, (中文(简体) ), `cp`, (中文(简体) ), `restart`,以及 `resume` 默认等待 SSH 。 过 `{ waitUntil: "created" }` 返回时不检查,包括当符号 没有 `ssh` 允许. `vm.waitUntilReady({ waitUntil?, timeoutMs?, signal? })` 明确等待以后。 默认准备时间为60秒 **之后** 创建或生命周期操作返回,包括探测请求和后退.

准备只运行无害的命令 `true`,重试瞬间连接 失败。 它从不重复用户命令或创建请求,而是 不等待应用程序服务器.

`{ waitUntil: "setup" }` 也等待 VM 的设置脚本(`new`是因为 `"setup-script"`,由exeuntu的运行 `exe-setup.service`结束,投票 单位超过SSH,默认截止时间为10分钟. 如果剧本失败,则 `VMReadyError`是因为 `cause` 是一个 `VMSetupError` 与 `exitCode` (或 `signal`和 系统 `result`· ; `details().output` 拥有其日志的结尾。 只有exeuntu, 默认的图像, 以及在其上所建的图像 运行设置脚本: 在其它的, 例如 作为 `ubuntu:24.04`剧本没有运行,等待它是一个 `VMSetupError` 与 `result` `"unsupported"`。没有剧本,什么也没有 等待,一旦一个脚本运行了,以后的重启不会等待它.

```ts
const vm = await exe.new({ "setup-script": "#!/bin/sh\nsudo apt-get install -y jq", waitUntil: "setup" });
```

如果等待失败, `VMReadyError.vm` - 向您提供核查或清理的车辆; 它不会自动被删除。 包括一个没有 `ssh` 权限: 探测器被拒绝, 错误说要使用 `waitUntil: "created"`。所有行动接受 `AbortSignal`。 。 。 . 调用者取消保留 `signal.reason`,包括在溪流和 召回,而不是将其打入另一个错误中。 中止的创建可能 仍然创建了 VM; 使用明确的名称或 `ls()` 把它找回来.

## 运行命令

`vm.ssh()` 决定: `{ exitCode, stdout, stderr, stdoutBytes, stderrBytes, captured }`。一个非零退出代码是结果,而不是例外;一个命令被杀死 通过信号N出口128+N,如在外壳. b. 字节数组保存二进制输出; 字符串被解码为UTF-8. 命令是 shell 脚本: 引用任何不可信 数值 `quote`。 。 。 .

```ts
import { quote } from "@exedev/sdk";
await vm.ssh(`cat ${quote(path)}`);
```

命令运行在非日志外壳中. 变量从 `new`是因为 `env` 设定为 它们(一旦VM的exe-init有更新,则使用;然后使用) `bash -lc`) (中文(简体) ). 长而无声的命令是好的:服务器保持了响应的活性.

```ts
await vm.ssh("make", {
  capture: false,
  onStdout: (chunk) => { process.stdout.write(chunk); },
  onStderr: (chunk) => { process.stderr.write(chunk); },
});
```

连续等待回调,每条流都有递增的UTF-8解码. 它们的跨流顺序大致相同. 从召回中丢弃取消 回答错误,并拒绝错误.

输出默认被捕获, 带有 **8个米B综合限值** {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}然后呢 师曰. 换一个 `maxOutputBytes`; 超过它会取消响应和 掷出 `SSHStreamError` 有代码 `output_limit`设置 `capture: false` 页:1 任意长长输出的边框-记忆流:仍然收到回调 ,但结果/错误输出为空并 `captured` 是虚假的。 捕捉限制 在此模式中被忽略。 无效或超大小的 NDJSON 帧总是被拒绝 .

## 错误

-   `ExeAPIError`数字 : `operation` 和 HTTP 软件 `status`。信息包括: 服务器的错误文本, 在一行, 没有终端逃逸或其他控制 字符,并缩短为200个字符,例如 `exe.dev API error (422) during ssh: VM "web" is not running`永远不会 包括请求,但服务器的文本可以提及您发送的值. `error.details().body` 完全有反应;这可能包含秘密.
-   `ExeNetworkError`: 在完整答复到来之前,请求失败, 例如网络出错或在读取响应时丢失的连接. `operation` 命名命令,并发送系统错误代码 有一个 操作是否生效未知 : `new` 也许有 创建了 VM,所以通过 a `name` 如果你需要再找到它的话. `details().cause` 有运输错误.
-   `ExeProtocolError`:不兼容的反应,包括JSON或 不支持 NDJSON SSH 输出的服务器.
-   `SSHStreamError`:中断/无效输出或捕获限制. `code` 实值 `interrupted`, (中文(简体) ), `protocol`,或 `output_limit`; 获取器提供捕获的部分 输出。 退出状态不明. 答复前未答复的请求 (例如,网络出错)是 `interrupted` 由于命令可能 已经开始了. `details()` 曝光选择性诊断: 服务器的消息或 运输错误.
-   `VMReadyError`: 准备失败; `vm` 财务报告和审定财务报表 `cause` 备有.
-   `VMSetupError`: 设置脚本失败或未运行 `cause` 页:1 `VMReadyError`。 。 。 .

错误无法确定操作从未运行 。 不要盲目重试一个 运输失败后发生突变或远程命令.

## 认证

通过 SSH 生成一个符号 :

```sh
ssh exe.dev ssh-key generate-api-key --label=my-app --exp=30d --cmds="new,ls,ssh,share add,rm"
```

见 [HTTPS API 文档](https://exe.dev/docs/https-api) 授权和范围界定.

## 发展

**全体人员 `src/` 生成.** 编辑 `cmd/gensdkjs` 及其类型脚本模板 在 exe.dev 仓库中,然后运行 `go run ./cmd/gensdkjs` 在这里。 复制 输出到此检查和测试中 :

```sh
npm install
npm run sync-commands -- ../exe
npm test
```

`npm test` 构建软件包,检查公共类型Script API,并运行单元 和现场融合测试。 现场测试需要一个标记的标志 并创建, 复制、执行命令,重新启动、重命名和删除自己的测试 VM. 他们读了 `$EXE_TOKEN`,或 `$EXE_TOKEN_FILE` (含 `token`),或 `~/.config/exedev/sdk-test-token`。预期标签是 `sdk-test` (与 `$EXE_TEST_TAG`) (中文(简体) ). 设定 `$EXE_BASE_URL` 测试另一个 部署,例如 `https://exe-staging.dev`。要创建测试符号:

```sh
ssh exe.dev 'ssh-key generate-api-key --label=sdk-test --tag=sdk-test --exp=30d --cmds="ls,new,whoami,stat,rm,restart,rename,cp,ssh,ssh-key list,share show" --json'
```

设定 `EXE_SKIP_INTEGRATION=1` 无法活着进入 设定 `EXE_SKIP_SSH_INTEGRATION=1` 仅用于在 服务器尚未部署 NDJSON SSH 支持; 这明确跳过 live SSH 和准备状态,而不是相应的单位测试。 现场直播 套接字需要该协议,不会默默地回到原始的SSH输出.

发电机的"去"测试检查再生和命令语法假设. 服务器侧电线合同测试活动创建、上市、复制和SSH. 要运行生成的 SDK 端到端对应本地的 Go HTTP/ SSH 固定 :

```sh
# In the exe.dev checkout, with this SDK's npm dependencies installed:
EXE_SDK_JS_DIR=/absolute/path/to/exe-sdk-js go test ./execore -run TestSDKJSHTTP
```

## 许可证

麻省理工学院

## 常见问题

### @exedev/sdk 是什么？

Exe\.dev API 的官方 JavaScript/ TypeScript SDK

### 如何安装 @exedev/sdk？

在项目目录运行 npm install @exedev/sdk，或使用 pnpm add / yarn add / bun add。

### @exedev/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @exedev/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @exedev/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @exedev/sdk 可以商用吗？

@exedev/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @exedev/sdk 的下载量有多少？

根据 npm 官方下载统计，@exedev/sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 12,961 次，日均约 432 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @exedev/sdk 还在维护吗？

最新版本 0\.4\.1 发布于 2026/10/20（25 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/05/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。