V2Ray 配置文件结构与参数说明

01 / JSON STRUCTURE

配置文件结构总览

先按流量方向理解顶层对象

V2Ray 与 Xray 的配置文件通常是一个 JSON 对象。真正需要先记住的不是字段数量，而是流量方向：应用程序先连接本机的入站监听，内核读取路由规则，选择一个出站，再通过目标出站建立连接。DNS 负责把域名解析成地址，policy 负责会话超时、统计等运行策略，log 则决定日志写到哪里以及记录到什么级别。

inbounds 和 outbounds 都是数组，因为同一实例可以同时监听多个本地端口，也可以准备多个出口。数组中的每个对象通常用 tag 命名，路由规则再通过标签引用它。标签只是实例内部的标识，不会发送给远端；名称可以自行确定，但应保持简短、稳定并能看出用途，例如 socks-in、proxy、direct 和 block。

一个便于阅读的配置顺序是：先写日志，再写 DNS，然后写入站、出站、路由和策略。JSON 本身不要求这个顺序，但固定排列能减少排查时间。遇到启动失败时，可以从文件开头向下检查；比较两份配置时，也更容易找到变化。图形客户端生成的顺序可能不同，只要层级和字段有效，执行结果不会因为对象键的排列顺序而改变。

{
  "log": {
    "loglevel": "warning"
  },
  "dns": {},
  "inbounds": [],
  "outbounds": [],
  "routing": {},
  "policy": {}
}

JSON 语法与配置语义是两层检查

配置能被 JSON 解析，只表示括号、引号、逗号和数据类型符合语法，并不代表所有字段都被当前内核接受。例如端口写成字符串，可能是合法 JSON，却不符合该字段需要整数的要求；出站标签拼写不一致，也可能等到匹配路由时才暴露问题。排查时要分两步：先确认 JSON 可以解析，再查看内核日志中关于未知字段、类型错误、标签缺失或协议设置不完整的提示。

标准 JSON 不允许注释，也不允许对象或数组最后一项后面保留多余逗号。复制示例时尤其要注意这一点。文档为了讲解经常展示片段，片段本身只有放进正确的父级对象才有效。例如单独复制一个 routing 对象时，必须把它作为顶层的 "routing" 值，而不是直接粘贴到文件末尾。字符串必须使用双引号，布尔值使用 true 或 false，不能加引号。

修改前建立可回退的基线

开始调整前，先让当前配置在不修改的情况下成功启动一次，并记下正在使用的本地端口、系统代理模式和内核名称。接着复制配置文件，给副本加上用途明确的文件名。每次只改一个逻辑单元，例如先增加直连出站，验证后再添加路由规则。一次改动多个区域虽然更快，但启动失败时很难判断是语法、标签还是协议参数造成的。

图形客户端可能在更新订阅、切换节点或重启核心时重新生成运行配置。此时直接编辑临时文件，改动可能不会长期保留。v2rayN 中应优先使用客户端提供的自定义配置、路由设置或高级选项；Android 客户端则先确认当前配置来自订阅节点还是手工配置。想了解某个术语的边界，可同时查看术语表，避免把“入站”“系统代理”和“路由模式”理解成同一个功能。

03 / OUTBOUNDS

outbounds 出站配置

代理、直连与阻断组成基础出口

出站定义内核把流量送往哪里。完整配置通常至少包含代理出口和直连出口，需要明确拒绝某类连接时再增加阻断出口。代理出口保存服务器地址、端口、用户标识、加密或传输设置；直连出口让内核直接访问目标；阻断出口则主动终止被规则匹配的连接。routing 不负责建立连接，它只负责把当前请求交给某个出站标签。

出站数组的顺序值得留意。当某条连接没有命中任何路由规则时，常见实现会使用第一个出站作为默认出口。因此，把代理放第一项还是把直连放第一项，会直接影响漏网流量的去向。不要只依赖默认顺序表达关键策略，重要流量应写清楚规则；同时仍要让第一项符合整体预期，防止新增域名或遗漏条件时产生意外结果。

