# @beamcloud/beam-js 中文文档

规范地址：https://npmcn.com/package/%40beamcloud/beam-js/

版本：1\.1\.6
npm 元数据更新时间：2026-10-16T18:37:50.415Z
中文译文更新时间：2026-11-07T19:38:50.793Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40beamcloud/beam-js
原文对照：https://npmcn.com/package/%40beamcloud/beam-js/?lang=original
项目主页：https://github.com/beam-cloud/beam-client/tree/master/js#readme
源码仓库：https://github.com/beam-cloud/beam-client

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

- 包体积（解压后）：606 kB，124 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：typescript ^5\.0\.0
- 首次发布：2024-10-29T19:00:47.910Z
- 最新版本发布：2026-10-16T18:37:49.870Z
- 近 30 天下载量：24690（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 28 个）

## 中文简介

用于 Beam 的 TypeScript 和 JavaScript SDK

## 安装

```sh
npm install @beamcloud/beam-js
```

也可以使用：`pnpm add @beamcloud/beam-js`、`yarn add @beamcloud/beam-js`、`bun add @beamcloud/beam-js`

## README

# Beam 类型脚本/ Java 脚本 SDK

官方TypeScript和JavaScript SDK为Beam发行.

## 安装

```bash
npm install @beamcloud/beam-js
```

```bash
yarn add @beamcloud/beam-js
```

## 配置

拨打SDK电话前先设定您的Beam标志和工作空间ID.

```typescript
import { beamOpts } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN!;
beamOpts.workspaceId = process.env.BEAM_WORKSPACE_ID!;
```

SDK默认目标是"Beam Cloud".

## 虚拟机

创建持久的 Linux VM, 运行命令, 抓取其根并叉出它 :

```typescript
import { beamOpts, VM } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN!;
const vm = await VM.create({
  name: "agent-workspace",
  cpu: 1,
  memory: "2Gi",
  protectedPorts: [7681],
  idleTimeout: 300,
  idleAction: "pause",
  autoResume: true,
});
console.log(vm.publicIpv6); // Persistent IPv6 address, when public networking is enabled.
const command = await vm.exec(["node", "--version"]);
await command.wait();
console.log(await command.stdout.read());

const snapshot = await vm.snapshots.create("ready");
const branch = await snapshot.fork({ name: "experiment", memory: "512Mi" });
await branch.remove();
await snapshot.delete();
await vm.pause();
await vm.close();
// Later: await VM.connect(vm.id); to delete: await vm.remove().
```

VMs 默认为消化固定的 Ubuntu 24.04, 4 个CPU, 8 个 GiB 内存和一个 50 个 GiB 可写根. 桌面是选入( T)`desktop: true`,最小值 1 GiB 内存;多克 需求 `dockerEnabled: true`。创建等待来宾命令。 使用 `await vm.wait({ services: true })` sSH、终端和启用的桌面; 多克帮手分别等待守护进程.

