# 故障排除

## "spawn tmux ENOENT"

未安装 tmux，或它不在你的 PATH 中。Termbridge 会打印此错误，但目前仍会继续运行，却不提供终端（[#4](https://github.com/inline0/termbridge/issues/4)）；请按 `Ctrl+C`，安装 tmux，然后重新启动。

```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

## "spawn cloudflared ENOENT"

Cloudflare 的隧道客户端未安装，或不在你的 PATH 中。只有隧道模式需要它；直接模式下，`--no-tunnel` 和 Daytona 不需要 cloudflared。

```bash
# macOS
brew install cloudflared
```

对于 Linux，请从 [cloudflare.com/downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 下载。

## 隧道无法启动

请检查以下几项（如果你使用的是直接沙盒模式，可跳过此项）：

1. 确认 cloudflared 可以正常运行：`cloudflared --version`
2. 确认你可以访问 `https://trycloudflare.com`
3. 检查是否有防火墙阻止出站连接

如果隧道无法启动，Termbridge 会打印错误、停止服务器并以状态码 1 退出。它不会回退到仅限本地的模式，并且服务器默认只监听 `127.0.0.1`，因此网络中的其他设备也无法访问。此次运行创建的 tmux 会话会继续运行（[#4](https://github.com/inline0/termbridge/issues/4)）。

若要在不使用 Cloudflare 隧道的情况下使用 Termbridge，请在自己的反向代理或隧道后面运行它，并使用 `--no-tunnel --public-url <url>`。

## trycloudflare 返回“429 Too Many Requests”

Cloudflare 会对无需账户的隧道实施速率限制。如果你看到类似 `429 Too Many Requests` 的错误，请尝试：

1. 等待几分钟后重试
2. 确认没有旧的 `cloudflared` 进程仍在运行
3. 使用命名隧道令牌（频繁使用时推荐）

## 空白屏幕或“无法加载终端”

这通常表示浏览器没有有效的会话 Cookie，例如打开页面时没有兑换共享链接，或者隧道 URL 已更改：

1. 检查本地服务器是否仍在运行
2. 查看浏览器控制台中是否有 401/403 错误
3. 重启 Termbridge，以获取新的 URL 和 QR 代码

## 终端没有输出

tmux 会话可能未运行：

```bash
# Check if sessions exist
tmux ls
```

如果会话已显示，但终端为空白，请尝试：
- 重新加载页面
- 检查你的 Shell 是否支持 `TERM=xterm-256color`

## 扫描 QR 代码后页面为空白

QR 代码包含一次性令牌。它只能使用一次，并且必须在 Termbridge 启动后的 90 秒内使用。已使用或已过期的链接会返回 `invalid token`。

解决方法：重启 Termbridge 以生成新的 QR 代码，并立即扫描。

## node-pty 报告 spawn-helper 错误

Termbridge 会尝试自动修复此问题，但如果你看到权限错误：

```bash
chmod +x node_modules/node-pty/prebuilds/**/spawn-helper
```

## 仍未解决？

在 [github.com/inline0/termbridge](https://github.com/inline0/termbridge/issues) 提交问题，并附上：
- 你的操作系统和 Node.js 版本
- 错误消息
- 重现步骤