{
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-2222-4333-8444-555555555555",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "server.example.com"
        }
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {
        "response": {
          "type": "none"
        }
      }
    }
  ]
}

协议身份参数与传输参数要分开看

排查代理出站时，先把字段分成两组。第一组是协议身份参数，例如服务器地址、端口、用户 ID 和协议要求的附加设置；第二组是 streamSettings 中的传输参数，例如 TCP、WebSocket、gRPC、TLS 或 REALITY。两组参数分别正确但组合关系不一致，连接仍然无法建立。例如远端使用 WebSocket，而本地写成 TCP；服务器证书对应的名称与 serverName 不同；用户标识正确，但端口指向另一项服务。

订阅导入的价值之一，就是把服务提供方给出的协议、传输、安全层和主机参数一起写入客户端。手工迁移时不要只复制地址与端口。看到“节点能测试但网页打不开”时，也不要立即认定出站身份参数全部正确：客户端测试方法可能只覆盖部分链路，真实应用还会涉及 DNS、UDP、路由和系统代理。应结合运行日志判断失败发生在解析、连接远端、握手还是目标访问阶段。

直连出口同样会受到 DNS 与网络环境影响

freedom 表示由当前设备直接建立目标连接。它不是绕过整个配置流程，而是仍然经过入站和 routing 后，由内核执行直连。直连失败时要检查本地网络、系统 DNS、目标地址以及出站的域名策略。若规则根据域名选择 direct，但目标在建立连接前需要解析，解析结果和地址族会影响后续行为。某些环境中 IPv6 记录存在但实际连接条件不完整，也可能表现为等待较久后超时。

可以为 freedom 出站设置适当的域名解析策略，但不同内核支持的取值和行为可能有差异。没有明确需要时，先保留客户端生成的默认值。调试过程中若想判断问题是否来自分流，可以临时建立一条范围很小、目标明确的规则送往 direct，而不是把全部规则删除。验证完成后再恢复，避免临时测试改变其他应用的流量路径。

代理链与多出口要从简单结构开始

一个配置可以包含多个代理出站，并通过路由标签选择，也可以让一个出口经由另一个出口建立底层连接。这样的结构适合有明确链路需求的环境，但标签依赖会迅速增加。开始配置前先画出“入站 → 路由 → 第一出口 → 底层出口”的顺序，确保不存在相互引用。若 proxy-a 依赖 proxy-b，而 proxy-b 又回到 proxy-a，内核无法得到有效链路。

多节点选择通常由 v2rayN、v2rayNG 或 v2flyNG 的配置管理功能完成。客户端切换节点时，会调整当前使用的出站或重新生成运行配置。直接在生成文件中塞入大量服务器对象，不一定能与客户端的切换逻辑配合。桌面场景优先让 v2rayN 管理节点，只把稳定的自定义路由和 DNS 需求放到客户端支持的扩展位置，这比长期手工维护一整份节点清单更容易回退。

05 / DNS

dns 解析配置

先分清系统解析与内核解析

DNS 配置容易出错，是因为一台设备上可能同时存在多条解析路径。应用可以先调用系统 DNS 得到 IP，再把 IP 交给代理；内核也可以为了路由判断主动解析域名；TUN 场景还可能由客户端接管系统查询。配置文件中的 dns 主要定义内核自身如何解析，并不自动保证所有应用查询都经过这里。判断问题前，先确认日志中进入内核的是域名还是已经解析好的 IP。

如果应用把域名直接交给 SOCKS 或 HTTP 代理，内核有机会按自己的 DNS 配置处理。若应用在本地先解析，routing 看到的可能只有地址，此时 DNS 配置对该次原始查询不一定生效。sniffing 可以从部分连接中恢复域名，但不能替代完整的查询接管。因此“已经写了 dns 对象”与“所有程序都使用该 DNS”不是同一件事。

{
  "dns": {
    "hosts": {
      "router.home.arpa": "192.168.1.1"
    },
    "servers": [
      {
        "address": "1.1.1.1",
        "domains": [
          "domain:example.com"
        ],
        "skipFallback": true
      },
      "localhost"
    ],
    "queryStrategy": "UseIP"
  }
}

