企业官网建设流程全解析

tapflow 是一款自托管的 iOS 模拟器 / Android 模拟器流式工具，让 QA、产品经理、设计师等团队成员直接在浏览器里操作 Mac 上的模拟器。本文以tapflow setup为核心，带你一步步完成 Xcode、iOS 模拟器运行时与 Android SDK 环境的一键引导，从零搭建可运行的模拟器测试环境。

开始前的环境要求清单

在运行tapflow setup之前，先确认你的 Mac 满足以下条件。完整说明见 docs/operate/requirements.md：

⚠️ 注意：Agent 只支持 Apple Silicon Mac，Intel Mac 会报spawn unknown error；而 Relay 服务没有这个限制，跑在任意服务器上都可以。

三步引入：安装 tapflow 命令

安装只需一行命令，支持 npm / yarn / pnpm 三种包管理器：

npm install -g tapflow # 或：yarn global add tapflow ｜ pnpm add -g tapflow

💡 如果缺少 Node.js，可以先安装 Node.js 22 或更高版本。

安装完成后，就可以进入本文的主角——环境引导。

一键环境配置：tapflow setup 自动做了什么

在将运行模拟器的 Mac 上执行：

tapflow setup

tapflow setup会自动检测环境并安装缺失的部分；每个需要安装系统组件的步骤执行前都会先征求你的同意，全程交互式引导，无需手动翻文档。也可以只配置单一平台：tapflow setup ios或tapflow setup android。命令逻辑位于 packages/cli/src/commands/setup.ts，具体流程实现在 packages/cli/src/lib/setup.ts。

iOS 篇：Xcode 与 iOS 模拟器自动引导

tapflow setup ios会自动完成以下工作：

• Homebrew：缺失时自动安装；
• Xcode：setup 无法直接安装 Xcode，会自动为你打开 App Store，安装完成后按 Enter 即可继续；
• Xcode 激活：接受许可协议并执行首次启动配置（xcode-select、xcodebuild -runFirstLaunch），此步需要管理员密码；
• iOS 模拟器运行时：尚无可用设备时自动下载；
• 音频权限：预先申请模拟器音频捕获权限，用于把设备声音传回浏览器；
• 网络过滤器：安装 iOS 网络控制所需的系统扩展，macOS 会弹出系统扩展审批窗口，记得点「允许」。

📌 若系统扩展审批被跳过，setup 会以SETUP INCOMPLETE结束并列出遗留项——除此之外，其他功能均不受影响。

Android 篇：Android SDK 与 AVD 自动创建

tapflow setup android会在后台构建一套自包含的 Android 环境：

• JDK：通过brew install --cask temurin安装运行 SDK 工具所需的 JDK；
• Android SDK：在~/Library/Android/sdk下创建完整 SDK，包含 command-line tools、platform-tools（adb）、emulator、build-tools（aapt）与系统镜像——全程不需要 Android Studio 图形界面；
• AVD 模拟器：自动创建 4 台覆盖不同形态的设备（小屏 / 标准 / 大屏手机 + 平板），方便多分辨率测试。

💡 setup 会把ANDROID_HOME和 PATH 写入你的 shell 配置，但当前终端不会立即生效——开一个新终端（或执行exec $SHELL），再用tapflow doctor验证。

验证环境是否就绪：tapflow doctor 体检

setup 完成后，运行一次「体检」确认所有组件就绪：

tapflow doctor

doctor会逐项检查并给出✓ ready、⚠ attention、✗ needs install三种状态：

📌 检查逻辑见 packages/cli/src/lib/doctor.ts。如果 Relay 已在本机运行，「Port 4000」一项会失败——这是正常的，可以忽略。支持tapflow doctor --json输出机器可读结果，方便接入 CI。

启动 Relay 与 Agent：tapflow start 一键拉起

环境与安装都就绪后，在同一台 Mac 上启动本地模式（Relay + Agent 一起跑）：

tapflow start

启动成功后会看到类似这样的横幅：

→ Relay started on http://localhost:4000 ✓ Connecting ios agent… ┌─────────────────────────────────────────────┐ │ ✓ TAPFLOW READY │ └─────────────────────────────────────────────┘ Relay : http://localhost:4000 Open http://localhost:4000 in your browser.

接着只需两步：

1. 浏览器打开http://localhost:4000，首次访问会跳转到/setup页面，创建第一个管理员账号（无浏览器环境可用tapflow admin init）；
2. 登录 Dashboard，上传你的.app.zip/.apk构建包，点击Start QA选择 Mac 和设备，即可在浏览器里实时点击、滑动、输入。

此时，QA 会话中模拟器会按需自动启动——setup 只负责准备「可启动」的设备，真正开机由 Relay 在有人打开会话时自动完成，无需手动 boot。

可选进阶：tapflow init 配置隧道与 HTTPS

如果默认配置（端口 4000、局域网、HTTP）够用，可以跳过这步。需要外部访问或更流畅的硬件解码流时，运行：

tapflow init

它会引导你选择：

• Tunnel：None（仅局域网）/ Tailscale（加密组网，无需 VPS）/ rathole（自建 VPS 公网地址）；
• Streaming：Standard（HTTP 软解，即时可用）或 Smooth（HTTPS + WebCodecs 硬件解码，更流畅）；
• Lean 模式：精简模拟器后台服务，iOS 模拟器内存可省约 1/4。

详细说明见 docs/operate/configure.md。

常见问题快速排查

更多条目见 docs/troubleshooting/install-and-agents.md，环境引导全流程细节见 docs/operate/environment-setup.md。

小结

整套流程可以浓缩为四条命令：

1. npm install -g tapflow—— 安装工具；
2. tapflow setup—— 一键引导 Xcode、iOS 模拟器运行时、Android SDK 与 AVD；
3. tapflow doctor—— 体检确认环境就绪；
4. tapflow start—— 启动 Relay 与 Agent，浏览器打开http://localhost:4000即可开工。

配置完成后，团队任何人都能直接在浏览器里测试你的构建，构建包与录屏数据全部保留在你自己的基础设施上。下一步可以阅读 docs/get-started/quick-start.md 学习上传构建包、发起 QA 会话和邀请团队成员。