Hysteria2 — Xray-core

Xray-core 支持 Hysteria v2，但 把配置分到两个块：协议层的 settings（version、address/port、users）与传输层的 streamSettings.hysteriaSettings（鉴权、带宽、端口跳变、伪装）。 两个块都填好后出站才可用。

出站 —— 协议层

"protocol": "hysteria" 出站的 settings：

字段	类型	默认值	允许值	描述
version	int32	(required)	2	必须恰好等于 2。其他值会在启动时被拒绝（`infra/conf/hysteria.go:19-21`）。
address	*Address	(required)	<host>	服务器主机名或 IP。
port	uint16	(required)	<port>	服务器 UDP 端口。

源码： infra/conf/hysteria.go:13-17 · 锚定版本 v26.6.1 (94ffd50)

不支持 Hysteria v1

version 字段 必须 等于 2。HysteriaClientConfig.Build （infra/conf/hysteria.go:19-21）对任何其他值返回 errors.New("version != 2")。

入站 —— 协议层

"protocol": "hysteria" 入站的 settings：

字段	类型	默认值	允许值	描述
version	int32	(required)	2	必须为 2。
users	[]*HysteriaUserConfig	[]	[HysteriaUserConfig]	可接受的用户。`users` 是较新的名称，与 `clients` 一并接受。
clients	[]*HysteriaUserConfig	[]	[HysteriaUserConfig]	可接受的用户（旧名称；形状与 `users` 相同）。

源码： infra/conf/hysteria.go:40-44 · 锚定版本 v26.6.1 (94ffd50)

clients[]

字段	类型	默认值	允许值	描述
auth	string	(required)	<string>	鉴权字符串。
level	uint32	0	<uint32>	该用户的策略等级。
email	string	(unset)	<string>	统计 / 日志中显示的标签。

源码： infra/conf/hysteria.go:34-38 · 锚定版本 v26.6.1 (94ffd50)

传输层 —— hysteriaSettings

位于 streamSettings.hysteriaSettings 下。承载协议层不涵盖的所有 运行时旋钮。

字段	类型	默认值	允许值	描述
version	int32	(required)	2	Hysteria 协议版本。必须与 `settings` 中的 `version` 一致。
auth	string	(required on outbound)	<string>	出站的鉴权字符串。入站会把该字段转发给校验器，但每用户的鉴权位于 `settings.clients[].auth`。
congestion	*string	(unset)	bbr | cubic | reno	服务端拥塞控制算法的提示。新构建已把它迁移到 QUIC 参数 —— 在此位置设置会触发警告。
up	*Bandwidth	(unset)	<bandwidth>	估算的上行带宽（带单位的字符串：`1Mbps`、`100kbps`、`50mbps`）。
down	*Bandwidth	(unset)	<bandwidth>	估算的下行带宽。
udphop	*UdpHop	(unset)	UdpHop	出站的 UDP 端口跳变配置。
udpIdleTimeout	int64	60	<2..600 seconds>	QUIC 流关闭前的 UDP 流空闲秒数。必须在 [2, 600] 之间（含端点）（`infra/conf/transport_internet.go:544-546`）。
masquerade	Masquerade	(unset)	Masquerade	仅入站：对未鉴权流量返回 HTTP 响应伪装。

源码： infra/conf/transport_internet.go:513-524 · 锚定版本 v26.6.1 (94ffd50)

udphop

字段	类型	默认值	允许值	描述
ports	PortList	(required)	<JSON array or string>	用于跳变的端口列表。接受端口 / 范围的 JSON 数组，或形如 `"100,200-210,400"` 的字符串。
interval	Int32Range	(unset)	Int32Range	切换端口的频率，以秒为单位的范围（`{From, To}`）。

源码： infra/conf/transport_internet.go:494-497 · 锚定版本 v26.6.1 (94ffd50)

masquerade