servers 数组既有顺序，也可以附带条件

servers 可以包含简单地址，也可以使用对象为某个服务器附加域名条件、期望地址范围或回退行为。简单配置从一两个稳定解析源开始即可。服务器越多，不代表解析越可靠；如果各服务器的使用条件不清楚，失败时很难判断查询实际发往哪里。对象中的 domains 用于让指定域名优先交给该服务器，适合内部域名或有明确解析来源的服务。

skipFallback 的目的，是控制匹配当前服务器条件的查询是否还参与后续回退。启用前要确认该服务器确实能够解析所列域名，否则查询失败后可能不会再尝试其他来源。对于局域网主机名，直接使用本地解析服务器或 hosts 静态映射通常更清楚。把内部名称交给公共解析源，不仅得不到结果，还可能让排查方向偏离本地网络。

hosts 适合稳定映射，不适合维护动态地址

hosts 可以把域名映射到固定地址，也可以用于少量别名关系。它在测试新服务、覆盖局域网主机名或临时绕开错误解析时很方便。由于映射优先于普通查询，写错后会持续把连接送往错误目标。使用 hosts 排错时，要记录新增项并在验证后决定是否保留，避免数周后地址已经变化，配置仍固定在旧值。

映射值的数据形态要符合内核要求，域名键也应写成预期的完整名称。若目标同时有 IPv4 与 IPv6，单一固定映射会改变正常的地址选择。对于由服务方动态调度的域名，不建议用 hosts 长期固定某个结果；看似缩短了一次查询，实际可能失去故障切换和地址更新能力。遇到偶发连接问题，应先比较解析结果与连接日志，而不是立刻把当前 IP 写死。

queryStrategy 影响地址族选择

queryStrategy 用来控制查询 IPv4、IPv6 或两类地址的倾向。不同内核支持的具体取值可能有所差异，应以当前客户端所用内核的有效配置为准。设备所在网络只有稳定 IPv4 时，强制只返回 IPv6 会导致目标不可达；网络具备 IPv6 并不表示每条远端链路都适合优先使用它。选择策略时要结合本地网络、代理服务器地址和目标出站的能力。

典型现象是域名解析很快，但连接在某个地址族上持续等待，随后回退或超时。此时可以分别查看解析得到的 A 与 AAAA 记录，再观察内核实际尝试的目标地址。不要把所有 timeout 都归为节点故障。若切换查询策略后恢复，应继续确认是本地 IPv6 路由、远端服务器监听还是目标网络路径的问题，而不是永久依赖一个偶然有效的设置。

DNS 与 routing 需要闭环检查

当 domainStrategy 需要解析域名以匹配 IP 规则时，routing 会调用 DNS；解析查询本身又可能通过某个出站发送。设计不当会出现循环依赖：为了决定域名走哪个出口先发起查询，但查询出口又依赖尚未完成的域名分类。简单环境应避免给 DNS 设计过度复杂的路由链。先确保基础查询可用，再为明确的解析服务器地址添加直连或代理规则。

检查闭环可以按四步进行：第一，看应用交给入站的是域名还是 IP；第二，看路由策略是否需要解析；第三，看查询由哪个服务器处理；第四，看查询连接本身通过哪个出站。任何一步与预期不同，最终都会表现成网页打不开或分流错误。v2rayN 的日志可以帮助定位查询和连接阶段，阅读方法可参考V2Ray 运行日志怎么看。

07 / ASSEMBLY

组合完整配置与启动前检查

先构建最小闭环，再逐层增加能力

组合配置时，最可靠的顺序是先建立最小闭环：一个仅监听本机的 SOCKS 入站、一个有效代理出站、一个直连出站，以及少量方向明确的路由规则。最小配置能够启动并完成连接后，再增加 HTTP 入站、DNS 条件、阻断规则和 policy。这样每次新增的范围有限，出现问题时可以直接回退到上一份可用配置。

