# 蒸汽模式 DevTools
通过 CLI 创建、复用 uni-app x 蒸汽模式 App 的 DevTools 调试会话，并在不打开 DevTools 窗口的情况下读取或修改应用的调试数据（DOM、样式、页面、Network、Storage 等），适用于无人值守调试、自动化脚本等场景。
需先安装
uniappx-vapor-devtools插件，详见插件安装。
# 适用范围
- 仅适用于 uni-app x 蒸汽模式的
app-android、app-ios、app-harmony。 - 不适用于 Web 和小程序。
- 同一平台同一时间只处理一台运行设备；若连接了多台设备，请先确定要调试的那一台。
# 概念说明
- Session（会话）：针对某台设备上正在运行的 App 建立的一次 DevTools 调试会话。同一时间可以存在多个会话。
- port（端口）：每个会话在电脑本机监听的端口号，创建会话后由
start、list返回。后续所有操作都用--port指定会话。 - Runtime：设备上运行的应用，通过会话向电脑上报页面、DOM、Network、Storage 等调试数据。
# 使用流程
# 1. 确认插件
DevTools 依赖 dcloud.uniappx-vapor-devtools 插件。HBuilder V 会在需要时通过 IDE 的插件安装交互检查并安装该插件；CLI 不提供安装插件的能力，请确保插件已安装后再执行后续命令。
# 2. 查询已有会话
cli uniappx-vapor-devtools --command list
返回结果中的 projectPath、platform、iosTarget、deviceId、deviceName 可用于识别会话。若已有与当前调试目标匹配的会话，直接复用其 port 即可。
# 3. 创建会话
没有可复用的会话时新建一个（创建后自动分配端口）。先用 设备列表 枚举设备：
| 目标 | devices list --platform 取值 |
|---|---|
| Android | android |
| iOS 真机 | ios-iPhone |
| iOS 模拟器 | ios-simulator |
| HarmonyOS | app-harmony |
cli uniappx-vapor-devtools --command start \
--project <项目绝对路径> \
--platform <app-android|app-ios|app-harmony> \
--deviceId <设备ID> \
[--iosTarget <device|simulator>] \
[--deviceName <名称>]
--project必须是绝对路径；--iosTarget仅app-ios使用。- 创建成功后会返回
port和runtimeInfo，后续操作都要用到port。 - Android / HarmonyOS 由 CLI 自动建立设备端口反向转发；iOS 真机使用本机局域网 IPv4 地址（需与电脑处于同一局域网），模拟器使用
127.0.0.1。
# 4. 查询会话状态
cli uniappx-vapor-devtools --command status --port <端口>
| 返回 | 处理 |
|---|---|
connected | 可以直接执行数据操作 |
disconnected | 应用尚未连接或已断开，请参考 重启应用 重新拉起后再重试 |
SESSION_NOT_FOUND 或其它错误 | 停止任务 |
# 5. 关闭会话
cli uniappx-vapor-devtools --command stop --port <端口>
若会话是复用已有的，请勿关闭，以免影响其它使用方。返回 SESSION_NOT_FOUND 说明会话已不存在，无需处理。
# 可用操作
以下命令均使用已选定的 {port}。
# dom
读取 DOM 和样式，并支持修改属性与样式。
cli uniappx-vapor-devtools --command dom --port <端口> --action get-document --depth 2
cli uniappx-vapor-devtools --command dom --port <端口> --action describe-node --node <节点ID> --depth -1
cli uniappx-vapor-devtools --command dom --port <端口> --action computed-style --node <节点ID>
cli uniappx-vapor-devtools --command dom --port <端口> --action box-model --node <节点ID>
cli uniappx-vapor-devtools --command dom --port <端口> --action set-attribute --node <节点ID> --name <属性名> --value <值>
cli uniappx-vapor-devtools --command dom --port <端口> --action set-style --node <节点ID> --name <样式名> --value <值>
| 参数 | 说明 |
|---|---|
--action | 操作：get-document / describe-node / computed-style / box-model / set-attribute / remove-attribute / set-style |
--node | DOM 节点 ID，除 get-document 外必填 |
--depth | 子树深度，默认 1，-1 为完整子树，仅 get-document、describe-node 使用 |
--name / --value | 属性名/样式名与其值 |
- 页面切换或 DOM 刷新后，旧节点 ID 可能失效，需要重新获取。
- 节点包含
uniProperties、uniComponent、uniSourceFile等扩展字段，便于判断页面、自定义组件与普通 Element。 set-style修改行内样式，set-attribute、remove-attribute修改属性。命令成功只表示 setter 已调用，不保证画面已刷新。
# 截图
截取指定 Element（dom）或整个页面（page）。
cli uniappx-vapor-devtools --command dom --port <端口> --action capture-screenshot \
--node <节点ID> --output <绝对png路径> [--overwrite]
cli uniappx-vapor-devtools --command page --port <端口> --action capture-screenshot \
--output <绝对png路径> [--full-page] [--overwrite]
| 参数 | 说明 |
|---|---|
--output | 截图输出文件的绝对路径，必填 |
--full-page | 开关参数，传入时截取完整页面，仅页面截图使用 |
--overwrite | 是否覆盖已有截图，默认 false |
截图固定为 PNG，单张上限 16 MiB。
# page
页面跳转，仅供无头调用方使用。
cli uniappx-vapor-devtools --command page --port <端口> --action navigate --type navigateTo --url /pages/detail/detail?id=1
cli uniappx-vapor-devtools --command page --port <端口> --action navigate --type navigateBack --delta 1
| 参数 | 说明 |
|---|---|
--type | 跳转方式：navigateTo / redirectTo / switchTab / reLaunch / navigateBack |
--url | 页面路径，navigateTo、redirectTo、switchTab、reLaunch 必填，需以 / 开头 |
--delta | 返回页面层数，默认 1，仅 navigateBack 使用 |
# network
采集并读取应用的网络请求。
cli uniappx-vapor-devtools --command network --port <端口> --action list
cli uniappx-vapor-devtools --command network --port <端口> --action get --request <请求ID>
cli uniappx-vapor-devtools --command network --port <端口> --action body --request <请求ID>
仅采集连接会话之后产生的
uni.request、uni.uploadFile、uni.downloadFile请求，最多保留最近 1000 条；UTS 插件直接发起的请求不会出现，应用重连后历史记录清空。
# storage
读取和修改应用的本地 Storage。
cli uniappx-vapor-devtools --command storage --port <端口> --action list
cli uniappx-vapor-devtools --command storage --port <端口> --action add-item --key <键名> --value <值> --value-type <string|number|boolean|null|array|object>
cli uniappx-vapor-devtools --command storage --port <端口> --action set-item --key <键名> --value <值>
cli uniappx-vapor-devtools --command storage --port <端口> --action remove-item --key <键名>
cli uniappx-vapor-devtools --command storage --port <端口> --action clear
CLI 不支持修改 key；Storage 的实时变化不会主动推送，需要最新数据时重新执行
list。
# component
自定义组件 Props 目前仅支持读取，不支持修改，可通过 dom --action describe-node 返回的 uniComponent、uniComponentProps 字段读取。
# 错误码
| 错误码 | 含义 |
|---|---|
INVALID_ARGUMENT | 参数缺失或格式错误 |
SESSION_NOT_FOUND | 会话不存在或已关闭 |
SESSION_CLOSED | 会话在创建期间已关闭 |
LOCAL_NETWORK_ADDRESS_UNAVAILABLE | iOS 真机调试无可用局域网 IPv4 地址 |
DEVTOOLS_NOT_READY | Runtime 或无头客户端尚未就绪 |
CONNECTION_CHANGED | 操作期间 Runtime 连接发生变化 |
PAGE_NOT_FOUND | 当前没有可操作的页面 |
NODE_NOT_FOUND | 文档中不存在指定节点 |
NODE_NOT_ELEMENT | 指定节点不是 Element |
REQUEST_NOT_FOUND | Network 请求不存在或已淘汰 |
STORAGE_ITEM_ALREADY_EXISTS | 新增的 Storage key 已存在 |
STORAGE_ITEM_NOT_FOUND | 要修改的 Storage key 不存在 |
STORAGE_VALUE_INVALID | 新值无法按原类型解析 |
NAVIGATION_FAILED | 页面跳转失败 |
SCREENSHOT_FAILED | 平台截图或文件读取失败 |
SCREENSHOT_TOO_LARGE | PNG 超过 16 MiB |
OUTPUT_ALREADY_EXISTS | 目标文件已存在且未允许覆盖 |
REQUEST_TIMEOUT | 单次操作超过内部超时 |
PORT_FORWARD_FAILED | 设备端口转发失败或当前 Launcher 不支持 |
INTERNAL_ERROR | 未归类的插件或 Server 错误 |
