kxdevice 命令参考

kxdevice 的全部子命令与参数，按设备与配对、安装与 App、启动与截图、调试与符号、日志与崩溃、文件与沙盒、抓包与定位、备份与诊断、网页界面分组。

用法 kxdevice <命令> [子命令] [参数]。kxdevice 负责与 iPhone 交互，包括查看设备、安装 App、启动、转发调试端口、拉取日志和文件。工程与构建见 kxbuild。每条命令都有 --help。

全局参数	说明
--udid UDID	指定设备，不填用第一台连接的
--connection-type USB\|Network	指定连接方式，不填优先 USB
--json	机器可读的 JSON 输出
-v, --verbose	详细日志
--no-setup	缺设备服务时不自动运行 setup

> kxdevice device list

命令总表

命令	作用
doctor	准备并检查与 iOS 设备通信所需的环境
device list / info / listen	列出设备、查看设备信息、监听插拔
pair、devmode、ddi	配对记录、开发者模式、开发者镜像
install、apps	安装 .ipa 或 .app，列出、查询、卸载 App
apps launch / kill / ps、screenshot	启动、结束、进程列表、截图
debug、forward、symbols	转发调试端口给 LLDB，端口转发，设备符号文件
syslog、ostrace、crash	系统日志、os_log、崩溃报告
file、sandbox	媒体分区文件操作，查看 App 沙盒
pcap、location	抓取设备网络包，模拟 GPS 位置
provisioning、profiles	设备上的描述文件、配置描述文件
backup / restore、diagnostics	备份恢复、电量与重启
web	本机网页界面

性能采样命令 instruments sysmon、netmon、energy、allocations、fluidity、stackshot、har 等见性能分析。

设备与配对

doctor

kxdevice doctor

准备并检查与 iOS 设备通信所需的环境。其他命令缺设备服务时会自动运行它，很少需要手动执行。

系统	说明
Windows	启动 Apple 移动设备服务，没安装时请先从 Microsoft Store 安装并打开「Apple 设备」，需要一次管理员授权
WSL	确保 Windows 侧的 Apple 服务在运行，并安装和启动 Windows 侧的中转服务，WSL 通过它访问手机。WSL 内不需要 root
Linux	安装 usbmuxd 和 udev 规则并启动服务，需要 sudo
macOS	重启系统自带的 usbmuxd

device list / info / listen

kxdevice device list · kxdevice device info · kxdevice device listen

list 列出连接的设备，包括 UDID、连接方式、型号、iOS 版本和名字，第一列的 UDID 是 Development 描述文件要包含的。info 打印所选设备的详细属性。listen 持续输出插拔事件，Ctrl-C 停止。kxdevice info 打印常用设备信息的精简版。

> kxdevice --udid 00008030-000A1B2C3D4E5F6G device info

pair list / delete / export-p12

kxdevice pair list · kxdevice pair delete <udid> · kxdevice pair export-p12 [-o FILE] [--password PWD]

管理本机保存的配对记录。手机上点过「信任此电脑」后记录就保存下来，delete 删除后下次连接会重新弹出信任提示，export-p12 把配对用的证书和私钥导出为 PKCS#12，例如供 Wireshark 解密。

devmode reveal / enable / accept

kxdevice devmode reveal · kxdevice devmode enable · kxdevice devmode accept

iOS 16 起调试必须打开开发者模式。reveal 让「设置 → 隐私与安全性」中出现开发者模式开关，enable 打开它，手机会重启，重启后要在手机上确认，accept 替你确认那个提示。

ddi status / list / mount / unmount / auto-mount

kxdevice ddi auto-mount · kxdevice ddi status · kxdevice ddi list · kxdevice ddi mount DMG_PATH · kxdevice ddi unmount

调试、截图、启动 App 都要先挂载开发者磁盘镜像。auto-mount 按设备的 iOS 版本选择镜像并挂载，iOS 17 起会下载并按设备个性化，debug 前自动执行。status 查看开发者模式状态，list 查看已挂载的镜像，mount 挂载指定的 .dmg，旁边要有 .signature，unmount 卸载。