完整文件中的每个标签都要形成引用闭环。routing 使用的 outboundTag 必须能在 outbounds 中找到；inboundTag 必须与 inbounds 的标签一致；用户 level 若关联 policy，也要存在对应策略。标签区分大小写时，Proxy 与 proxy 会被视为不同名称。建议只使用小写字母、数字和短横线，减少输入错误。

{
  "log": {
    "loglevel": "warning"
  },
  "dns": {
    "servers": [
      "localhost"
    ],
    "queryStrategy": "UseIP"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls"
        ]
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-2222-4333-8444-555555555555",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "server.example.com"
        }
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  },
  "policy": {
    "levels": {
      "0": {
        "handshake": 4,
        "connIdle": 300
      }
    }
  }
}

示例完整不等于节点参数可以直接使用

上面的 JSON 层级完整，可以用于理解各部分如何组合，但其中的服务器域名和用户 ID 是文档示例。实际配置必须替换为自己订阅或服务信息中的完整参数，并让 streamSettings 与远端一致。若实际节点使用的不是示例中的协议或传输方式，应替换整个代理出站对象，而不是只改协议名称。协议对象内部结构不同，简单改一个字符串会留下不兼容字段。

使用 v2rayN、v2rayNG 或 v2flyNG 时，优先导入节点后观察客户端生成的出站结构，再把需要的路由思想应用到客户端支持的位置。不要为了使用本文示例而放弃客户端已经正确生成的节点参数。配置参考的用途是解释结构和帮助排错，不是让每位用户都从空文件手写全部连接信息。

执行语法检查与内核配置检查

第一层检查可以使用支持 JSON 的编辑器确认括号、引号和逗号。第二层需要让实际内核读取配置。独立运行 Xray 时，常见测试方式是执行 xray run -test -config config.json；独立运行 V2Ray 时，可根据当前可执行文件支持的命令使用 v2ray test -c config.json。命令名称和参数应以本机内核帮助输出为准，因为客户端封装方式和可执行文件位置可能不同。

图形客户端用户通常不需要手工打开终端测试临时配置。重新启动内核后查看客户端日志即可。若客户端启动前会重新生成文件，应在它提供的编辑入口中保存改动。测试结果报告未知字段时，先确认当前是 V2Fly 还是 Xray 内核，再检查该字段属于顶层、入站设置、协议设置还是 streamSettings。把正确字段放错层级，同样会被判定无效。

按数据流做启动后的四段验证

配置通过读取后，还要验证运行链路。第一段检查入站：确认端口正在监听，应用代理类型与端口对应。第二段检查路由：访问一个目标，查看日志选择了 proxy 还是 direct。第三段检查出站：观察远端连接与握手是否完成。第四段检查目标响应：确认应用拿到实际内容，而不是仅建立了本地代理连接。

如果第一段失败，重点看端口占用和监听地址；第二段错误，检查规则顺序、目标形式和标签；第三段失败，检查节点、网络和传输参数；前三段正常但第四段异常，再看 DNS、目标服务和应用自身行为。这种分段方法比不停更换节点更有效，也能避免把本地端口问题误判为远端故障。

客户端覆盖配置时如何保留改动

v2rayN 在切换服务器、更新订阅或改变代理模式后，可能重新组织内核运行配置。需要长期保留的内容，应放进客户端支持的自定义路由、DNS 或自定义配置功能，而不是只编辑运行目录里的临时 JSON。修改前先导出或记录当前设置，更新后再确认自定义规则仍被合并。首次安装与配置文件位置相关的注意事项，可查看v2rayN 首次安装与初始设置全流程。

Android 客户端也可能把单节点配置、订阅条目和运行配置分开保存。编辑某个节点只会改变该节点的协议参数，不一定改变全局路由。先确认当前页面修改的是节点、路由还是应用设置，再测试结果。v2rayNG 首推使用 Xray 内核路径，v2flyNG 作为 v2fly 内核备选；两者扩展字段存在差异时，不应直接互相复制完整 JSON。