sing-box Hysteria2 配置怎么写？先分清入站还是出站

更新于 2026-10-24 · candytally.buzz

简答：sing-box 配置 Hysteria2 时，服务端写 hysteria2 入站，客户端写 hysteria2 出站；先核对服务器地址、UDP 端口、密码和 TLS SNI，再用 sing-box check 检查 JSON，最后查看启动日志与端口监听。

定义：Hysteria2 在 sing-box 中是一种基于 QUIC 的代理协议，服务端使用 hysteria2 入站接收连接，客户端使用 hysteria2 出站连接服务器。

先看这张表：你需要配置哪一段

如果你已经拿到服务器域名、UDP 端口和密码，通常只需要填写客户端出站；只有自建服务器、需要监听端口并提供 Hysteria2 服务时，才需要配置服务端入站。sing-box 的总配置使用 JSON，并通过 官方配置结构文档定义 log、inbounds、outbounds 和 route 等顶层字段。

截至 2026-10-24，Releases 标记为 Latest 的是 1.14.4；官方文档同时列出 1.14.0、1.11.0 等字段变化，复制旧教程时要特别检查字段名称。

服务端 Hysteria2 入站最小配置

下面示例适合自建服务器。将域名、端口、证书路径、私钥路径和密码替换为自己的值；证书必须覆盖客户端连接时使用的域名。Hysteria2 入站要求 TLS，官方字段说明见 Hysteria2 入站文档与 TLS 文档。

{
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "hysteria2",
      "tag": "hy2-in",
      "listen": "::",
      "listen_port": 443,
      "users": [
        {
          "name": "user-1",
          "password": "替换为客户端使用的密码"
        }
      ],
      "tls": {
        "enabled": true,
        "certificate_path": "/etc/sing-box/server.crt",
        "key_path": "/etc/sing-box/server.key"
      }
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

• listen_port：服务端监听的 UDP 端口，需要同时检查系统防火墙、云平台安全组和上游网络设备。
• users[].password：这是 sing-box 入站用户认证密码，客户端出站的 password 必须对应。
• tls.certificate_path 与 key_path：分别指向 PEM 格式证书链和私钥文件。路径错误、权限不足或证书过期都会导致启动或握手失败。
• up_mbps、down_mbps：用于设置最大带宽，单位是 Mbps；初次排查可以先不写，避免把过低的限制误判成网络变慢。

客户端 Hysteria2 出站最小配置

如果你是连接已有节点，应把 Hysteria2 写在 outbounds 中。官方出站文档要求填写服务器地址和端口；当使用 server_ports 时，server_port 会被忽略，二者不要同时用于同一目的。参考官方 Hysteria2 出站字段说明。

{
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "hysteria2",
      "tag": "hy2-out",
      "server": "hy2.example.com",
      "server_port": 443,
      "password": "替换为服务端对应密码",
      "tls": {
        "enabled": true,
        "server_name": "hy2.example.com",
        "insecure": false
      }
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "hy2-out"
  }
}

其中 server 是服务器地址，server_port 是服务器端口，password 是认证密码，tls.server_name 用于 SNI 和证书主机名校验。insecure 为 true 时会接受任意服务器证书，适合临时定位证书问题，不应作为长期默认配置；正常使用应保留为 false。

如果服务端使用的是官方 Hysteria2 的 userpass 认证，sing-box 文档说明它本质上是“用户名:密码”的组合，而 sing-box 不提供同名别名。此时应按服务端实际认证方式填写完整字符串，不能只凭字段名称猜测。

TLS、域名、SNI 和 UDP 端口怎么对应

CA 证书方案应优先使用系统或受信任 CA 签发的证书，客户端保持证书校验。自签证书需要额外配置客户端信任材料或固定证书、公钥；如果只是把 insecure 设为 true，虽然可能绕过校验错误，但也失去了服务器身份验证。官方 TLS 文档明确说明，server_name 会参与证书主机名验证，而 insecure 会接受任意服务器证书。

配置检查、启动和日志排错闭环