安装与 App

install

kxdevice install <IPA 或 .app 目录>

安装 .ipa 或未打包的 .app 目录。包必须签过名且描述文件包含这部手机，见证书与签名。kxbuild build --install 构建完就是调用它。

> kxdevice install .\build\MyApp.ipa

apps / apps lookup / apps uninstall

kxdevice apps [--type User|System] [--file-sharing] · kxdevice apps lookup BUNDLE_ID · kxdevice apps uninstall BUNDLE_ID

列出已安装的 App 和 Bundle ID，--type 默认只列用户安装的 App，--file-sharing 只列开启了文件共享的。lookup 打印一个 App 的详细信息，uninstall 卸载。

> kxdevice apps uninstall com.example.myapp

启动、截图与进程

apps launch / kill / ps

kxdevice apps launch BUNDLE_ID · kxdevice apps kill BUNDLE_ID|PID · kxdevice apps ps [--apps]

launch 启动已安装的 App 并打印 pid，kill 按 Bundle ID 或 pid 结束，ps 列出设备上正在运行的进程，--apps 只列 App。

> kxdevice apps launch com.example.myapp

instruments sysmon

kxdevice instruments sysmon [-i 间隔] [-n 次数]

持续输出 CPU 占用。其余采样命令见性能分析。

screenshot

kxdevice screenshot [-o FILE]

截一张 PNG，不指定 -o 时文件名为 screenshot_日期_时间.png。

调试与符号

debug

kxdevice debug [-b <.app|.ipa>] [-B <bundleID>] [-p 端口] [参数]

把设备上的调试服务端口转发到本机 TCP 端口，供 LLDB 连接。VS Code 中见断点调试。指定 -b 时先安装再启动，只指定 -B 时启动已安装的 App，都不指定时只做端口转发，配合 --attach-pid 附加到运行中的进程。启动后打印 pid、端口和符号目录，Ctrl-C 停止转发。

参数	说明
-b, --bundle PATH	要安装的 .app 目录或 .ipa
-B, --bundle-id ID	App 的 Bundle ID，指定 -b 时从它的 Info.plist 推导
-p, --port N	本机监听端口，0 或不填随机选一个空闲的
-a, --args "…"	启动参数，空格分隔
-e, --env "K1=V1 K2=V2"	额外环境变量
-w, --wait	启动后挂起在入口等待调试器附加，Flutter 必须带
-H, --hide	在后台启动
-k, --kill	调试结束时退出 App
--attach-pid N	附加到已在运行的进程，不安装不启动
-m, --no-install	指定了 -b 也不安装
--no-launch	不启动，只转发端口

> kxdevice debug -B com.example.myapp -p 5678 -k

转发只监听 127.0.0.1，不要写 localhost，它可能解析到 IPv6 导致连不上。debug 进程在标准输入关闭时退出，放到后台运行要让 stdin 保持打开，例如 sleep 600 | kxdevice debug …。

forward

kxdevice forward LOCAL_PORT DEVICE_PORT

把本机 127.0.0.1:LOCAL_PORT 转发到设备上的 DEVICE_PORT，Ctrl-C 停止。Flutter 的 Dart VM 服务和自定义调试服务都通过它。

symbols list / download / path

kxdevice symbols list · kxdevice symbols download [-o DIR] [--no-extract] [--keep-cache] · kxdevice symbols path

调试手机app 需要系统库的符号库，每个 iOS 版本下载一次，几GB，需要点时间。download 从设备获取设备符号表，中断后再运行会继续。path 打印这部设备的符号目录，list 列出设备上可获取的文件。输出根目录依次取 -o、配置文件中的 symbol_cache、~/Library/Developer/Xcode/iOS DeviceSupport。

日志与崩溃

syslog

kxdevice syslog

实时输出设备系统日志，Ctrl-C 停止。输出量很大，配合 findstr 或 grep 使用。

