Skip to content

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 字段备注
节点名nameoutbounds[].tag必须唯一,含中文需注意编码
协议类型type: vmess/vless/trojan/ssprotocol: vmess/vless/trojan/shadowsocksss 在 V2Ray 中叫 shadowsocks
服务器serversettings.vnext[].address(vmess/vless)或 settings.servers[].address(ss)结构差异最大处
端口portsettings.vnext[].port整数
用户 IDuuidsettings.vnext[].users[].idvmess/vless
加密方式ciphersettings.vnext[].users[].security(vmess)/ settings.method(ss)vmess 默认 auto
TLStls: true + servernamestreamSettings.security: tls + tlsSettings.serverName
WS 传输network: ws + ws-opts.pathstreamSettings.network: ws + wsSettings.path
gRPCnetwork: grpc + grpc-opts.grpc-service-namestreamSettings.network: grpc + grpcSettings.serviceName
Realityreality-opts.public-keystreamSettings.security: reality + realitySettings.publicKey仅 Xray 支持
指纹client-fingerprinttlsSettings.fingerprint

1.2 规则匹配语法的表达力差异 ​

Clash 的规则类型与 V2Ray 的谓词字段并非一一对应,转换时必须做语义映射而非字面替换:

Clash 规则类型示例V2Ray 等价写法转换损耗
DOMAINDOMAIN,api.example.com,PROXYdomain: ["full:api.example.com"]无
DOMAIN-SUFFIXDOMAIN-SUFFIX,google.com,PROXYdomain: ["domain:google.com"]无
DOMAIN-KEYWORDDOMAIN-KEYWORD,ads,REJECTdomain: ["keyword:ads"]无
IP-CIDRIP-CIDR,10.0.0.0/8,DIRECTip: ["10.0.0.0/8"]无
GEOIPGEOIP,CN,DIRECTip: ["geoip:cn"]需 geoip.dat
GEOSITEGEOSITE,cn,DIRECTdomain: ["geosite:cn"]需 geosite.dat
PROCESS-NAMEPROCESS-NAME,curl,DIRECTprocess: ["curl"](仅部分平台)平台相关
MATCHMATCH,PROXY兜底规则放最后,无谓词无

MATCH 是 Clash 的兜底规则,在 V2Ray 中对应一条不含 domain/ip/port 谓词的规则,必须放在 routing.rules 数组末尾,否则后续规则永远不会命中。这个顺序语义在互转时极易被脚本作者忽略。

二、生产级实机测试床环境参数 ​

本文所有实测数据来自以下环境,读者可复现:

项目参数
内核Linux 6.8.0-45-generic(Ubuntu 24.04.1 LTS)
CPUAMD 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,PROXY

3.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

关键观察点:

  1. SNI 字段必须等于配置里的 servername(本例 www.microsoft.com)。若转换脚本漏掉 realitySettings.serverName,SNI 会退化为服务器 IP 或空,中间设备一眼识别。
  2. JA3 指纹由 fingerprint: chrome 决定。实测 chrome 指纹的 JA3 哈希与真实 Chrome 126 一致(cd08e31494f9531f560d64c695473da9),而 Go 默认 TLS 栈的 JA3 是 3b5074b1b5d032e432b9761947de44d2,两者在被动指纹库里分属“浏览器”与“Go 程序”两类。
  3. Vision 流控在握手完成后,应用数据段的 TLS record 长度分布与真实 HTTPS 流量无统计学差异(实测 1000 个 record 的长度熵为 7.82 bit,真实 Chrome 为 7.79 bit)。
  4. 时序特征: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 ms40.8 ms158.6 ms157.9 ms
RTT 抖动 σ3.1 ms2.9 ms11.4 ms10.8 ms
丢包率0.02%0.01%0.31%0.28%
下行吞吐486 Mbps491 Mbps213 Mbps219 Mbps
上行吞吐302 Mbps308 Mbps96 Mbps99 Mbps
客户端 CPU(单核)12.4%12.1%9.8%9.6%
首包时间(curl)62 ms60 ms189 ms186 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 踩坑清单 ​

  1. MATCH 规则未置底:转换后兜底规则跑到数组中间,后续规则全部失效,表现为“部分网站走错出口”。
  2. flow 字段丢失:VLESS + Vision 漏写 flow: xtls-rprx-vision,连接建立但吞吐骤降至 1/10。
  3. shortId 空串 vs 缺字段:Reality 的 shortId 允许空串,但字段缺失会导致 publicKey 校验路径不同,表现为间歇性握手失败。
  4. 策略组名与节点 tag 冲突:V2Ray 的 outboundTag 必须指向真实 outbound tag,Clash 的 PROXY 是组名不是节点名,脚本未做映射时规则全部指向不存在的 tag。
  5. alterId 默认值:VMess 的 alterId 在 Clash 侧默认 0,V2Ray 侧若写成非 0 会触发 AEAD 兼容问题。
  6. WS Host 头:Clash 的 ws-opts.headers.Host 在 JSON 里是 wsSettings.headers.Host,漏掉会被 CDN 拒绝。
  7. domainStrategy 未设:V2Ray 默认 AsIs,GEOIP 规则对域名流量不生效,需显式设 IPIfNonMatch。
  8. 订阅 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/ 的基准测试规范。