# 快速入门

## 安装先决条件

若要使用默认的本地隧道设置，请在计算机上安装以下工具：

### Node.js 20+

从 [nodejs.org](https://nodejs.org) 下载，或使用你的包管理器。

```bash
# Check if installed
node --version
```

### tmux

为 Termbridge 会话提供支持的终端复用器。

```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

### cloudflared

创建通往终端的安全隧道（沙盒直连模式无需此工具）。

```bash
# macOS
brew install cloudflared

# Linux - see cloudflare.com/downloads
```

[下载 cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)


## 运行 Termbridge

```bash
npx termbridge
```

你会看到类似这样的输出：

```
┌─────────────────────────────────────────┐
│  Termbridge                             │
│                                         │
│  Local:   http://127.0.0.1:51234        │
│  Public:  https://abc123.trycloudflare.com │
│                                         │
│  ██████████████                         │
│  ██          ██  <- Scan this QR code   │
│  ██████████████                         │
│                                         │
└─────────────────────────────────────────┘
```

> **注意**
> `trycloudflare.com` URL 是一种快速、无需账户的隧道。如果你经常使用 Termbridge，
> 请设置命名 Cloudflare 隧道令牌，以避免速率限制。


## 通过手机连接

1. 打开手机相机
2. 将相机对准 QR 码
3. 点按出现的链接
4. 终端就会在浏览器中加载

就是这样——你已连接！

## 刚才发生了什么？

1. Termbridge 在你的计算机上启动了本地服务器
2. 它为你的终端创建了一个 tmux 会话
3. Cloudflare 创建了安全隧道（即 `trycloudflare.com` URL）
4. QR 码包含用于安全访问的一次性令牌。它只能使用一次，并会在启动 90 秒后过期，请及时扫描；如果已过期，请重启 Termbridge 获取新令牌
5. 扫描后，你会获得会话 Cookie 并连接成功

## 试用一下

连接后，试着运行一些命令：

```bash
# See system info
htop

# Check a git repo
cd ~/your-project && git status

# Run any CLI tool
```

终端支持完整色彩、TUI，以及你预期的所有按键。

## 保持运行

Termbridge 必须保持运行，连接才能正常工作。完成后：

- 在运行 Termbridge 的终端中按 `Ctrl+C`
- 隧道关闭，连接结束
- 你的 tmux 会话会继续运行（除非你使用了 `--kill-on-exit`）

## 首个会话的行为

- Termbridge 会创建一个 tmux 会话（默认名称根据端口生成）
- 列表中的第一个终端会自动加载
- 设置 `TERMBRIDGE_SESSIONS=2` 可在启动时创建多个会话

## 使用现有的 tmux 会话

如果你传入 `--session <name>` 且该会话已存在，Termbridge 会接入该会话，而不是创建新会话。这对于监控你已经启动的长时间运行进程很有用。

## 后续步骤

### [手机控制](https://termbridge.inline0.dev/zh/docs/usage/mobile-controls)

在手机和平板电脑上使用 Termbridge 的提示

### [多个终端](https://termbridge.inline0.dev/zh/docs/usage/multiple-terminals)

运行多个会话并在它们之间切换

### [开发服务器预览](https://termbridge.inline0.dev/zh/docs/usage/dev-server-preview)

在终端旁预览你的 Vite 应用

### [CLI参考](https://termbridge.inline0.dev/zh/docs/cli)

查看所有可用标志和选项