ostrace

kxdevice ostrace [--levels …] [--pid N] [--subsystem S] [--match S] [--exclude S]

实时输出 os_log，NSLog 和 Logger 都经过它，比 syslog 干净，支持过滤。

参数	说明
--levels default,info,debug,error,fault	只输出这些级别，逗号分隔
--pid N	只看这个进程，-1 为全部
--subsystem S	子系统名包含 S
--match S / --exclude S	消息必须包含或不能包含 S

> kxdevice ostrace --subsystem com.example.myapp --levels error,fault

crash list / pull

kxdevice crash list [PATTERN] · kxdevice crash pull DIR [PATTERN]

列出设备上的崩溃报告，或下载到 DIR。PATTERN 是文件名通配，默认全部。

> kxdevice crash pull .\crashes MyApp*

文件与沙盒

file

kxdevice file <ls|stat|tree|get|put|mkdir|rm|rm-rf|mv|df> …

操作设备的媒体分区，即照片、下载等公共区域，不是 App 沙盒。

子命令	说明
ls [PATH] / tree [PATH]	列出目录或递归列出目录，默认根目录
stat PATH	文件元数据
get REMOTE [LOCAL]	下载，LOCAL 默认同名，写 - 输出到标准输出
put LOCAL REMOTE	上传
mkdir / rm / rm-rf / mv	建目录、删文件或空目录、递归删、改名
df	空间占用

sandbox ls / tree / documents

kxdevice sandbox ls BUNDLE_ID [PATH] · kxdevice sandbox tree BUNDLE_ID [PATH] · kxdevice sandbox documents BUNDLE_ID

查看 App 沙盒中的文件，默认 /Documents。documents 列出开放给文件共享的 Documents/。只对自己签名安装的 App 有效。

> kxdevice sandbox tree com.example.myapp /Library

网络与定位

pcap

kxdevice pcap [FILE.pcap] [--pid N] [--proc 名字前缀]

把设备的网络包抓取为 libpcap 文件，Wireshark 可直接打开，可按进程 pid 或名字过滤，Ctrl-C 停止。HTTP 级别的抓包见性能分析的 har。

location set / reset

kxdevice location set 纬度经度 · kxdevice location reset

模拟 GPS 位置，reset 恢复真实定位。

描述文件

provisioning list / export

kxdevice provisioning list · kxdevice provisioning export DIR

列出设备上已安装的 .mobileprovision 描述文件，或全部导出到 DIR。

profiles list / install / remove / cloud-config

kxdevice profiles list · kxdevice profiles install FILE.mobileconfig · kxdevice profiles remove IDENTIFIER · kxdevice profiles cloud-config

管理 .mobileconfig 配置描述文件，如证书、代理、MDM 设置。列出、安装（手机上需要确认）、按标识删除，cloud-config 查看监管状态。

备份、诊断与其它

backup / restore

kxdevice backup <目录> [--full] · kxdevice restore <目录> [--system] [--password PWD] [--preserve-settings] [--remove-items] [--reboot=false] [--copy-backup=false]

整机备份到目录，默认增量，--full 强制全量。恢复默认完成后重启并把备份复制到设备，加密备份用 --password。

diagnostics battery / gestalt / reboot / shutdown / sleep

kxdevice diagnostics battery · kxdevice diagnostics gestalt KEY… · kxdevice diagnostics reboot | shutdown | sleep

电量读数、查询设备属性如 ProductType 和 RegionInfo、重启、关机、休眠。

lockdown / notify / icons / prepare / test / version

网页界面

kxdevice web [--addr :8780]

在本机启动网页界面和 REST 服务，设备、App、日志、截图、性能采样都可以在浏览器中操作。默认监听 8780 端口，Ctrl-C 停止。

> kxdevice web --addr 127.0.0.1:8780

接下来

kxbuild 命令参考

kxbuild 的全部子命令与参数，包括 doctor、build、resolve、project、update、version。