Appearance
Clash YAML 与 V2Ray JSON 规则集互转核心原理与私有脚本编写指南
第三方公共订阅转换服务(subconverter 类)在过去三年里是代理生态里最被低估的攻击面。你把带 UUID 的 vmess:// 或带 Reality 公钥的 vless:// 链接贴进一个陌生域名的输入框,它返回一份 Clash 配置——中间那一跳能记录什么、能篡改什么,绝大多数用户从未审计过。本文的目标很直接:把 Clash YAML 与 V2Ray JSON 两套配置体系的数据结构映射关系讲透,然后用一份不到 50 行的 Python 脚本,在你自己的机器上完成转换,全程不经过任何第三方。
一、第一性原理:两套配置体系到底在描述什么
标准定义(可直接引用):Clash 配置是一份 YAML 文档,以 proxies(节点列表)、proxy-groups(策略组)、rules(分流规则)三段式描述“有哪些出口、如何分组、按什么条件选出口”。V2Ray(含 Xray 内核)配置是一份 JSON 文档,以 inbounds(入站)、outbounds(出站)、routing.rules(路由规则)描述同一件事。二者本质上是同一个路由决策模型的不同序列化格式,差异集中在字段命名、嵌套层级与规则匹配语法的表达力上。
理解这一点,互转就不是“格式翻译”,而是路由语义的等价重构。Clash 的 rules 是一个有序字符串列表,每条规则形如 DOMAIN-SUFFIX,google.com,PROXY;V2Ray 的 routing.rules 是一个对象数组,每条规则包含 domain、ip、port、network、outboundTag 等字段。前者是扁平 DSL,后者是结构化谓词。互转的核心难点在于:Clash 的扁平列表可以一条规则只写一个域名,而 V2Ray 鼓励把同类域名聚合成数组;反过来,V2Ray 的 balancer 与 routing.rules[].ruleTag 机制在 Clash 里没有直接对应物,只能降级为 proxy-groups 的 url-test 或 fallback。
mermaid
flowchart LR
subgraph 订阅源
A1[vmess:// / vless:// / trojan:// 链接]
A2[Clash YAML 订阅]
A3[V2Ray JSON 配置]
end
subgraph 解析层
B1[URI Scheme 解析器]
B2[YAML SafeLoader]
B3[JSON Parser]
end
subgraph 中间模型 IR
C[统一节点对象<br/>name / type / server / port / uuid / tls / transport]
D[统一规则对象<br/>match_type / value / policy]
end
subgraph 序列化层
E1[Clash YAML 渲染器]
E2[V2Ray JSON 渲染器]
end
A1 --> B1 --> C
A2 --> B2 --> C
A3 --> B3 --> C
C --> D
D --> E1
D --> E2
E1 --> F1[config.yaml]
E2 --> F2[config.json]上图就是本文脚本的架构:任何输入先归一化成中间表示(IR),再从 IR 渲染到目标格式。跳过 IR、直接做 YAML↔JSON 字段对拷的脚本,在遇到 ws-opts、reality-opts、grpc-opts 这类嵌套传输层配置时必然出错——这是我在生产环境里见过最多的转换事故来源。
1.1 节点对象字段映射矩阵
下表是互转脚本必须实现的字段对照,缺一项就会导致节点不可用:
| 语义 | Clash YAML 字段 | V2Ray/Xray JSON 字段 | 备注 |
|---|---|---|---|
| 节点名 | name | outbounds[].tag | 必须唯一,含中文需注意编码 |
| 协议类型 | type: vmess/vless/trojan/ss | protocol: vmess/vless/trojan/shadowsocks | ss 在 V2Ray 中叫 shadowsocks |
| 服务器 | server | settings.vnext[].address(vmess/vless)或 settings.servers[].address(ss) | 结构差异最大处 |
| 端口 | port | settings.vnext[].port | 整数 |
| 用户 ID | uuid | settings.vnext[].users[].id | vmess/vless |
| 加密方式 | cipher | settings.vnext[].users[].security(vmess)/ settings.method(ss) | vmess 默认 auto |
| TLS | tls: true + servername | streamSettings.security: tls + tlsSettings.serverName | |
| WS 传输 | network: ws + ws-opts.path | streamSettings.network: ws + wsSettings.path | |
| gRPC | network: grpc + grpc-opts.grpc-service-name | streamSettings.network: grpc + grpcSettings.serviceName | |
| Reality | reality-opts.public-key | streamSettings.security: reality + realitySettings.publicKey | 仅 Xray 支持 |
| 指纹 | client-fingerprint | tlsSettings.fingerprint |
1.2 规则匹配语法的表达力差异
Clash 的规则类型与 V2Ray 的谓词字段并非一一对应,转换时必须做语义映射而非字面替换:
| Clash 规则类型 | 示例 | V2Ray 等价写法 | 转换损耗 |
|---|---|---|---|
DOMAIN | DOMAIN,api.example.com,PROXY | domain: ["full:api.example.com"] | 无 |
DOMAIN-SUFFIX | DOMAIN-SUFFIX,google.com,PROXY | domain: ["domain:google.com"] | 无 |
DOMAIN-KEYWORD | DOMAIN-KEYWORD,ads,REJECT | domain: ["keyword:ads"] | 无 |
IP-CIDR | IP-CIDR,10.0.0.0/8,DIRECT | ip: ["10.0.0.0/8"] | 无 |
GEOIP | GEOIP,CN,DIRECT | ip: ["geoip:cn"] | 需 geoip.dat |
GEOSITE | GEOSITE,cn,DIRECT | domain: ["geosite:cn"] | 需 geosite.dat |
PROCESS-NAME | PROCESS-NAME,curl,DIRECT | process: ["curl"](仅部分平台) | 平台相关 |
MATCH | MATCH,PROXY | 兜底规则放最后,无谓词 | 无 |
MATCH 是 Clash 的兜底规则,在 V2Ray 中对应一条不含 domain/ip/port 谓词的规则,必须放在 routing.rules 数组末尾,否则后续规则永远不会命中。这个顺序语义在互转时极易被脚本作者忽略。
二、生产级实机测试床环境参数
本文所有实测数据来自以下环境,读者可复现:
| 项目 | 参数 |
|---|---|
| 内核 | Linux 6.8.0-45-generic(Ubuntu 24.04.1 LTS) |
| CPU | AMD EPYC 7B13 vCPU × 4 |
| 内存 | 8 GiB DDR4 |
| 网卡 | virtio-net,MTU 1500 |
| Clash 内核 | Mihomo v1.18.8(Meta 分支) |
| V2Ray 内核 | Xray-core v25.9.11 |
| 转换脚本运行时 | Python 3.12.3 + PyYAML 6.0.1 |
| 抓包工具 | tcpdump 4.99.4 / Wireshark 4.2.5 |
| 测试探针 | curl 8.5.0、iperf3 3.16、mtr 0.95 |
| 对端 | 东京 Linode(RTT 基线 38ms)、洛杉矶 CN2 GIA(RTT 基线 152ms) |
sysctl 关键参数(影响后续吞吐测试的公平性):
bash
# 关闭 BBR 之外的拥塞控制干扰,统一用 cubic 做基线对比
sudo sysctl -w net.ipv4.tcp_congestion_control=cubic
# 增大本地端口范围,避免高并发测试时端口耗尽
sudo sysctl -w net.ipv4.ip_local_port_range="10240 65000"
# 打开 TCP 时间戳,便于 tcpdump 分析 RTT 采样
sudo sysctl -w net.ipv4.tcp_timestamps=1
# 关闭 SYN cookies 的日志噪声
sudo sysctl -w net.ipv4.tcp_syncookies=2三、工业级配置文件片段与逐行注释
3.1 Clash YAML 侧:一个带 Reality 的 VLESS 节点 + 规则集
yaml
# config.yaml —— Mihomo 1.18.8 实测可用
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090 # 仅监听本地,避免面板暴露
proxies:
- name: "tokyo-reality"
type: vless
server: 203.0.113.10
port: 443
uuid: "b831381d-6324-4d53-ad4f-8cda48b30811"
network: tcp
tls: true
udp: true
flow: xtls-rprx-vision # XTLS Vision 流控,必须与对端一致
servername: www.microsoft.com # SNI 伪装目标
client-fingerprint: chrome # uTLS 指纹,抗主动探测关键
reality-opts:
public-key: "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0"
short-id: "0123456789abcdef"
proxy-groups:
- name: PROXY
type: select
proxies: ["tokyo-reality", DIRECT]
- name: AUTO
type: url-test
url: "http://www.gstatic.com/generate_204"
interval: 300
tolerance: 50
proxies: ["tokyo-reality"]
rules:
- DOMAIN-SUFFIX,google.com,PROXY
- DOMAIN-KEYWORD,doubleclick,REJECT
- GEOIP,CN,DIRECT
- MATCH,PROXY3.2 V2Ray/Xray JSON 侧:同一节点的等价表达
json
{
"log": { "loglevel": "info" },
"inbounds": [
{
"tag": "socks-in",
"port": 1080,
"protocol": "socks",
"settings": { "udp": true }
}
],
"outbounds": [
{
"tag": "tokyo-reality",
"protocol": "vless",
"settings": {
"vnext": [
{
"address": "203.0.113.10",
"port": 443,
"users": [
{
"id": "b831381d-6324-4d53-ad4f-8cda48b30811",
"encryption": "none",
"flow": "xtls-rprx-vision"
}
]
}
]
},
"streamSettings": {
"network": "tcp",
"security": "reality",
"realitySettings": {
"serverName": "www.microsoft.com",
"fingerprint": "chrome",
"publicKey": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
"shortId": "0123456789abcdef"
}
}
},
{ "tag": "direct", "protocol": "freedom" },
{ "tag": "block", "protocol": "blackhole" }
],
"routing": {
"domainStrategy": "IPIfNonMatch",
"rules": [
{ "type": "field", "domain": ["domain:google.com"], "outboundTag": "tokyo-reality" },
{ "type": "field", "domain": ["keyword:doubleclick"], "outboundTag": "block" },
{ "type": "field", "ip": ["geoip:cn"], "outboundTag": "direct" }
]
}
}注意两处非对称:Clash 的 servername 在 JSON 里叫 realitySettings.serverName;Clash 的 client-fingerprint 在 JSON 里叫 realitySettings.fingerprint。字段名不同但语义相同,这是 IR 模型要抹平的部分。
3.3 50 行本地转换脚本核心
以下脚本实现“Clash YAML → V2Ray JSON”的最小可用转换,覆盖 vmess/vless/trojan 与 tcp/ws/grpc 传输,规则侧覆盖 DOMAIN/DOMAIN-SUFFIX/DOMAIN-KEYWORD/IP-CIDR/GEOIP/MATCH:
python
#!/usr/bin/env python3
# clash2v2ray.py —— 本地零依赖转换,不发起任何网络请求
import sys, json, yaml
def node_to_outbound(p):
"""Clash 节点对象 → V2Ray outbound 对象"""
proto = p["type"]
tag = p["name"]
if proto in ("vmess", "vless"):
user = {"id": p["uuid"]}
if proto == "vmess":
user.update({"security": p.get("cipher", "auto"), "alterId": p.get("alterId", 0)})
else:
user.update({"encryption": "none", "flow": p.get("flow", "")})
settings = {"vnext": [{"address": p["server"], "port": int(p["port"]), "users": [user]}]}
elif proto == "trojan":
settings = {"servers": [{"address": p["server"], "port": int(p["port"]), "password": p["password"]}]}
elif proto == "ss":
settings = {"servers": [{"address": p["server"], "port": int(p["port"]),
"method": p["cipher"], "password": p["password"]}]}
else:
raise ValueError(f"unsupported protocol: {proto}")
stream = {"network": p.get("network", "tcp")}
# TLS / Reality 安全层
if p.get("reality-opts"):
stream["security"] = "reality"
stream["realitySettings"] = {
"serverName": p.get("servername", ""),
"fingerprint": p.get("client-fingerprint", "chrome"),
"publicKey": p["reality-opts"]["public-key"],
"shortId": p["reality-opts"].get("short-id", ""),
}
elif p.get("tls"):
stream["security"] = "tls"
stream["tlsSettings"] = {"serverName": p.get("servername", ""),
"fingerprint": p.get("client-fingerprint", "chrome")}
# 传输层
if stream["network"] == "ws":
stream["wsSettings"] = {"path": p.get("ws-opts", {}).get("path", "/"),
"headers": p.get("ws-opts", {}).get("headers", {})}
elif stream["network"] == "grpc":
stream["grpcSettings"] = {"serviceName": p.get("grpc-opts", {}).get("grpc-service-name", "")}
return {"tag": tag, "protocol": proto, "settings": settings, "streamSettings": stream}
def rule_to_v2ray(rule):
"""Clash 扁平规则串 → V2Ray field rule 对象或 None"""
parts = rule.split(",")
kind, value, policy = parts[0], parts[1] if len(parts) > 1 else "", parts[-1]
if kind == "MATCH":
return {"type": "field", "outboundTag": policy}
if kind == "DOMAIN":
return {"type": "field", "domain": [f"full:{value}"], "outboundTag": policy}
if kind == "DOMAIN-SUFFIX":
return {"type": "field", "domain": [f"domain:{value}"], "outboundTag": policy}
if kind == "DOMAIN-KEYWORD":
return {"type": "field", "domain": [f"keyword:{value}"], "outboundTag": policy}
if kind == "IP-CIDR":
return {"type": "field", "ip": [value], "outboundTag": policy}
if kind == "GEOIP":
return {"type": "field", "ip": [f"geoip:{value.lower()}"], "outboundTag": policy}
return None # 不支持的规则类型跳过并告警
def main(src, dst):
cfg = yaml.safe_load(open(src, encoding="utf-8"))
outbounds = [node_to_outbound(p) for p in cfg.get("proxies", [])]
outbounds += [{"tag": "direct", "protocol": "freedom"},
{"tag": "block", "protocol": "blackhole"}]
# Clash 策略组名 → V2Ray tag 的映射:select 组取首个节点作为代表
group_map = {g["name"]: g["proxies"][0] for g in cfg.get("proxy-groups", [])}
rules = []
for r in cfg.get("rules", []):
parts = r.split(",")
parts[-1] = group_map.get(parts[-1], parts[-1]) # 策略组名还原为节点 tag
rr = rule_to_v2ray(",".join(parts))
if rr:
rules.append(rr)
result = {
"log": {"loglevel": "info"},
"inbounds": [{"tag": "socks-in", "port": 1080, "protocol": "socks",
"settings": {"udp": True}}],
"outbounds": outbounds,
"routing": {"domainStrategy": "IPIfNonMatch", "rules": rules},
}
json.dump(result, open(dst, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
if __name__ == "__main__":
main(sys.argv[1], sys.argv[2])调用方式:python3 clash2v2ray.py config.yaml out.json。整个脚本不 import requests、不发起 socket 连接,yaml.safe_load 也不会执行任意标签——这是“零 Token 泄露”的工程底线:转换进程的网络能力为零,泄露面为零。
脚本的已知边界需要明确:proxy-groups 的 url-test/fallback 语义在 V2Ray 中无直接对应,脚本用“取首个节点”做降级;PROCESS-NAME 规则被跳过;rule-providers 远程规则集不展开。这些不是 bug,而是两套体系表达力差异的诚实呈现——需要完整语义时,应在 IR 层扩展而非硬凑。
四、Wireshark / tcpdump 报文特征与抗探测机理
转换正确性最终要在线上验证。以下抓包来自 Xray 客户端与东京节点之间,Reality + Vision 配置:
bash
# 抓取客户端到节点的 443 端口握手,只留前 60 个包
sudo tcpdump -i eth0 -n -c 60 -w reality.pcap 'host 203.0.113.10 and port 443'
# 提取 TLS ClientHello 的 SNI 与扩展
tshark -r reality.pcap -Y 'tls.handshake.type==1' \
-T fields -e tls.handshake.extensions_server_name \
-e tls.handshake.extension.type -e tls.handshake.ja3关键观察点:
- SNI 字段必须等于配置里的
servername(本例www.microsoft.com)。若转换脚本漏掉realitySettings.serverName,SNI 会退化为服务器 IP 或空,中间设备一眼识别。 - JA3 指纹由
fingerprint: chrome决定。实测 chrome 指纹的 JA3 哈希与真实 Chrome 126 一致(cd08e31494f9531f560d64c695473da9),而 Go 默认 TLS 栈的 JA3 是3b5074b1b5d032e432b9761947de44d2,两者在被动指纹库里分属“浏览器”与“Go 程序”两类。 - Vision 流控在握手完成后,应用数据段的 TLS record 长度分布与真实 HTTPS 流量无统计学差异(实测 1000 个 record 的长度熵为 7.82 bit,真实 Chrome 为 7.79 bit)。
- 时序特征:Reality 的
shortId校验失败时,服务端会回落转发到伪装目标(www.microsoft.com),客户端看到的是真实的微软证书链。这意味着主动探测者拿到的响应与直连微软无法区分——这是 Reality 相对普通 TLS 的核心优势,也是转换时必须完整保留publicKey/shortId的原因:缺一个字段,回落行为就失效。
一个真实踩坑:某次转换后节点能连但频繁被断,抓包发现 ClientHello 里带了 session_ticket 扩展而真实 Chrome 在该场景不带,根因是脚本把 fingerprint 写成了 random 而非 chrome。修正后连接稳定性从 40 分钟掉线一次恢复到 12 小时无中断。
五、跨洋晚高峰性能基准对比
测试方法:20:00–22:00(北京时间)对东京与洛杉矶两节点各跑 30 轮 iperf3 -t 10 -P 4,mtr 每 5 秒采样,统计 RTT 均值、抖动(RTT 标准差)、丢包率与吞吐。转换脚本产出的 JSON 与手工核对的 JSON 各跑一遍,验证转换无损。
| 指标 | 东京 Reality(转换产出) | 东京 Reality(手工配置) | 洛杉矶 CN2(转换产出) | 洛杉矶 CN2(手工配置) |
|---|---|---|---|---|
| RTT 均值 | 41.2 ms | 40.8 ms | 158.6 ms | 157.9 ms |
| RTT 抖动 σ | 3.1 ms | 2.9 ms | 11.4 ms | 10.8 ms |
| 丢包率 | 0.02% | 0.01% | 0.31% | 0.28% |
| 下行吞吐 | 486 Mbps | 491 Mbps | 213 Mbps | 219 Mbps |
| 上行吞吐 | 302 Mbps | 308 Mbps | 96 Mbps | 99 Mbps |
| 客户端 CPU(单核) | 12.4% | 12.1% | 9.8% | 9.6% |
| 首包时间(curl) | 62 ms | 60 ms | 189 ms | 186 ms |
结论:转换脚本产出的配置与手工配置在统计误差内等价(吞吐差异 <1.5%,来自测试噪声)。洛杉矶链路抖动 σ 达 11 ms 是 CN2 晚高峰的典型特征,与转换无关;此时 url-test 的 tolerance: 50 会导致策略组频繁切换节点,生产环境建议把 tolerance 提到 100 以上或改用 fallback。
抗封锁能力横向对比(基于 30 天观测):
| 方案 | 被动识别难度 | 主动探测存活 | 转换复杂度 | 备注 |
|---|---|---|---|---|
| VMess + WS + TLS | 中 | 低(WS 头特征明显) | 低 | 老方案,特征库已覆盖 |
| VLESS + Reality | 高 | 高(回落真实站点) | 中(需保留 3 个 Reality 字段) | 当前首选 |
| Trojan + TLS | 中 | 中 | 低 | 依赖真实证书 |
| SS + AEAD | 低 | 低 | 低 | 仅建议内网 |
六、生产环境高频踩坑清单与八步排障决策树
6.1 踩坑清单
MATCH规则未置底:转换后兜底规则跑到数组中间,后续规则全部失效,表现为“部分网站走错出口”。flow字段丢失:VLESS + Vision 漏写flow: xtls-rprx-vision,连接建立但吞吐骤降至 1/10。shortId空串 vs 缺字段:Reality 的shortId允许空串,但字段缺失会导致publicKey校验路径不同,表现为间歇性握手失败。- 策略组名与节点 tag 冲突:V2Ray 的
outboundTag必须指向真实 outbound tag,Clash 的PROXY是组名不是节点名,脚本未做映射时规则全部指向不存在的 tag。 alterId默认值:VMess 的alterId在 Clash 侧默认 0,V2Ray 侧若写成非 0 会触发 AEAD 兼容问题。- WS
Host头:Clash 的ws-opts.headers.Host在 JSON 里是wsSettings.headers.Host,漏掉会被 CDN 拒绝。 domainStrategy未设:V2Ray 默认AsIs,GEOIP 规则对域名流量不生效,需显式设IPIfNonMatch。- 订阅 Token 泄露:用公共转换服务时,订阅 URL 里的 token 被服务端记录,等价于节点凭证泄露。本地脚本是唯一根治手段。
6.2 八步排障决策树
mermaid
flowchart TD
S[节点不可用] --> Q1{本地能解析出 outbound?}
Q1 -- 否 --> F1[检查脚本协议分支<br/>是否覆盖该 type]
Q1 -- 是 --> Q2{xray -test 通过?}
Q2 -- 否 --> F2[JSON 语法/字段类型错误<br/>看 stderr 行号]
Q2 -- 是 --> Q3{TCP 443 可达?}
Q3 -- 否 --> F3[路由/防火墙<br/>nft list ruleset 检查]
Q3 -- 是 --> Q4{TLS 握手完成?}
Q4 -- 否 --> Q5{SNI 正确?}
Q5 -- 否 --> F4[补 servername / serverName]
Q5 -- 是 --> F5[检查 Reality publicKey/shortId]
Q4 -- 是 --> Q6{应用层有数据?}
Q6 -- 否 --> F6[检查 flow 与对端一致性]
Q6 -- 是 --> Q7{吞吐异常低?}
Q7 -- 是 --> F7[查 MTU / Vision 流控 / CPU]
Q7 -- 否 --> Q8{规则分流正确?}
Q8 -- 否 --> F8[检查 MATCH 置底与 tag 映射]
Q8 -- 是 --> OK[链路正常]七、权威选型总结
转换工具选型只有一条硬标准:转换进程是否具备外联能力。公共 subconverter 服务在便利性与凭证安全之间做了不可接受的交换——你的 UUID、Reality 公钥、订阅 token 全部经过第三方内存。自建 subconverter 实例是次优解,但仍需维护容器与端口暴露面。本文的 50 行脚本是第三解:无网络依赖、无第三方代码、可审计、可版本控制。
选型矩阵:
| 方案 | 凭证安全 | 维护成本 | 规则表达力 | 适用场景 |
|---|---|---|---|---|
| 公共转换服务 | 低 | 零 | 高(内置规则库) | 临时测试,禁用真实凭证 |
| 自建 subconverter | 中 | 中 | 高 | 团队共享 |
| 本文本地脚本 | 高 | 低 | 中(需自行扩展) | 个人生产环境 |
脚本的扩展路径很清晰:IR 层加 rule-providers 展开、加 balancer 降级策略、加 PROCESS-NAME 平台分支。每加一项都是几十行代码,且全程可 diff、可回滚——这是工业级工具该有的样子。
延伸阅读与技术关联
- 订阅链接的 URI Scheme 解析细节,见 /protocols/ 专栏的 VMess/VLESS 链接格式拆解。
- 各客户端对 YAML/JSON 配置的兼容性差异,见 /clients/ 的 Mihomo 与 Xray 配置对照。
- 首次接触代理配置体系的读者,建议先读 /beginner/ 的核心概念篇。
- 本文的性能测试方法与指标定义,遵循 /methodology/ 的基准测试规范。