1. 把配置保存为 config.json，先确认 JSON 没有注释、尾逗号或重复键。
2. 运行 sing-box check -c config.json。官方配置文档提供了 sing-box check 检查命令，也支持使用 sing-box format -w -c config.json 格式化配置。
3. 检查通过后运行 sing-box run -c config.json，先观察启动日志，再测试客户端连接。
4. Linux 服务端可用 systemctl status sing-box 查看服务状态，使用 journalctl -u sing-box -e 查看最近日志；具体服务名以你的 systemd 单元为准。
5. 检查 UDP 监听：Linux 使用 sudo ss -lunp | grep 443；macOS 使用 lsof -nP -iUDP:443。端口号替换为配置中的实际值。
6. 客户端连接后查看连接日志是否出现目标出站标签，例如 hy2-out；也可以对比代理开启前后的出口 IP，判断请求是否真的经过该出站。

Windows、Linux、Android 和 iOS 怎么导入

Windows 和 Linux 可使用官方的 sing-box for Desktop；官方页面列出 Windows 10+ 与 Linux 的支持要求，并说明桌面客户端可管理本地或远程配置文件。Windows 上导入时重点确认配置文件路径、系统权限和 TUN 开关；Linux 命令行则先用 sing-box check，再用 systemd 或前台命令启动。

Android 和 iOS 使用对应的 sing-box 图形客户端时，手动填写的核心仍是同一组出站字段：服务器地址、UDP 端口、密码、TLS 开关和 SNI。不同平台的导入按钮、权限提示和 TUN 设置位置会不同；如果订阅导入失败，应先把订阅内容转换或导出为客户端支持的 sing-box JSON，再检查生成的 outbounds 是否确实包含 type 为 hysteria2 的出站。

如果你使用的是服务商提供的订阅而不是自建服务器，服务商的节点参数、订阅格式和客户端兼容性应以其公开说明为准；不要把服务端入站模板直接粘贴到手机或桌面客户端。

新版字段迁移时先做这三项检查

• server_port 与 server_ports：官方文档说明，端口范围和端口跳跃字段自 sing-box 1.11.0 起出现；普通单端口连接先保留 server_port，不要为了“新字段”强行改成范围。
• hop_interval_max、bbr_profile、realm 和 gecko：这些属于较新的扩展能力，先让单端口、普通 TLS 配置跑通，再单独增加。官方出站页面将相关变化列在 1.14.0 部分。
• obfs：服务端和客户端必须使用相同的类型与密码；如果并未明确要求混淆，最小配置可以先不添加，减少变量。

排错的原则是一次只改一个变量：先确认 JSON、再确认进程启动、再确认 UDP 端口，最后才处理 TLS、认证和高级参数。这样能避免多个错误同时出现，导致日志无法判断。

结语：先跑通最小配置，再加高级功能

sing-box Hysteria2 配置的关键不是复制最长的 JSON，而是分清服务端入站和客户端出站，并让端口、密码、证书域名和 SNI 一一对应。自建服务器从入站模板开始；已有节点则只填写出站；任何连接失败都按 check、启动日志、UDP 监听和出口验证的顺序排查。

常见问题

sing-box Hysteria2 配置应该写 inbound 还是 outbound？

自建服务器写 hysteria2 inbound；连接已有节点写 hysteria2 outbound。客户端不能直接使用服务端入站模板。

Hysteria2 一定要配置 TLS 吗？

sing-box 官方 Hysteria2 入站文档将 TLS 标为必需。服务端需要证书和私钥，客户端需要开启 TLS，并让 server_name 与证书域名匹配。

客户端提示证书错误，可以直接把 insecure 改成 true 吗？

不建议作为长期配置。insecure 会接受任意服务器证书，降低身份验证强度；应先检查证书链、域名、系统时间和 SNI，临时开启只用于定位问题。

password 和 userpass 为什么不一样？

sing-box 使用 password 字段。官方 Hysteria2 的 userpass 本质上是“用户名:密码”组合；对接时要按服务端实际认证格式填写，不能只复制密码部分。

sing-box check 通过但还是连不上怎么办？

check 只说明配置结构和字段基本可解析，不代表网络可达。继续查看运行日志，确认服务端 UDP 监听、防火墙与安全组、TLS SNI、密码以及客户端实际命中的出站标签。

相关阅读

• sing-box 订阅导入失败排查
• 连接问题排查
• 设备配置指南
• 使用指南

参考资料

1. Introduction - sing-box
2. Hysteria2 入站 - sing-box
3. Hysteria2 出站 - sing-box
4. TLS - sing-box
5. sing-box for Desktop
6. SagerNet/sing-box Latest Release