VMess — mihomo

mihomo 双端支持 VMess。出站形态承载所有传输（ws、http、h2、grpc）、TLS、REALITY、ECH 与两个鉴权扩展开关。入站故意更精简 —— 用户列表直接位于监听器上。

出站

proxies: 下 type: vmess 条目。该结构体内嵌 BasicOption（通用出站字段：interface-name、routing-mark、ip-version、dialer-proxy 等）。

字段	类型	默认值	允许值	描述
name	string	(required)	<string>	唯一的代理名。
server	string	(required)	<host>	上游服务器主机名或 IP。
port	int	(required)	<port>	上游服务器端口。
uuid	string	(required)	<UUID>	服务器接受的用户 UUID。
alterId	int	0	0 | <int>	旧式 MD5-AEAD 兼容。现代仅 AEAD 模式保持 0。
cipher	string	auto	auto | aes-128-gcm | chacha20-poly1305 | none | zero	对称加密。mihomo 用 `cipher` 表达其他内核中的 `security`。
udp	bool	false	true | false	允许 UDP 包经此出站转发。
network	string	tcp	tcp | ws | http | h2 | grpc | mekya | mkcp	底层传输。`mekya` 与 `mkcp`（别名 `kcp`）的设置来自 `mekya-opts` / `mkcp-opts`。
tls	bool	false	true | false	用 TLS 包裹流。
alpn	[]string	[]	h2 | http/1.1	TLS 握手时宣告的 ALPN 列表。
skip-cert-verify	bool	false	true | false	禁用 TLS 证书校验（仅供测试）。
name-cert-verify	string	(unset)	<hostname>	改为按此主机名（而非 SNI）校验服务器证书。
fingerprint	string	(unset)	<SHA256 hex>	把服务端 TLS 证书锚定到该 SHA-256 指纹。
certificate	string	(unset)	<PEM file path>	客户端证书（mTLS）。
private-key	string	(unset)	<key file path>	与 `certificate` 配对的私钥。
servername	string	(unset)	<SNI>	覆盖 TLS SNI。
ech-opts	ECHOptions	(disabled)	ECHOptions	Encrypted Client Hello 配置。
shadow-tls-opts	ShadowTLSOptions	(disabled)	ShadowTLSOptions	Shadow-TLS 伪装块（`{ password, version }`）。每个代理最多只能启用一个 TLS 伪装块。
restls-opts	RestlsOptions	(disabled)	RestlsOptions	Restls 伪装块（`{ password, version-hint, restls-script }`）。每个代理最多只能启用一个 TLS 伪装块。
jls-opts	JLSOptions	(disabled)	JLSOptions	JLS 伪装块（`{ username, password }`）。每个代理最多只能启用一个 TLS 伪装块。
reality-opts	RealityOptions	(disabled)	RealityOptions	REALITY 客户端配置。
tlsmirror-opts	TLSMirrorOptions	(disabled)	TLSMirrorOptions	TLSMirror 伪装块，通过设置其 `primary-key` 启用；带有自己的子选项块。每个代理最多只能启用一个 TLS 伪装块。
mekya-opts	MekyaOptions	(unset)	MekyaOptions	`network: mekya`（V2Ray 兼容的 Mekya，将 KCP 承载在 HTTP 请求上）的设置；带有自己的子选项块（`url`、`h2-pool-size`、`kcp` 等）。
mkcp-opts	MKCPOptions	(unset)	MKCPOptions	`network: mkcp`（V2Ray 兼容的 mKCP over UDP）的设置；带有自己的子选项块（`mtu`、`tti`、`seed`、`header` 等）。
http-opts	HTTPOptions	(unset)	HTTPOptions	`network: http` 的设置。
h2-opts	HTTP2Options	(unset)	HTTP2Options	`network: h2` 的设置。
grpc-opts	GrpcOptions	(unset)	GrpcOptions	`network: grpc` 的设置。
ws-opts	WSOptions	(unset)	WSOptions	`network: ws` 的设置。
packet-addr	bool	false	true | false	使用旧式 packet-addr UDP 编码。
xudp	bool	false	true | false	对 UDP 包使用 xudp 编码（现代默认）。与 packet-addr 互斥。
packet-encoding	string	(use udp/xudp flags)	packetaddr | xudp	显式的 packet-encoding 选择器；设置后会覆盖布尔标志。
global-padding	bool	false	true | false	把所有写入填充到统一长度。服务端必须一致。
authenticated-length	bool	false	true | false	使用 authenticated-length 帧。服务端必须一致。
client-fingerprint	string	(global)	chrome | firefox | safari | ios | edge | random | randomized	uTLS ClientHello 指纹。

