企业官网建设流程全解析

T3 Code远程访问排错指南：快速定位node not found与端口扫描失败

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code

T3 Code 远程访问失败时，报错大多集中在两类：SSH 启动远程服务器时提示node not found，以及端口扫描失败导致服务器无法就绪。这份排错手册带你按错误出现顺序逐一诊断，从非交互 Shell 的 PATH 问题一路查到远端端口占用，覆盖 T3 Code 远程访问最常见的故障场景。

T3 Code 远程访问是怎么工作的

在排错之前，先搞清楚 T3 Code 桌面端 SSH 启动远程环境的完整链路（源码：tunnel.ts）：

1. 桌面端通过非交互sh会话连接远端主机（不带你交互式登录的 shell 环境）；
2. 在远端~/.t3/ssh-launch/<host-key>/下写入启动脚本，尝试启动或复用远端 T3 服务器；
3. 远端从默认端口3773开始做端口扫描，找到一个可用端口并绑定到127.0.0.1；
4. 轮询 HTTP 就绪探测（/返回 2xx 才算就绪，逻辑见 httpReadiness.ts）；
5. 成功后把远端回环端口转发回桌面端，本地 UI 通过转发端口正常连接。

只要其中任何一环断了，你就会看到本文要讲的三类错误。官方用户文档在 docs/user/remote-access.md，架构细节在 docs/internals/remote.md。

错误一：node not found（node: command not found）

这是最高频的错误。根本原因是：T3 Code 走的是非交互sh会话，它不会加载你.bashrc/.zshrc里的 PATH 配置，很多 Node 版本管理器（nvm、mise、asdf、fnm、nodenv、Volta）只在交互式 shell 里才生效。

第一步：用 T3 Code 的同一视角检查

SSH 登录远端主机，执行与 T3 Code 完全相同的检查路径：

ssh user@example.com 'sh -lc "command -v node && node --version"'

如果这条命令打不出兼容版本，问题就坐实了。

第二步：检查 Node 版本是否满足要求

即使找到了 node，版本也必须落在 T3 Code 服务器包的engines.node范围内（定义在 apps/server/package.json）：

^22.16 || ^23.11 || >=24.10

低于这个版本会得到 "does not satisfy required range" 报错。

第三步：修复版本管理器配置

T3 Code 的启动脚本（ensure_remote_node_path，见 tunnel.ts）会自动尝试激活主流版本管理器，覆盖大部分场景。修复方法按工具区分：

• nvm：为非交互 shell 设置默认版本 ——nvm alias default 24
• mise / asdf / fnm / nodenv：确认 shim 目录已安装，且非交互 shell 下能解析到合格版本
• 兜底方案：把兼容的 Node 直接装到脚本会搜索的目录，如~/.local/bin、~/.bin、/usr/local/bin

错误二：端口扫描失败（Failed to find an available port）

启动脚本会执行内嵌的端口探测程序（REMOTE_PICK_PORT_SCRIPT，见 tunnel.ts）：优先复用上次记录在~/.t3/ssh-launch/<host-key>/port的端口，否则从3773起逐个向上试探，尝试在127.0.0.1上 listen 成功即锁定该端口。

扫描失败通常有三种原因，按概率排序：

错误三：Remote T3 server did not become ready

端口拿到了，但就绪探测（HTTP 2xx 轮询）超时。注意区分两种日志形态：

• 有日志：会附带~/.t3/ssh-launch/<host-key>/server.log的最后 80 行，直接看里面的报错；
• 日志为空：说明进程启动前就退出了，最常见原因是通过npx安装t3时原生依赖 node-pty 编译失败——远端缺少 C 工具链。修复：Debian/Ubuntu 装build-essential，Fedora/RHEL 装gcc-c++ make，macOS 执行xcode-select --install。

应用更新后重连失败：重试一次即可

应用升级后如果重连失败，直接再点一次 SSH 启动。启动器现在会自动对比生成的 runner 脚本、停掉旧的由启动器管理的远端服务、清理 SSH 启动的 PID/端口状态并拉起全新服务器（tunnel.ts）。正常情况下不需要手动删除~/.t3/ssh-launch或 killt3进程。

另外，如果客户端和远端服务器版本不一致，会话和Settings → Connections里会显示版本告警，按界面提示操作即可，详见 docs/user/updating.md。

排错检查清单

📋 按顺序过一遍，绝大多数远程访问问题都能定位：

• ssh user@host 'sh -lc "command -v node && node --version"'能输出版本吗？
• 版本满足^22.16 || ^23.11 || >=24.10吗？
• 版本管理器是否为非交互 shell 配置了默认版本（如nvm alias default 24）？
• 远端 3773 附近的端口被什么进程占用了？
• 远端装好 C 工具链了吗（node-pty 需要编译）？
• 更新应用后，重试一次 SSH 启动了吗？
• 两边设备的时间和日期一致吗？

安全提醒：配对 URL 和 token 视同密码保管；建议把--host绑定到可信的私有地址（如 Tailnet IP），并定期用t3 auth吊销不再信任的凭据。

延伸阅读

• 用户文档：docs/user/remote-access.md
• 架构文档：docs/internals/remote.md
• SSH 隧道与远端启动脚本源码：packages/ssh/src/tunnel.ts
• HTTP 就绪探测逻辑：packages/shared/src/httpReadiness.ts
• 后台服务运行指南（Linux 长驻服务器）：docs/user/background-service.md

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code