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	底层传输。
tls	bool	false	true | false	用 TLS 包裹流。
alpn	[]string	[]	h2 | http/1.1	TLS 握手时宣告的 ALPN 列表。
skip-cert-verify	bool	false	true | false	禁用 TLS 证书校验（仅供测试）。
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 配置。
reality-opts	RealityOptions	(disabled)	RealityOptions	REALITY 客户端配置。
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:43-72 · 锚定版本 v1.19.27 (5184081)

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:94-101 · 锚定版本 v1.19.27 (5184081)

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:85-92 · 锚定版本 v1.19.27 (5184081)

入站

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 配置 / 密钥。
reality-config	RealityConfig	(disabled)	RealityConfig	REALITY 服务端配置。
mux-option	MuxOption	(disabled)	MuxOption	多路复用设置（sing 风格 mux）。

源码： listener/inbound/vmess.go:12-24 · 锚定版本 v1.19.27 (5184081)

users[]

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

源码： listener/inbound/vmess.go:26-30 · 锚定版本 v1.19.27 (5184081)

示例

出站 —— 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）字段名不同。允许的取值相同：auto、 aes-128-gcm、chacha20-poly1305、none、zero。
• 出站暴露了三套 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。

跨内核说明

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

源码： adapter/outbound/vmess.go:43-101 · v1.19.27 (5184081)