remote-iterm2
通过手机浏览器，在局域网内远程控制 Mac 上的 iTerm2 终端。实时输出、语法着色、多窗口管理、分屏对比、广播命令——全部在你的掌心中。
快速开始
安装
启动 / 停止 / 重启
remote-iterm2 stop # 停止服务
remote-iterm2 restart # 重启服务
http://192.168.1.119:7291，用手机 Safari 打开即可（需与 Mac 处于同一 Wi-Fi）。
系统要求
| 项目 | 要求 |
|---|---|
| macOS | 需安装 iTerm2 |
| Node.js | >= 18 |
| Port | 7291（HTTP + WebSocket 共用） |
| Mobile | 与 Mac 处于同一局域网 |
界面总览
顶部状态栏
3.1 连接状态指示灯
| 颜色 | 含义 |
|---|---|
| ● 绿色（光晕动画） | 已连接到 Mac |
| ● 红色 | 连接断开，自动重连中 |
断开时全屏出现半透明遮罩并显示 RECONNECTING，自动重连，无需手动刷新。
3.2 延迟显示（ms）
每 5 秒自动测量往返延迟，颜色区分网络质量：
| 颜色 | 延迟范围 | 网络状态 |
|---|---|---|
| 绿色 | < 50ms | 良好 |
| 黄色 | 50–149ms | 一般 |
| 红色 | ≥ 150ms | 较差 |
3.3 ALERT — 长命令完成提醒
点击 🔔 图标切换。开启后（黄色高亮），当终端输出停止超过 4 秒，手机会震动提醒（双次短振）。适合等待编译、下载等耗时命令时使用。
3.4 SCROLL — 滚动锁定
锁定（红色）：终端内容不会自动滚动，可自由查看历史。解锁（默认）：有新输出时自动滚动到最新行。
3.5 CAST — 广播模式
点击 📡 图标切换。开启后（紫色高亮），命令同时广播到多个窗口。详见 第 8 节。
3.6 SPLIT — 分屏视图
点击 ⊟ 图标切换。开启后（蓝色高亮），屏幕分为两个独立终端面板。详见 第 6 节。仅有一个 Session 时此按钮变灰禁用。
3.7 N win — 窗口切换
显示当前 iTerm2 窗口总数（如 "2 win"）。点击弹出窗口地图可切换窗口。只有 1 个窗口时按钮变灰禁用。
标签页管理栏
| 操作 | 说明 |
|---|---|
| 切换标签页 | 点击标签名，活跃标签以绿色下划线高亮。 |
| 重命名标签页 | 长按标签名约 0.5 秒，弹出输入框，输入新名称后回车确认。 |
| 新建标签页 | 点击标签栏最右侧 ＋ 按钮，在 iTerm2 新建标签页。 |
| 关闭标签页 | 点击标签栏最右侧 ✕ 按钮，关闭当前标签（仅剩 1 个时自动禁用）。 |
终端内容区
5.1 语法着色规则
终端输出按内容类型自动着色，方便快速识别关键信息：
| 颜色 | 代表内容 |
|---|---|
| 亮白色（粗体） | 当前命令提示行（最后一行） |
| 青色（粗体） | Shell 提示符（user@host $、%、# 等） |
| 红色 | 错误信息（error、FAIL、fatal、ENOENT 等） |
| 黄色 | 警告信息（warning、WARN、deprecated 等） |
| 绿色 | 成功信息（success、done、compiled、OK 等） |
| 紫蓝色 | 文件路径（/、~/、./ 开头）及目录树符号 |
| 浅绿色 | Git diff 新增行（+ 开头） |
| 粉红色 | Git diff 删除行（- 开头） |
| 暗灰色 | 注释行（# 开头） |
| 浅灰色 | 普通输出 |
5.2 光标
终端末尾显示 绿色闪烁方块光标 █（仅在 Shell 提示符状态下出现）。运行交互式应用（vim、htop 等）时光标自动隐藏。
5.3 滚动查看
在终端区域上下滑动查看历史输出。开启滚动锁定后，新输出不会打断浏览。
分屏视图
同时查看两个不同 Session 的终端输出，适合对比日志、同时监控多个进程。
| 操作 | 说明 |
|---|---|
| 开启分屏 | 点击 SPLIT 按钮（需至少 2 个 Session）。主面板 绿色边框，分屏面板 蓝色边框。 |
| 布局方向 | 竖屏上下分屏；横屏左右分屏。 |
| 调整比例 | 拖动分隔条，可调整主面板与分屏面板比例（20%–80%）。 |
| 切换焦点 | 点击任意面板，边框变亮即为焦点面板，后续命令发送到该 Session。 |
| 分屏标签栏 | 分屏面板有独立标签栏，支持切换标签、新建/关闭，可为分屏面板选择不同窗口。 |
| 关闭分屏 | 再次点击 SPLIT 按钮，恢复单面板模式。 |
窗口地图
点击 N win 按钮打开窗口地图。弹出半透明全屏遮罩，按比例还原各 iTerm2 窗口在屏幕上的实际位置和大小。
| 功能 | 说明 |
|---|---|
| 切换窗口 | 点击窗口编号块切换，地图自动关闭；点击遮罩空白区域取消。 |
| 广播目标选择 | 广播模式下变为多选模式，紫色高亮 = 已选为广播目标。 |
广播模式
将同一条命令同时发送到多个 iTerm2 窗口，适合批量操作多台服务或多个项目。
| 步骤 | 说明 |
|---|---|
| 1. 开启广播 | 点击 CAST 按钮（默认选中所有窗口），标签栏下方出现 紫色横幅。 |
| 2. 选择目标 | 点击横幅右侧 EDIT，在窗口地图多选模式中勾选目标窗口。 |
| 3. 发送命令 | 输入框提示符变为 >，发送后命令同时发至所有目标窗口。 |
| 4. 关闭广播 | 再次点击 CAST 按钮，恢复单窗口发送。 |
快捷操作栏
位于终端内容区下方，提供高频终端操作的一键按钮，无需展开键盘即可操作。
9.1 控制键
| 按钮 | 功能 | 发送字符 |
|---|---|---|
| ↵ Enter | 发送回车 | \n |
| ESC | 发送 Escape 键 | \x1b |
| ^C | 中断当前进程（Ctrl+C） | \x03 |
| ^D | 发送 EOF / 退出（Ctrl+D） | \x04 |
| ^Z | 挂起进程到后台（Ctrl+Z） | \x1a |
| ^L | 清屏（Ctrl+L） | \x0c |
9.2 光标导航键
| 按钮 | 功能 |
|---|---|
| ↑ 上箭头 | 上方向键（浏览历史命令 / 菜单导航） |
| ↓ 下箭头 | 下方向键 |
| TAB | 发送 Tab 键（自动补全） |
| ⇧TAB | 发送 Shift+Tab（反向补全 / 反向切换选项） |
9.3 剪贴板操作
| 按钮 | 功能 |
|---|---|
| 📋 粘贴 | 从手机剪贴板读取内容，直接发送到终端 |
| 复制 | 将当前终端内容全部复制到手机剪贴板 |
| 🗑️ 清除行 | 清除当前命令行输入（Ctrl+U） |
命令输入区
10.1 命令输入框
输入框左侧提示符：$ 普通模式 → 当前焦点 Session；> 广播模式 → 所有选中窗口。已禁用自动纠错和首字母大写，适合终端命令输入。
10.2 发送命令
点击右侧发送按钮，或按键盘 Return 键。发送后命令自动保存到历史（最多 100 条，存于浏览器 localStorage）。
10.3 命令历史导航
| 操作 | 效果 |
|---|---|
| 按 ↑ 方向键 | 向历史前翻（更早的命令） |
| 按 ↓ 方向键 | 向历史后翻（更近的命令），回到底部恢复原始输入 |
10.4 切换虚拟键盘
点击输入区左侧的键盘图标，切换到内置虚拟键盘模式（详见 第 11 节）。
虚拟键盘
专为终端操作设计的内置软键盘，提供字母、数字及常用符号布局，无需依赖系统键盘。
11.1 进入 / 退出
进入：点击命令输入区左侧的键盘图标。
退出：点击虚拟键盘左下角的 Terminal 图标，返回命令输入框。
11.2 三种键盘布局
| 模式 | 内容 | 切换方式 |
|---|---|---|
| ABC（字母） | 标准 QWERTY，含 SHIFT（单次大写）和 DEL | 默认 |
| 123（符号） | 数字 0–9、/ . ~ * $ | > < & ; = " ' \ ` # 等 | 按 123 键 |
| #+=（高级） | ! @ % ^ + = ? : ( ) [ ] { } , ; " ' ` ~ \ _ 等 | 符号模式下按 #+= 键 |
11.3 底部功能行
| 按钮 | 功能 |
|---|---|
| 🖥️ Terminal | 退出虚拟键盘，返回命令输入框 |
| ABC / 123 | 字母 / 符号模式切换 |
| - | 快速输入连字符 |
| SPACE | 发送空格 |
| . | 快速输入句点 |
| ↵ | 发送回车 |
颜色语义说明
整个界面使用统一的颜色系统，便于快速识别状态：
PWA 安装
将 remote-iterm2 添加为手机主屏幕应用，获得全屏无浏览器栏的沉浸体验：
- 在 iPhone Safari 中打开应用 URL（如 http://192.168.1.119:7291）
- 点击底部分享按钮 → 添加到主屏幕
- 确认名称后点击添加
配置说明与常见问题
配置文件
在 Mac 上创建 ~/.remote-iterm2.json 可自定义行为：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| tabColor | true | 切换窗口时自动改变 iTerm2 标签背景色。设为 false 可保留手动颜色。 |