一个 `VM` 对象曝光生命周期、快照/模板、文件、多克、桌面 控制,私人隧道,SSH/SCP,目录同步,提示,日志和公制. 见 [VM 引导并完成 API/ 均等映射](https://npmcn.com/package/%40beamcloud/beam-js/docs/virtual-machines.md)。 。 。 . 关于带有清理功能的可运行的 JavaScript 工作流程,参见 [代理工作空间示例](https://npmcn.com/package/%40beamcloud/beam-js/examples/vm-agent-workspace.mjs)。 。 。 .

## 沙盒快速启动

创建沙盒,运行代码,流日志,并清洁地终止.

```typescript
import { beamOpts, Image, Sandbox } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN!;
beamOpts.workspaceId = process.env.BEAM_WORKSPACE_ID!;

async function main() {
  const sandbox = new Sandbox({
    name: "examples",
    image: new Image({ pythonPackages: ["requests"] }),
    cpu: 1,
    memory: 1024,
    keepWarmSeconds: 300,
  });

  const sb = await sandbox.create();

  const result = await sb.runCode(`
import requests
print(requests.get("https://api.github.com").status_code)
`);
  console.log(result);

  const process = await sb.exec(["python3", "-c", "print('hello from Beam')"]);
  for await (const line of process.logs) {
    console.log(line.trimEnd());
  }

  await sb.terminate();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

`name` 是用于组合沙盒的Beam应用名称。 每个正在运行的沙盒仍然会得到它自己生成的沙盒ID.

## 显示一个端口

```typescript
const server = await sb.execShell("python3 -m http.server 8888 --bind 0.0.0.0");
const url = await sb.exposePort(8888);
console.log(url);

await server.kill();
```

## 文件系统

```typescript
await sb.fs.writeText("/tmp/hello.txt", "hello");
console.log(await sb.fs.readText("/tmp/hello.txt"));

await sb.fs.mkdir("/tmp/data");
await sb.fs.uploadFile("./local.txt", "/tmp/data/local.txt");
console.log(await sb.fs.list("/tmp/data"));
await sb.fs.remove("/tmp/data/local.txt");
```

## 抓图

```typescript
const checkpointId = await sb.snapshot();
await sb.terminate();

const restored = await Sandbox.createFromSnapshot(checkpointId);
console.log(restored.sandboxId);
```

## 夹克

在图像中安装 Docker 并明确启用管理的守护进程 :

```typescript
const sandbox = new Sandbox({
  name: "docker-actions",
  image: Image.fromRegistry("node:20-slim").withDocker(),
  dockerEnabled: true,
  cpu: 2,
  memory: "2Gi",
  keepWarmSeconds: 300,
});

const sb = await sandbox.create();
try {
  const ready = await sb.exec([
    "timeout", "60", "sh", "-c",
    "until docker info >/dev/null 2>&1; do sleep 1; done",
  ]);
  if (await ready.wait() !== 0) throw new Error("Docker daemon did not become ready");
  const proc = await sb.exec([
    "docker", "run", "--rm", "--network=host", "--pid=host",
    "alpine:3.20", "echo", "hello",
  ], { wait: true });
  if (await proc.wait() !== 0) throw new Error(await proc.stderr.read());
  console.log(await proc.stdout.read());
} finally {
  await sb.terminate();
}
```

`withDocker()` 支持Ubuntu和Debian图像并安装多克引擎, CLI, Buildx, (英语), `docker compose`,则 `docker-compose` 别名。 其他基础图像 必须提供自己的多克安装。 没有安装主机 Docker 套接字 .

通过 Docker 命令运行 `sb.exec` 或者说 `sb.execShell`; 一个单独的 Python 风格 `sb.docker` 不需要包装。 守护进程同步启动: 等待 `docker info` 在签发建造或运行集装箱之前成功.

被管理的守护进程使用 VFS 存储,在 runc/g Visor 下没有默认桥. 使用 `--network=host --pid=host` 用于内容器; 这些共享沙盒的 名字空间,不是工人机器的。 对于编曲,配置每个服务 `network_mode: host` 财务报告和审定财务报表 `pid: host`启用 `docker compose -f /path/compose.yaml up` 财务报告和审定财务报表 `down` 结束 `exec`; 编译文件不自动重写. 以 `docker build --network=host -t my-image /path/to/context`; 否则 粘贴文件 `RUN` 指令失败 `network bridge not found`,即使当 指令不访问网络.

## 卷和云桶

```typescript
import { CloudBucket, Volume } from "@beamcloud/beam-js";

const volume = new Volume("cache", "/mnt/cache");
const bucket = new CloudBucket("my-bucket", "/mnt/bucket", {
  accessKey: "AWS_ACCESS_KEY_ID",
  secretKey: "AWS_SECRET_ACCESS_KEY",
  region: "us-east-1",
});

const sandbox = new Sandbox({
  name: "storage",
  volumes: [volume, bucket],
});
```

## 发展

将 SDK 指向本地网关:

```typescript
beamOpts.gatewayUrl = "http://localhost:1993";
```

## 链接

-   [光束文件](https://docs.beam.cloud/)
-   [npm 软件包](https://www.npmjs.com/package/@beamcloud/beam-js)
-   [GitHub 图像](https://github.com/beam-cloud/beam-client/tree/master/js)

## 常见问题

### @beamcloud/beam-js 是什么？

用于 Beam 的 TypeScript 和 JavaScript SDK

### 如何安装 @beamcloud/beam-js？

在项目目录运行 npm install @beamcloud/beam-js，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beamcloud/beam-js 支持 TypeScript 吗？

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

### @beamcloud/beam-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @beamcloud/beam-js 可以商用吗？

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

### @beamcloud/beam-js 的下载量有多少？

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

### @beamcloud/beam-js 还在维护吗？

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