Aeris DevBox
在浏览器预览 Canopus 应用,检查 LVGL 对象并导出截图和录屏。
DevBox 是 Aeris UI 的本地浏览器调试器。接入后,它会把应用的 Rust 页面、状态和导航编译到 WebAssembly,让你直接操作界面,检查当前画面的 LVGL 对象。预览采用小米手环 10 Pro 的 336 × 480 画布。

在画布上指向「15 秒」按钮,检查器会高亮它的边界,并显示 152 × 112 px 的尺寸、内边距和对象属性。
DevBox 能省下哪些调试步骤
按常规 Canopus 流程检查界面,需要为目标固件构建 .canopus 包,再装到 Mirage 或真机上,从管理器打开模块页面。接入 DevBox 后,日常的界面和交互调试可以在本地浏览器完成。
- 保存后直接验证界面。 默认开启的自动刷新会在重新构建成功后更新预览。改完按钮间距、页面布局或交互逻辑,可以直接点按按钮、切换页面,省去每次改动都打包和安装模块的步骤。
- 从画面定位到具体对象。 遇到文字被裁切或按钮位置不对,可以直接在画布上选中元素,查看它在 LVGL 对象树中的层级、尺寸、内边距和计算后的样式,缩小排查范围。
- 单独复现组件问题。 用独立场景打开待检查的组件,可以跳过进入该页面所需的导航步骤,直接反复检查同一个布局或交互。
- 让 AI 助手操作预览并复测。 通过 MCP 或 Agent CLI 接入后,AI 助手可以等待最新构建、读取日志和 LVGL 对象树,在独立的浏览器预览中复现点按、滑动或返回操作,再用截图核对修改后的界面。接入 AI 助手
- 直接导出截图和录屏。 截取整个设备画面或选中区域,便于对照修改前后的布局。用录屏记录页面切换、手势和动画的完整过程,方便提交问题或演示功能。截图与录屏
模块安装、启用和启动可在 Mirage 中验证,振动和系统通知仍需上真机测试。涉及固件接口或 AstroBox 激活的功能,需要在对应的固件和配套环境中验证。在 Mirage 中测试模块 · 真机测试
启动自己的应用
安装工具链和启动器
准备 Rust、Cargo、Make、Node.js(20.19+ 或 22.12+)、pnpm、Emscripten 4.0.20 和 LVGL 9.4.0 源码。下面以 macOS / Linux 的 shell 为例。Emscripten SDK 安装说明 · LVGL v9.4.0
rustup target add wasm32-unknown-emscripten
cd /path/to/emsdk
./emsdk install 4.0.20
./emsdk activate 4.0.20
source ./emsdk_env.sh
export LVGL_DIR=/path/to/lvglLVGL_DIR 指向含有 lvgl.h 的源码根目录。新开终端后,重新加载 emsdk_env.sh 并设置 LVGL_DIR。如果工具链安装在自定义位置,也可以通过 EMCC 和 EMAR 指定编译器和归档工具。
从 Git 安装启动器。已有 Aeris UI 源码时,也可在其根目录执行 cargo install --locked --path crates/cargo-aeris-devbox。
cargo install --locked --git https://github.com/ClaralightDesign/Aeris-UI.git cargo-aeris-devbox启动器会从应用的 Cargo 依赖中找到 Aeris UI,再使用该版本自带的 DevBox。应用本身也需要引用包含 DevBox 的修订。Git 依赖和本地路径依赖都支持。
注册浏览器入口
在应用的 Cargo.toml 中合并以下配置。若已有 [lib]、[features] 或其他库类型,把对应项并入原配置。
[lib]
crate-type = ["staticlib"]
[features]
devbox = ["aeris-ui/devbox"]在应用库入口注册浏览器启动函数。把 browser::start 换成项目里的函数,其签名为 fn(aeris_ui::devbox::Obj) -> bool。DevBox 从 UI 线程传入 LVGL 根对象,应用完成初始化并打开首页后返回 true。
#[cfg(all(feature = "devbox", target_os = "emscripten"))]
mod browser;
#[cfg(all(feature = "devbox", target_os = "emscripten"))]
aeris_ui::devbox_app!(browser::start);尽量共用现有页面、业务状态和导航。把依赖固件地址的代码和依赖放在设备目标下,在浏览器入口为应用用到的存储、时钟等服务提供适配。若希望在预览画面按下 Esc 时走应用自己的返回流程,可以在浏览器分支导出带 #[unsafe(no_mangle)] 的 pub extern "C" fn aeris_devbox_back()。
配置并运行
在应用目录创建 devbox.json。所有路径相对于这份配置文件。
{
"title": "我的手表应用",
"manifest": "Cargo.toml",
"features": ["devbox"],
"source": "src/lib.rs",
"watch": ["assets", "build.rs"]
}| 字段 | 用途 |
|---|---|
title | 工具栏显示的应用名称。必填。 |
manifest | 应用包的 Cargo.toml。工作区项目要指向包含静态库目标的成员清单。必填。 |
features | 浏览器构建要启用的 Cargo feature。应用须在该构建中启用 aeris-ui/devbox。 |
source | 在「源代码」面板里默认打开的项目文件。留空时可从文件树选择。 |
watch | 额外监听的素材、构建脚本或目录。应用及 Cargo 本地依赖的 Rust 源码会自动监听。 |
scenes | 可选的场景列表。每项包含唯一的 id、显示用 title,以及可选的 source。 |
在应用目录运行以下命令并打开终端显示的地址。首次构建会编译 Rust 和 LVGL,后续构建复用本地缓存。
cargo aeris-devbox可用 cargo aeris-devbox configs/watch.json 选择其他配置,或用 AERIS_DEVBOX_PORT=5180 cargo aeris-devbox 指定本地端口。
如果要为组件提供独立的测试场景,在配置中填写 scenes,并使用 aeris_ui::devbox_scenes!(browser::render) 注册入口。场景函数的签名为 fn(aeris_ui::devbox::Obj, &str) -> bool,第二个参数是场景 ID。ID 以小写字母或数字开头,可再包含小写字母、数字、连字符和下划线,最多 127 个字符。使用场景入口时,同一个预览目标只注册这一个挂载宏。
调试界面
缩放、平移与标尺
在支持画布平移的版本中,100% 时画面显示为 168 × 240 CSS 像素,圆角随画面同比缩放。缩放菜单支持输入到 0.1%,触控板捏合可连续缩放。双指滑动可平移,也可以拖动预览区空白处,或按住空格、鼠标中键从画面上拖动。标尺、元素坐标和截图导出使用设备像素。
| 快捷键 | 操作 |
|---|---|
⌘/Ctrl + + 或 - | 放大或缩小画布 |
⌘/Ctrl + 0 | 恢复到 100% 并居中 |
⌘/Ctrl + R | 显示或隐藏标尺 |
⌘/Ctrl + I | 显示或隐藏检查面板 |
⌘/Ctrl + E | 打开或关闭设置 |
⌘/Ctrl + S | 打开或关闭截图与录屏 |
⌘ 用于 macOS,Ctrl 用于其他平台。标尺、检查面板、设置和截图快捷键在 DevBox 主界面使用。焦点位于应用画面内时,可以先点一下画布外的空白处。
检查对象和构建日志
- 元素支持搜索对象树。在画布上选取对象后,可以查看它的样式、布局、事件回调数量和属性。
- 控制台汇集构建日志和应用运行日志。出现构建失败提示时,点「查看详情」跳到控制台,或点「复制提示词」复制错误上下文。
- 源代码在支持文件树的版本中可浏览
manifest对应的应用包目录。展开目录后可点开多个文件,在右侧标签间切换和关闭。源码区支持行号和常见语言的语法高亮。场景可通过自己的source指定默认打开的文件。 - 资源统计当前画面可见的图片对象,性能显示最近绘制间隔和预览的 WASM 内存,图层可以按绘制顺序查看可见对象。
设置里的「保存后自动刷新」默认开启。保存被监听的文件后,DevBox 重新构建,成功时重载预览。关闭此开关后,可以在构建完成后通过「重载」手动更新。若构建失败且已有成功的产物,当前预览仍可操作。同一应用在同一浏览器地址上的本地存储会在重载后保留。
接入 AI 助手
使用支持 Agent 接入的 Cargo 启动器和 Aeris UI 版本。在应用目录安装无头 Chromium 后启动 DevBox。
cargo aeris-devbox agent install-browser
cargo aeris-devbox在预览工具栏打开「设置」,按使用方式开启对应选项。两项默认关闭,开启后共用一个独立于当前工作台画面的无头浏览器预览。
- 通过 MCP 连接。 点「复制 MCP 配置」,将地址和
Authorization请求头填入支持 Streamable HTTP 和自定义请求头的 MCP 客户端。 - 通过 Agent CLI 连接。 点「复制会话路径」。你和 AI 助手都可以运行
cargo aeris-devbox agent <命令> --session <会话路径>来操作预览。运行cargo aeris-devbox agent --help可查看命令。
以轻翎计时器为例,可以让助手等待构建完成,读取 LVGL 对象树,定位并点按「15 秒」,再截图确认倒计时是否启动。修复后让助手在新构建上重复同样的操作。单独排查编译错误时,也可以直接使用构建提示里的「复制提示词」,将错误上下文粘贴给助手。
截图与录屏
点工具栏的「截图与录屏」,选择全屏或区域模式。全屏指整个设备预览。区域模式要在设备画面上拖出选区,按 Esc 可取消选区。「设置 → 截图」可以直接导出整张 PNG。支持图片格式选择的版本可在截图菜单导出 PNG、WebP 或 JPG。
录屏前可选择 MP4、WebP 或 GIF,设置帧率档位和是否录制鼠标指针。录制后点工具栏的计时胶囊停止并导出。MP4 档位会根据浏览器编码能力尝试导出 MP4 或 WebM,WebP 和 GIF 的实际采样帧率可能低于所选档位。
常见问题
| 现象 | 处理方法 |
|---|---|
找不到 cargo aeris-devbox | 安装启动器,并确认 Cargo 的可执行文件目录在 PATH 中。 |
无法打开 devbox.json | 切到应用目录运行,或传入配置文件路径。 |
| 提示当前 Aeris UI 修订没有 DevBox | 检查应用实际解析到的 Aeris UI 版本,以及浏览器构建是否启用了 aeris-ui/devbox。 |
找不到 LVGL 或 emcc | 检查 LVGL_DIR/lvgl.h 是否存在,并在当前终端运行 emcc --version。 |
| 修改素材后画面没有更新 | 将素材路径加入 watch,检查「保存后自动刷新」是否开启,再到控制台查看构建结果。 |
| 文件树里找不到文件 | 检查文件是否位于 manifest 对应的应用包目录内。文件树会略过隐藏目录、依赖、构建产物和符号链接。 |