字段	类型	默认值	允许值	描述
type	string	(required)	file | proxy | string	选择启用的子块。
dir	string	(file only)	<dir path>	`type: file` 时托管的目录。
url	string	(proxy only)	<URL>	`type: proxy` 时使用的上游 URL。
rewriteHost	bool	false	true | false	代理时是否改写 Host 头（`type: proxy`）。
insecure	bool	false	true | false	`type: proxy` 时跳过对上游的 TLS 校验。
content	string	(string only)	<text>	`type: string` 时返回的响应体。
headers	map[string]string	{}	{<header>: <value>}	`type: string` 时附加的响应头。
statusCode	int32	200	<int>	`type: string` 时返回的状态码。

源码： infra/conf/transport_internet.go:499-511 · 锚定版本 v26.6.1 (94ffd50)

type 字段切换活动子块：file 使用 dir，proxy 使用 url / rewriteHost / insecure，string 使用 content / headers / statusCode。

带宽语法

up 与 down 由 infra/conf/transport_internet.go:478-501 中的 辅助函数解析。可接受的后缀：

后缀	倍数
（空）、b、bps	1
k、kb、kbps	1024
m、mb、mbps	1 048 576
g、gb、gbps	1 073 741 824
t、tb、tbps	1 099 511 627 776

数值部分按 float64 解析，结果除以 8（protobuf 中承载的是 bytes-per-second，但来源单位名是 bps）。

示例

出站：

{
  "outbounds": [
    {
      "tag": "hy2-out",
      "protocol": "hysteria",
      "settings": {
        "version": 2,
        "address": "example.com",
        "port": 443
      },
      "streamSettings": {
        "network": "hysteria",
        "security": "tls",
        "tlsSettings": { "serverName": "example.com" },
        "hysteriaSettings": {
          "version": 2,
          "auth": "<password>",
          "up": "100mbps",
          "down": "300mbps",
          "udpIdleTimeout": 120
        }
      }
    }
  ]
}

带两个用户与 HTTP-file 伪装的入站：

{
  "inbounds": [
    {
      "tag": "hy2-in",
      "listen": "0.0.0.0",
      "port": 443,
      "protocol": "hysteria",
      "settings": {
        "version": 2,
        "clients": [
          { "auth": "<alice>", "email": "alice" },
          { "auth": "<bob>",   "email": "bob"   }
        ]
      },
      "streamSettings": {
        "network": "hysteria",
        "security": "tls",
        "tlsSettings": { "certificates": [{ "certificateFile": "/etc/ssl/cert.pem", "keyFile": "/etc/ssl/key.pem" }] },
        "hysteriaSettings": {
          "version": 2,
          "masquerade": {
            "type": "file",
            "dir": "/var/www"
          }
        }
      }
    }
  ]
}

说明

• 常见坑：仅在 settings 中设置 auth（误以为它是用户名 / 密码 字段）。Xray 从 streamSettings.hysteriaSettings.auth 读取出站 鉴权；入站用户使用 settings.clients[].auth（每用户），匹配 时忽略传输层 auth。
• congestion、up、down 与 udphop 会在未来版本迁入新的 finalmask / quicParams 块。在旧位置设置这些字段会打印警告 （infra/conf/transport_internet.go:540-542）。
• Hysteria v1 已完全从 Xray-core 移除。源码中 "v1" 字样如今只是历史 标签 —— version != 2 是硬错误。
• udpIdleTimeout < 2 或 > 600 会触发启动错误 （infra/conf/transport_internet.go:544-546）。

跨内核说明

• sing-box 采用单一、扁平得多的块 —— 没有传输层拆分。带宽以 整数 Mbps 表达（不带单位字符串），伪装支持多态形态（字符串 URL 或类型化对象）。参见 Hysteria2 — sing-box。
• mihomo 同样是单块形态，端口跳变由 ports（范围语法）加 hop-interval 驱动。mihomo 像 Xray 一样接受带单位后缀的 up / down 字符串。参见 Hysteria2 — mihomo。

源码： infra/conf/hysteria.go:13-44 · v26.6.1 (94ffd50)