源码： adapter/outbound/vmess.go:53-89 · 锚定版本 v1.19.29 (e26714a)

ws-opts

字段	类型	默认值	允许值	描述
path	string	/	/<path>	WebSocket 路径。
headers	map[string]string	{}	{<header>: <value>}	upgrade 请求附加的 HTTP 头。
max-early-data	int	0	<bytes>	WS 握手完成前缓冲的最大早数据字节数。
early-data-header-name	string	(unset)	<header name>	服务端期望以非标准头承载 base64 编码早数据时使用的头名。
v2ray-http-upgrade	bool	false	true | false	使用 V2Ray 风格 HTTP-upgrade 传输替代真正的 WebSocket。
v2ray-http-upgrade-fast-open	bool	false	true | false	把客户端载荷与 HTTP-upgrade 请求一起发出以省一次 RTT。

源码： adapter/outbound/vmess.go:165-172 · 锚定版本 v1.19.29 (e26714a)

grpc-opts

字段	类型	默认值	允许值	描述
grpc-service-name	string	(required)	<name>	gRPC 服务名路径。
grpc-user-agent	string	(unset)	<UA string>	覆盖 gRPC 客户端 User-Agent。
ping-interval	int	0	<seconds>	HTTP/2 PING 帧间隔。0 禁用。
max-connections	int	0	<int>	最大并发 gRPC 通道数（mux fan-out）。
min-streams	int	0	<int>	分配新通道前每通道的最小流数。
max-streams	int	0	<int>	每通道的最大流数。

源码： adapter/outbound/vmess.go:156-163 · 锚定版本 v1.19.29 (e26714a)

入站

listeners: 下 type: vmess 条目。内嵌 BaseOption（listen、port）。

字段	类型	默认值	允许值	描述
users	[]VmessUser	(required)	<VmessUser array>	可接受的客户端。
ws-path	string	(unset)	/<path>	该监听器提供的 WebSocket 路径。
grpc-service-name	string	(unset)	<name>	该监听器接受的 gRPC 服务名。
certificate	string	(unset)	<PEM file path>	TLS 服务端证书。
private-key	string	(unset)	<key file path>	TLS 私钥。
client-auth-type	string	(none)	no-client-cert | request-client-cert | require-any-client-cert | verify-client-cert-if-given | require-and-verify-client-cert	mTLS 客户端鉴权模式。
client-auth-cert	string	(unset)	<PEM file path>	作为客户端根的 CA 集合。
ech-key	string	(unset)	<ECH config>	Encrypted Client Hello 配置 / 密钥。
shadow-tls	ShadowTLS	(disabled)	ShadowTLS	服务端 Shadow-TLS 伪装块（`{ enable, version, password, users, handshake, ... }`）。
res-tls	ResTLS	(disabled)	ResTLS	服务端 Restls 伪装块（`{ enable, dest, password, ... }`）；未通过认证的客户端会被中继到 `dest`。
jls-config	JLSConfig	(disabled)	JLSConfig	服务端 JLS 伪装块（`{ enable, users, sni, dest, ... }`）；未通过认证的客户端会被中继到 `dest`。
reality-config	RealityConfig	(disabled)	RealityConfig	REALITY 服务端配置。
tlsmirror-config	TLSMirrorConfig	(disabled)	TLSMirrorConfig	服务端 TLSMirror 伪装块，通过设置其 `primary-key` 启用；带有自己的子选项块（`dest`、`proxy` 等）。
mekya-config	MekyaConfig	(disabled)	MekyaConfig	服务端块（`enable` 加子选项），接受 V2Ray 兼容的 Mekya 传输。不能与 `mkcp-config`、`ws-path` 或 `grpc-service-name` 组合。
mkcp-config	MKCPConfig	(disabled)	MKCPConfig	服务端块（`enable` 加子选项），接受 V2Ray 兼容的 mKCP over UDP 传输。
mux-option	MuxOption	(disabled)	MuxOption	多路复用设置（sing 风格 mux）。

