先判断失败在界面、内核还是连接阶段

表现更接近的问题
窗口空白、点击无响应图形界面、运行依赖或安装环境
界面正常，内核反复退出配置、端口、权限或运行文件
内核已运行，所有节点超时连接链路、DNS、订阅或节点
只在开机自动启动时失败服务启动顺序、工作目录或用户权限

先记录系统、客户端及内核版本，保存第一次失败的完整错误。日志后面连串的重试可能只是同一故障的结果。已有可用配置先备份，不要通过删除用户目录来“恢复默认”而丢掉全部订阅和覆写。

第一步：端口占用时先找拥有者

Windows PowerShell；7890 换成日志报错的实际 TCP 端口
Get-NetTCPConnection -LocalPort 7890 -State Listen -ErrorAction SilentlyContinue |
  Select-Object LocalAddress,LocalPort,OwningProcess
# 将下行 1234 换成上面查到的进程号
Get-Process -Id 1234
macOS / Linux：同样替换为实际端口
# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN
# Linux
ss -ltnp 'sport = :7890'

这些命令针对 TCP，UDP 入站需用相应 UDP 查询方式。普通用户可能看不到其他用户进程的完整信息。确认占用者是旧客户端时，优先从其界面正常退出；若是需要保留的服务，则改新客户端端口，并同步修改系统代理和依赖它的应用。不要根据一个端口号直接强杀进程。

第二步：端口和控制接口不要混用

HTTP/mixed、SOCKS、DNS 和控制面板是不同入口。日志里的 address already in use 可能发生在其中任何一项。改了代理端口却没同步系统设置，会变成“启动成功但浏览器连不上”；把控制接口端口填给浏览器也不能代理流量。

第三步：按错误检查配置和权限

  1. 若日志出现语法错误、未知字段或不存在的策略组，先用客户端检查功能；sing-box 可在匹配版本 CLI 上运行 check。处理真实错误，不删除安全校验字段。
  2. 若提示 TUN 或服务权限不足，核对是否已按官方方式安装所需服务。只给该功能必要权限，不将整个图形客户端永久设为管理员作为通用办法。
  3. 文件路径或权限错误时，确认当前用户能访问配置和依赖文件。移动便携版目录、以 root 启动过界面或切换用户，都可能改变配置位置和所有者。

Windows 空白窗口可按项目 FAQ 核对 WebView2；Mac 的来源限制按 Apple 指引核实安装包。两种问题都发生在网络代理工作之前，此时反复换节点无法解决。不要从陌生帖子下载替换 DLL 或内核文件。

验收与回退

  1. 确认界面和内核均稳定运行，再测试本地代理端口及实际网站。
  2. 按原计划启动一次 TUN 或服务，复测局域网与正常退出；若服务仍失败，先保持已验证的有限接管方式，不宣称全部应用可用。
  3. 关闭并重新打开客户端，确认不再出现端口冲突。撤销本次无效修改，保留脱敏日志和最小复现，避免同时卸载多款网络软件。