Tamagui iOS 原生开发实战基于 kitchen-sink 的 Detox 测试与模拟器调试指南【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui本篇指南以 Tamagui 仓库内 docs/using-ios.md 为骨架结合仓库中真实运行 Detox E2E 测试的 kitchen-sink 示例应用系统讲解 iOS 原生开发环境下的测试启动、模拟器管理、日志排查与调试技巧。读完你将掌握一套可直接落地的「独立 Metro 单测快速迭代 simctl 模拟器管理 Metro 日志过滤」工作流用于 Tamagui 原生组件的日常开发与回归验证。环境准备跑通 Detox 前的依赖检查docs/using-ios.md中的命令都围绕code/kitchen-sink这个演示应用展开它是一个同时支持 Web 与 iOS/Android 的 Tamagui 示例工程。在运行测试前仓库提供了两个关键入口package.json 中声明了detox20.47.0、jest、react-native0.86.2、expo~57.0.10等依赖以及detox:build:iosbun run pod detox build -c ios.sim.debug、detox:run:ios./run-detox.sh ios等脚本run-detox.sh 是完整的测试运行器其前置检查逻辑check_prerequisites明确列出了 iOS 平台的两个硬性依赖# 1. detox-cli全局命令行工具 npm install -g detox-cli # 2. applesimutilsDetox 操作 iOS 模拟器的底层工具 brew tap wix/brew brew install applesimutils从 run-detox.sh 的源码看首次运行还会自动处理两件事若$HOME/Library/Detox/ios/framework缓存缺失常见于 Xcode 升级后会执行npx detox clean-framework-cache npx detox build-framework-cache重建框架缓存若ios/目录不存在会自动执行npx expo prebuild --platform ios生成原生工程。此外 iOS 构建前需要先执行 CocoaPods 安装bun run pod即./pod-install.sh。Metro 设置独立运行打包器以加速迭代文档推荐将 Metro 与 Detox 分离独立启动 Metro 可以显著加快迭代速度——每次改动只触发增量打包而不是重建整个 App。在 kitchen-sink 目录下执行cd code/kitchen-sink bun run start /tmp/metro.log 21 要点说明bun run start实际执行的是EXPO_NO_TELEMETRYtrue expo start --dev-client --offline见 package.json其中--dev-client表明该应用通过 Expo dev client 加载开发包--offline避免联网拉取远端 bundle输出重定向到/tmp/metro.log是为了让 Metro 在后台持续运行同时保留完整日志供后续grep排查将进程放入后台。仓库的 run-detox.sh 也遵循同样思路它会先探测端口上是否已有 Metro 在运行curl -s http://localhost:${DETOX_METRO_PORT}/status没有才后台拉起并在测试结束后自动清理自己启动的 Metro 进程。Metro 就绪后运行 Detox 时加上--reuse即可复用现有 Metro 与已安装的 App跳过重复构建npx detox test -c ios.sim.debug --reuse单测试工作流开发期的推荐模式日常调试某个组件时最怕 Detox 默认并行启动 10 个模拟器既吵又难定位。文档给出的推荐做法是强制单 worker# 在单个模拟器上跑单个测试快速迭代 npx detox test -c ios.sim.debug --reuse --retries 0 --maxWorkers 1 -t test name--maxWorkers 1会阻止 Detox 并行拉起多个模拟器从而避免调试时的环境噪声。这与仓库配置完全一致从 .detoxrc.js 可以看到项目本身就强制将maxWorkers固定为 1并在注释中解释了原因——多 worker 会触发 ECOMPROMISED 锁文件错误对应 Detox issue #4210同时 jest.setup.ts 中通过jest.retryTimes(1)实现了「仅重试单个失败用例」的粒度避免 Detox 整文件级--retries造成的重复耗时。全量测试套件CI 或最终验证需要跑完整个测试套件做回归验证如提交前、CI 中时去掉--maxWorkers即可恢复并行npx detox test -c ios.sim.debug --reuse在实际仓库中更推荐直接使用封装好的入口脚本它会自动完成「检查 pods → 检测是否需要重建 → 启动 Metro → 运行测试 → 清理 Metro」的全流程bun run detox:run:ios # 运行全部 iOS 测试 bun run detox:run:ios Sheet # 只运行名称匹配 Sheet 的测试从 run-detox.sh 的needs_rebuild函数看它会智能判断是否真的需要重建App 二进制不存在、Podfile.lock或package.json比 App 新、或设置了FORCE_BUILD1时才触发detox:build:ios若 App 已安装在当前激活的模拟器上则自动追加--reuse避免重复安装。常用环境变量包括FORCE_BUILD1强制重建、SKIP_BUILD1跳过构建检查、SKIP_METRO1假设 Metro 已运行、DETOX_DEVICEname指定模拟器型号默认 iPhone 16、DETOX_METRO_PORTn专用 Metro 端口默认 9034用于避免与日常开发服务器冲突。Detox 常用 Flags 速查Flag作用建议场景--retries 0失败立即终止不做整文件重试本地调试快速暴露真实失败-t test name按测试名称精确运行定位某个具体用例--reuse复用现有 Metro / 已安装的 App日常迭代跳过重建--maxWorkers 1只使用单个模拟器调试时保持安静环境--headless无模拟器 UI 界面运行CI 环境专用组合示例文档原文运行键盘相关测试npx detox test -c ios.sim.debug --reuse --retries 0 --maxWorkers 1 -t sheet drag test管理模拟器simctl 实用命令Detox 运行一段时间后会遗留大量模拟器进程文档给出了完整的 simctl 管理命令# 列出所有模拟器 xcrun simctl list devices # 关闭所有模拟器 xcrun simctl shutdown all # 启动指定模拟器 xcrun simctl boot iPhone 15 # 擦除模拟器恢复全新状态 xcrun simctl erase iPhone 15 # 清理不可用的模拟器如旧 Xcode 版本遗留 xcrun simctl delete unavailableerase非常适合在状态异常、缓存污染时使用——它会将模拟器恢复到出厂状态代价是需要重新安装 App。delete unavailable则是清理磁盘空间的常用手段它只会删除当前 Xcode 无法使用的遗留模拟器。模拟器卡在 Shutting Down 状态的应急处理当模拟器陷入关机僵局时文档给出了三步强制恢复流程# 强制杀掉所有模拟器进程 killall Simulator 2/dev/null xcrun simctl shutdown all sleep 2 xcrun simctl boot iPhone 15killall Simulator会直接终止 Simulator.app 的所有进程2/dev/null用于忽略「无进程可杀」时的报错随后统一关机再重新启动目标模拟器。如果依然无法启动可以再叠加xcrun simctl erase重置或通过xcrun simctl list devices确认目标设备是否仍处于可用状态。调试工作流从日志到截图的五步法文档总结了原生端调试的五个高效习惯跳过已验证的测试利用-t test name只跑本次改动的用例缩短反馈回路原生代码用console.warn()而非console.log()在 Metro 输出中warn级别的日志更醒目不容易被淹没也便于grep过滤过滤 Metro 日志由于 Metro 输出已重定向到/tmp/metro.log可以随时精准检索grep -E pattern /tmp/metro.log在测试中截图await device.takeScreenshot(name)查看截图产物运行结束后在e2e/artifacts/目录检查截图。第 4、5 步与仓库配置一一对应从 .detoxrc.js 可以看到 artifacts 的rootDir被配置为./e2e/artifacts插件开启了screenshot: failing失败自动截图与uiHierarchy: enabled记录 UI 层级手动调用device.takeScreenshot()的截图也会落入同一目录。在 e2e 的多个测试中都能看到这一实践例如 Accordion.test.ts 中通过device.takeScreenshot(accordion-default-open)等调用记录交互前后的界面状态。实战案例键盘与 Sheet 手势协同测试文档给出的示例场景是「键盘与 Sheet 手势之间的平滑交接」——这是 iOS 原生交互中典型的痛点。对应的测试文件是 SheetKeyboardDrag.test.ts它覆盖了六个用例打开 Sheet 时键盘隐藏、点击输入框键盘弹出且 Sheet 平滑上移、点击外部收起键盘后 Sheet 恢复原位、键盘弹出时下拉 Sheet 应先收起键盘、输入框间切换保持键盘常驻、关闭 Sheet 连带收起键盘。运行键盘相关测试detox test --reuse --retries 0 -t Keyboard同时观察键盘事件grep -E keyboard|Keyboard|kb- /tmp/metro.log从该测试源码可以印证文档中调试要点的实际用法用例通过await device.takeScreenshot(case2-before-keyboard)等在关键节点留档通过读取带sheet-keyboard-drag-kb-visibletestID 元素的文本断言键盘可见性并在console.log中输出键盘高度等运行时数据最终在 Metro 日志中过滤查看。需要说明的是从源码注释看这个测试文件目前仍处于 WIP 状态describe.skip原因是react-native-keyboard-controller的持续主线程轮询会干扰 Detox 的同步机制。仓库为此在 e2e/utils/detox.ts 中提供了一套safeLaunchApp/safeReloadApp封装默认通过disableKeyboardController: true启动参数禁用键盘控制器、启动后立即device.disableSynchronization()只有真正需要键盘的用例才显式传入disableKeyboardController: false同时为启动流程设置了多重超时兜底连接超时 70 秒、恢复预算 165 秒并内置「启动失败熔断」机制避免单个模拟器失联拖垮整个测试文件。这套模式同样值得你在自己的 Detox 项目中借鉴。小结这套 iOS 原生开发工作流的核心可以归纳为三点Metro 独立后台运行 --reuse跳过重复构建让每次迭代只付出增量打包的代价--maxWorkers 1-t精确锁定用例把调试环境噪声降到最低simctl 命令族 /tmp/metro.log过滤 artifacts 截图实现模拟器与运行时状态的可观测、可恢复。配合仓库内 run-detox.sh 与 .detoxrc.js 提供的自动化与智能重建判断无论是本地日常调试还是 CI 全量回归都能获得稳定且高效的测试体验。【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