源码： listener/inbound/vmess.go:12-30 · 锚定版本 v1.19.29 (e26714a)

users[]

字段	类型	默认值	允许值	描述
username	string	(unset)	<string>	显示名。
uuid	string	(required)	<UUID>	用户 UUID。
alterId	int	0	0 | <int>	旧式 MD5-AEAD 兼容。

源码： listener/inbound/vmess.go:32-36 · 锚定版本 v1.19.29 (e26714a)

示例

出站 —— WebSocket + TLS 的 VMess：

proxies:
  - name: vmess-ws
    type: vmess
    server: example.com
    port: 443
    uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
    alterId: 0
    cipher: auto
    udp: true
    network: ws
    tls: true
    servername: example.com
    ws-opts:
      path: /vm
      headers:
        Host: example.com

出站 —— gRPC + REALITY 的 VMess：

proxies:
  - name: vmess-grpc
    type: vmess
    server: example.com
    port: 443
    uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
    alterId: 0
    cipher: auto
    network: grpc
    tls: true
    servername: www.cloudflare.com
    client-fingerprint: chrome
    reality-opts:
      public-key: <reality public key>
      short-id: <short id>
    grpc-opts:
      grpc-service-name: GunService

listeners 下的入站：

listeners:
  - name: vmess-in
    type: vmess
    listen: 0.0.0.0
    port: 443
    users:
      - username: alice
        uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
        alterId: 0
    certificate: /etc/mihomo/server.crt
    private-key: /etc/mihomo/server.key

说明

• mihomo 出站使用 cipher 表达对称算法。Xray（security）与 sing-box（security）字段名不同。mihomo 与 sing-box 接受 auto、aes-128-gcm、chacha20-poly1305、none、zero；Xray-core 已在 v26.7.x 移除 none / zero，现在只接受前三个（未知值回退到 auto）。
• 出站暴露了三套 UDP 编码开关：udp（布尔 —— 是否启用 UDP 转发）、xudp / packet-addr（旧式布尔选择器）、packet-encoding（现代显式选择器）。设置了 packet-encoding 时，布尔选择器被忽略。
• global-padding 与 authenticated-length 对应 sing-box 的 global_padding / authenticated_length —— 两端必须一致。
• ws-opts.v2ray-http-upgrade 把 WebSocket 握手换成 V2Ray 的 HTTP-upgrade 传输；v2ray-http-upgrade-fast-open 进一步把客户端载荷捎带在握手上以省一次 RTT。
• shadow-tls-opts、restls-opts、jls-opts、reality-opts 与 tlsmirror-opts 是互斥的 TLS 伪装模式 —— 最多启用一个，且都需要 tls: true。Shadow-TLS、Restls 与 JLS 仅支持 TCP，与 network: mkcp 组合会被拒绝。入站对应的 shadow-tls、res-tls 与 jls-config 同样互斥。
• V2Ray 兼容的 mekya 与 mkcp 传输把设置放在专用块中：出站为 mekya-opts / mkcp-opts，监听器为 mekya-config / mkcp-config。Mekya 把 KCP 帧打包进池化的 HTTP 请求 / 响应交换；mKCP 则直接在 UDP 上运行 KCP。

跨内核说明

• Xray 仅支持 AEAD 并完全移除 alterId；字段名为 security（不是 cipher）。参见 VMess — Xray-core。
• sing-box 保留 alterId（出站为 alter_id，入站用户为 alterId），使用 security 而非 cipher，并通过专门的 multiplex 块暴露多路复用。参见 VMess — sing-box。

源码： adapter/outbound/vmess.go:53-172 · v1.19.29 (e26714a)