跳转到正文

故障排除

以 Markdown 格式查看 在 GitHub 上编辑 文档位置 1675df8

"spawn tmux ENOENT"

未安装 tmux，或它不在你的 PATH 中。Termbridge 会打印此错误，但目前仍会继续运行，却不提供终端（#4）；请按 Ctrl+C，安装 tmux，然后重新启动。

命令行
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

"spawn cloudflared ENOENT"

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

命令行
# macOS
brew install cloudflared

对于 Linux，请从 cloudflare.com/downloads 下载。

隧道无法启动

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

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

如果隧道无法启动，Termbridge 会打印错误、停止服务器并以状态码 1 退出。它不会回退到仅限本地的模式，并且服务器默认只监听 127.0.0.1，因此网络中的其他设备也无法访问。此次运行创建的 tmux 会话会继续运行（#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 会话可能未运行：

命令行
# Check if sessions exist
tmux ls

如果会话已显示，但终端为空白，请尝试：

  • 重新加载页面
  • 检查你的 Shell 是否支持 TERM=xterm-256color

扫描 QR 代码后页面为空白

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

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

node-pty 报告 spawn-helper 错误

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

命令行
chmod +x node_modules/node-pty/prebuilds/**/spawn-helper

仍未解决？

在 github.com/inline0/termbridge 提交问题，并附上：

  • 你的操作系统和 Node.js 版本
  • 错误消息
  • 重现步骤