Detox 完全卸载指南：清理框架缓存、测试状态与设备残留的检查清单

• 测试
• 移动开发
• 质量保障
• 开发工具

本指南基于 Detox 20.x 版本官方文档整理，系统梳理了在 macOS / Linux / Windows 上彻底卸载 Detox 时需要处理的全部"副作用"：框架缓存、会话状态文件、克隆模拟器、测试产物残留以及 CLI 工具本身。读完本文，你将掌握一套可复制、可验证的干净卸载流程，并能对照源码理解每个残留文件与命令的底层作用，避免测试环境被历史遗留数据污染。

为什么 Detox 卸载不是"删除 node_modules"这么简单

Detox 作为灰盒端到端测试框架，其运行机制决定了它会在用户机器上留下多种痕迹：

• 安装时通过postinstall脚本编译并缓存Detox.framework；
• 每次测试运行时改写设备注册表、全局锁文件等状态文件；
• 在 iOS 上为多 worker 并发自动克隆模拟器实例；
• 异常退出时残留日志、截图等临时产物；
• 若安装了独立 CLI 包，还需要单独卸载。

在 detox/scripts/postinstall.js 中可以确认安装阶段的行为：在 macOS 平台上，postinstall会依次执行build_local_framework.ios.sh与build_local_xcuitest.ios.sh，把 Detox 框架与 XCUITest 运行器编译进缓存目录；同时patchGradleByRNVersion()会按 React Native 版本修正 Android Gradle 配置。该脚本还支持通过环境变量DETOX_DISABLE_POSTINSTALL跳过安装阶段的工作（见 detox/package.json 中的"postinstall": "node scripts/postinstall.js"）。

因此，"干净卸载"应当覆盖以下五类残留，本文按官方卸载清单逐项展开。

Detox 框架缓存（Framework Cache）

每次安装 Detox 时，postinstall脚本都会把Detox.framework构建（或解包）到~/Library/Detox目录。这是体积最大、最典型的残留物。

手动删除

直接删除缓存目录即可：

rm -rf ~/Library/Detox

使用官方命令清理

更推荐使用官方提供的 CLI 命令：

detox clean-framework-cache

从源码看，该命令由 detox/local-cli/clean-framework-cache.js 实现，其底层逻辑位于 detox/local-cli/utils/frameworkUtils.js 的clean()函数：

• 默认同时清理两个组件：getFrameworkDirPath()对应的~/Library/Detox/ios/framework（注入的 Detox 库）与getXCUITestRunnerDirPath()对应的~/Library/Detox/ios/xcuitest-runner（XCUITest 测试运行器）；
• 命令仅在 macOS 上生效，非 darwin 平台会打印提示并跳过执行（shouldSkipExecution()中对os.platform() !== 'darwin'的判断）；
• 支持按需选择性清理，两个布尔选项默认均为false：
  • --detox：仅清理注入的 Detox 框架；
  • --xcuitest：仅清理 XCUITest 测试运行器。

例如：

detox clean-framework-cache --detox

与之对应的detox rebuild-framework-cache（实现见 detox/local-cli/rebuild-framework-cache.js）则是先clean再build，适用于框架损坏或版本变更后需要重建缓存的场景。

测试会话状态文件（Test Session State）

每次测试运行时，Detox 都会在DETOX_LIBRARY_ROOT_PATH下改写若干临时文件。从 detox/src/utils/environment.js 可以看出，该根目录由appdatapath.appDataPath()拼上Detox子目录构成，具体包含：

1. device.registry.json—— 设备注册表，用于区分"忙碌中"与"可用"的设备，支撑多 worker 并发测试；
2. global-context.json.lock—— 全局锁文件，用于检测是否同时启动了多个 Detox 实例，防止并发冲突。

此外，源码中还可以看到同一目录下的其他状态文件：

• apps-cache/—— 按udid与bundleId组织的应用缓存目录；
• global-context.json—— 全局上下文文件（锁文件global-context.json.lock正是围绕它建立的）；
• last-failed.txt—— 最近一次失败的测试记录。

