Desktop 模板-函数计算(FC)-阿里云帮助中心

Desktop 模板提供完整的 Linux 桌面环境，内置 Chrome，并兼容 e2b-desktop / @e2b/desktop SDK。您可以通过截图感知桌面，通过鼠标、键盘操作 GUI 应用，并通过实时流观察执行过程。

与 browser 模板相比，Desktop 模板控制的是整套虚拟桌面，而不是只通过 CDP 控制浏览器。本页介绍镜像配置、模板构建和最小验证；完整的鼠标键盘操作、实时流和安全建议，请参见使用 Computer Use Sandbox。

功能特性

特性	说明
完整桌面	提供窗口管理器、终端和文件管理器
GUI 自动化	通过截图、鼠标坐标、键盘和窗口 API 操作桌面应用
浏览器	内置 Chrome，可通过应用启动接口打开指定 URL
实时查看	通过 SDK 开启整桌面实时流
SDK 兼容	支持 Python `e2b-desktop` 和 TypeScript `@e2b/desktop`

默认配置

本文使用 v0.0.39 版本的北京地域镜像：

配置项	默认值	说明
容器镜像	`fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/desktop:v0.0.39`	Desktop 官方镜像，北京地域示例
CPU	4 vCPU	推荐起始规格
内存	8192 MB	推荐起始规格

说明

构建模板时，镜像仓库地域应与云沙箱接入地域保持一致。其他地域请将镜像地址中的地域替换为对应地域，并保持版本为唯一标签 v0.0.39；同时配置同地域的 E2B_API_URL 和 E2B_DOMAIN。

构建 Desktop 模板

Desktop 模板不是开通即用的内置模板，需要先从官方 Desktop 镜像构建一个带名称的自定义模板。模板无需配置启动命令或就绪命令，Desktop SDK 会自动启动桌面环境和实时流服务。

Python

安装依赖：

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install e2b-desktop==2.4.1 python-dotenv

将以下代码保存为 build.py：

"""Desktop 模板构建示例。"""

from dotenv import load_dotenv
from e2b import Template, default_build_logger

load_dotenv()

# SDK 自动读取 E2B_API_KEY / E2B_API_URL / E2B_DOMAIN 环境变量。
FROM_IMAGE = "fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/desktop:v0.0.39"

build = Template.build(
    Template().from_image(FROM_IMAGE),
    name="my-desktop-template",
    cpu_count=4,
    memory_mb=8192,
    on_build_logs=default_build_logger(),
)
print(f"template_id: {build.template_id}")

运行构建：

python build.py

Node.js

安装依赖：

npm install e2b@^2.31.0 @e2b/desktop@2.3.1 dotenv
npm install --save-dev tsx
npm pkg set type=module

将以下代码保存为 build.mjs：

// Desktop 模板构建示例。
import "dotenv/config";
import { Template, defaultBuildLogger } from "e2b";

const FROM_IMAGE =
  "fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/desktop:v0.0.39";

const build = await Template.build(
  Template().fromImage(FROM_IMAGE),
  "my-desktop-template",
  {
    cpuCount: 4,
    memoryMB: 8192,
    onBuildLogs: defaultBuildLogger(),
  },
);
console.log(`template_id: ${build.templateId}`);

运行构建：

node build.mjs

最小验证

模板构建完成后，创建沙箱、启动 Chrome 并截图，验证桌面环境和应用启动能力。

Python：

from pathlib import Path

from dotenv import load_dotenv
from e2b_desktop import Sandbox

load_dotenv()

desktop = None
try:
    desktop = Sandbox.create(template="my-desktop-template", timeout=600)
    desktop.launch("google-chrome", "https://example.com")
    # 等待应用窗口渲染完成，避免截到尚未加载的桌面。
    desktop.wait(10000)
    Path("desktop.png").write_bytes(desktop.screenshot())
finally:
    if desktop is not None:
        desktop.kill()

TypeScript：将以下代码保存为 desktop.ts。

import "dotenv/config";
import { writeFileSync } from "node:fs";
import { Sandbox } from "@e2b/desktop";

let desktop: Sandbox | undefined;
try {
  desktop = await Sandbox.create("my-desktop-template", { timeoutMs: 600_000 });
  await desktop.launch("google-chrome", "https://example.com");
  // 等待应用窗口渲染完成，避免截到尚未加载的桌面。
  await desktop.wait(10_000);
  writeFileSync("desktop.png", await desktop.screenshot());
} finally {
  await desktop?.kill();
}

运行示例：

npx tsx desktop.ts

常用能力速查

能力	Python	TypeScript
创建沙箱	`Sandbox.create(template=..., timeout=...)`	`Sandbox.create(template, { timeoutMs })`
启动应用	`desktop.launch("google-chrome", url)`	`desktop.launch("google-chrome", url)`
等待	`desktop.wait(10000)`	`desktop.wait(10000)`
截图	`desktop.screenshot()`	`desktop.screenshot()`
移动鼠标	`desktop.move_mouse(x, y)`	`desktop.moveMouse(x, y)`
单击 / 双击 / 右键	`left_click()` / `double_click()` / `right_click()`	`leftClick()` / `doubleClick()` / `rightClick()`
滚动	`desktop.scroll("down", amount)`	`desktop.scroll("down", amount)`
拖拽	`desktop.drag((x1, y1), (x2, y2))`	`desktop.drag([x1, y1], [x2, y2])`
输入文本	`desktop.write("...")`	`desktop.write("...")`
按键 / 组合键	`press("enter")` / `press(["ctrl", "c"])`	`press("enter")` / `press(["ctrl", "c"])`
当前窗口 ID	`desktop.get_current_window_id()`	`desktop.getCurrentWindowId()`
开启 / 停止实时流	`stream.start()` / `stream.stop()`	`stream.start()` / `stream.stop()`
获取流地址	`stream.get_url(auth_key=...)`	`stream.getUrl({ authKey })`
销毁沙箱	`desktop.kill()`	`desktop.kill()`

使用限制

限制项	说明
资源规格	建议使用 4 vCPU、8192 MB 内存或更高规格
地域	镜像、`E2B_API_URL` 和 `E2B_DOMAIN` 必须使用同一地域
实时流	同一沙箱同一时刻只能开启一个整桌面 Desktop stream；`v0.0.39` 版本暂不支持指定单个窗口
生命周期	任务结束后应调用 `kill()`，避免桌面沙箱持续占用资源