其中device.registry.json的实际消费方是 detox/src/devices/allocation/DeviceRegistry.js，它通过ExclusiveLockfile（见 detox/src/utils/ExclusiveLockfile.js）对注册表做互斥访问，保证多 worker 场景下设备分配的原子性。

各平台下DETOX_LIBRARY_ROOT_PATH的位置

DETOX_LIBRARY_ROOT_PATH的具体位置因操作系统而异，其判定逻辑完整实现在 detox/src/utils/appdatapath.js 中：

• macOS：~/Library/Detox；
• Linux：
  • 若定义了$XDG_DATA_HOME：$XDG_DATA_HOME/Detox；
  • 否则：~/.local/share/Detox；
• Windows：
  • 若定义了%LOCALAPPDATA%：%LOCALAPPDATA%\data\Detox；
  • 否则：%USERPROFILE%\Application Data\Detox。

做完整卸载时，可以手动删除对应路径下的device.registry.json、global-context.json*等状态文件，或直接清理整个 Detox 数据目录。

克隆的模拟器实例（macOS）

为了在 iOS 上支持"多 worker"并行特性，当可用模拟器数量不足时，Detox 会克隆模拟器实例。这些自动生成的模拟器名称带有-Detox后缀，便于识别。这一点在 detox/src/devices/common/drivers/ios/tools/AppleSimUtils.js 的create()方法中有直接体现：它执行simctl create "${deviceName}-Detox" ...来创建克隆实例。

找出克隆模拟器

xcrun simctl list | grep "-Detox"

删除指定模拟器

将上一步查到的 UUID 代入以下命令：

xcrun simctl delete <uuid>

simctl delete是 Xcode 自带的模拟器管理命令，会彻底移除指定 UDID 对应的模拟器及其数据。

测试产物残留（Artifacts Remnants）

强制退出（如 Ctrl+C、进程被杀）可能导致临时文件残留。按平台分别处理：

iOS

清除临时目录中的 Detox 产物（日志、截图等）：

rm -rf $TMPDIR/*.detox.*

如果需要把某个模拟器上安装的应用与自定义设置一并还原为出厂状态，可对其执行擦除：

xcrun simctl erase <uuid>

注意erase与delete的区别：erase保留模拟器本身、仅清空其内容与已安装应用；delete则移除整个模拟器。

Android

Android 虚拟设备（AVD）的处理思路与 iOS 一致。要擦除某个 AVD 的用户数据，运行：

emulator -avd <your_AVD> -wipe-data

若只需清理某个已启动设备上的 Detox 临时文件，可关注/sdcard目录下形如11159175_0.log的文件。这类文件遵循"数字下划线数字"的命名模式，可以用通配符批量删除（也可自行定制更精确的模式）：

adb -s <emulator-port> shell rm -rf /sdcard/*_*.*

其中<emulator-port>是 adb 连接模拟器所用的端口号（通常为5554、5556等，可通过adb devices查询）。

卸载独立 Detox CLI

若你通过全局方式安装过官方 CLI 包装包detox-cli（它与 Detox 主包分离，提供detox命令入口），请务必一并卸载：

npm uninstall detox-cli --global

该独立包的入口实现位于 detox-cli/cli.js。若你的detox命令来自项目本地依赖（node_modules/.bin/detox），则删除项目目录并重新安装依赖即可，无需执行此步。

卸载检查清单（速查）

完成一次彻底的 Detox 清理，建议按以下顺序核对：

上述所有命令、路径与文件名的依据均可回溯至仓库源码：detox/src/utils/appdatapath.js（平台路径判定）、detox/src/utils/environment.js（状态文件与缓存路径定义）、detox/local-cli/utils/frameworkUtils.js（缓存清理实现）以及 detox/src/devices/common/drivers/ios/tools/AppleSimUtils.js（克隆模拟器命名）。如果你还想了解与清理配套的构建命令，可参考 docs/cli/clean-framework-cache.md 中clean-framework-cache的完整选项说明。

• 测试
• 移动开发
• 质量保障
• 开发工具