配置文件参考

V2Ray JSON 手册

如果还没完成安装、导入和首次连接,先读快速上手教程,沿着图形界面走一遍;需要知道某个开关生成了什么字段,或要找出一条连接在哪一步走错,再回到本手册。这里以本地监听、直连和拦截为例,逐层解释客户端交给内核的配置。

JSON 结构:从入口读到出口

配置的根节点是一个对象。把它想成内核启动时要读取的一张连接说明书,而不是客户端界面的逐项备份。inbounds 和 outbounds 是数组,同一进程可以登记多个入口和出口;routing、dns 和 policy 是不同职责的对象。客户端保存的订阅名称、界面偏好或历史测速结果,不属于这张说明书。导出配置前应先确认导出的到底是客户端设置、单个节点,还是某次启动交给内核的完整文件。

完整基线与局部示例的区别

以下是一份完整的本地基线:应用把 SOCKS 请求送到回环地址,内核通过 freedom 出站直接访问目的地。它不是远端节点配置,不需要服务地址或账户。请通过客户端支持的自定义配置入口加载副本;如果已有进程占用同一个端口,先退出该进程,或在副本里换一个空闲端口,同时修改测试应用的代理地址。后续章节的代码多为局部字段,不能把它们依次粘贴到这个文件末尾。

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

这里有三处值得对照。第一,port 是数字,udp 是布尔值,不能为了看起来整齐给两者都加引号。第二,入站和出站都有 protocol 与 settings,但设置的解释方式由各自协议决定,不能把 SOCKS 入站的认证字段平移到直连出站。第三,tag 是文件内部的标识;名称可以自定,但后续引用必须逐字一致。把 direct 改成其他名字,不会改变直连行为,却可能令引用旧名字的规则失效。

阅读顺序不等于字段排列顺序

排查时先顺着连接走:应用把请求交给某个入口,内核判断能得到哪些目标信息,再按规则选择出口,出口按自己的协议和解析策略建立后续连接。DNS 并不是固定插在每条连接正中间的一步。请求一开始就带着数字地址时,内核可能无需查询;应用先在本地解析再交给 SOCKS 时,内核甚至可能看不到原始域名。连接策略则约束某些阶段的等待和统计行为,不承担选路工作。

根对象中各字段的书写顺序通常不影响含义,例如把日志块移到文件末尾,并不会改变日志覆盖的连接范围。数组里的位置却可能决定结果:路由规则按先后匹配,默认出口取决于出站数组的第一项。合并配置时,要分别处理对象和数组。根节点已有 outbounds 就修改原数组,不要再新增同名键;许多解析器会保留靠后的值而不报重复键,导致原来的出口在启动后消失。

在客户端和内核之间找准修改位置

桌面客户端首推 v2rayN,按操作系统和处理器架构从客户端下载页选包。Android 端根据所需内核选择 v2rayNG 或 v2flyNG。图形客户端的常规模板可能在切换节点、重启服务或更新订阅时重新生成文件;直接编辑临时文件,即使一时生效,也不能说明改动被保存。先确认当前使用的是图形设置还是自定义配置,再从该入口保存,随后重新打开或重新导出确认。

修改前留一份可以原样恢复的副本,并记录客户端选用的内核。同名字段在不同内核、不同配置变体中不一定提供相同选项;借来的片段能被文本编辑器打开,也不代表当前内核接受。严格 JSON 使用双引号,不依赖注释、尾逗号或单引号。先检查语法,再检查字段类型和本地监听,最后验证一次真实请求。这样可以把文件读不进来、服务没有启动和连接行为不符合预期分开处理。

inbounds:监听地址、端口与协议

入站描述的是内核如何接收连接,不是远端服务器在哪里。判断一项入站是否可用,至少要对齐监听地址、端口和入站协议。客户端界面写着“已连接”也不能替应用完成这个对齐:应用可能仍沿用旧的代理端口,或者给 HTTP 代理地址发了 SOCKS 握手。区分这几类情况,首先看操作系统能否建立到端口的连接,再看内核是否读到了符合预期的代理请求。

分别提供 SOCKS 与 HTTP 入口

下面的片段可替换基线的 inbounds 数组。这里给两类代理分别分配端口,便于观察应用实际用了哪一个入口。local-socks 留给明确支持 SOCKS 的应用,local-http 留给支持 HTTP 代理的应用。二者可以共用同一个出站,或者通过入站标签在路由中分开处理。端口数字本身没有协议含义,真正决定握手格式的是 protocol。

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false,
        "userLevel": 0
      }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {
        "userLevel": 0
      }
    }
  ]
}
字段作用核对位置
listen限制监听绑定的本机地址。代理地址的地址部分。
port指定入站端口。应用代理端口与端口占用情况。
protocol决定入口接受哪类代理握手。应用选择的代理类型。
tag为路由规则标记流量来源。规则中的 inboundTag。

回环地址、访问边界与地址族

127.0.0.1 是本机的 IPv4 回环地址。示例没有设置账户,仍把监听限制在本机,避免其他设备直接使用这个入口。不要为了让同一台机器上的浏览器连通,就改成监听所有网卡;那会扩大访问范围,却不能修复代理类型写反的问题。如果应用处在虚拟机或另一个网络命名空间,它看到的回环地址可能属于自己的环境,和宿主机不是同一个位置,不能照抄宿主机的代理地址。

本地应用填写 localhost 时,系统可能先尝试 IPv6 回环地址。示例只绑定 IPv4,某些应用不能回退,表现就是本机也连不上。排查时先明确填写 127.0.0.1,排除名称解析与地址族选择,再决定是否确有必要增加另一种监听。若日志在启动阶段就提示端口被占用,优先查端口属于哪个进程,不要把更换监听地址当成常规处理。一个客户端启动的旧进程,有时仍在为别的应用处理连接。

UDP 能力与域名识别是两件事

SOCKS 入站允许 UDP,并不代表所有 UDP 数据报都会进入内核。应用必须支持 SOCKS 的 UDP 转发方式,出口也得能处理该流量;普通 HTTP 代理不会因此代替系统接管 UDP。做连通性验证时先测 TCP。只有能指出具体是什么应用、什么协议需要 UDP,再在可控环境单独验证。否则即使网页能开,也无法据此判断应用的实时通话、游戏或传统 DNS 请求走了同一条路径。

部分入站支持在建立后续连接前识别流量中的目标信息,这类配置常见于 sniffing。它有时能补上应用没直接提供的域名,但不能把每个数字地址都还原成唯一的网站。是否能读到标识取决于流量本身,识别到的名称是否替换目标又是另一项设置。调试时先用本来就把域名交给代理的应用,确认普通域名规则正确,再决定是否需要依赖识别,不要靠同时打开多个选项来判断哪一个有效。

outbounds:出口协议与默认行为

出站描述内核接到请求后,如何继续处理它。最容易验证的两种出站是 freedom 和 blackhole:前者从运行内核的机器直接连接目的地,后者终止经它处理的流量。出站名叫 direct 或 blocked 并不赋予它任何能力,行为仍由 protocol 决定。先用这两种结果明显不同的出口确认选路,再加入需要远端配合的连接,能把路由错误和节点握手错误分开。

用两个出口建立可观察的对照

{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "AsIs"
      }
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {
        "response": {
          "type": "none"
        }
      }
    }
  ]
}

这段代码可替换基线的 outbounds 数组。由于直连排在第一项,没有命中规则的连接会走直连。拦截出口即使出现在数组里,也不会自动处理任何域名;必须有规则把请求交给它,或者将其设为默认出口。response.type 为 none 表示不构造协议响应。应用可能显示连接关闭、加载失败或重试,而不是出现一张说明拦截原因的网页。看到失败之后仍要核对日志里的出口选择,不能用失败本身证明拦截规则生效。

第一项是默认出口,这也意味着拖动列表顺序可能影响许多没写进规则的服务。测试期间保留明确的默认出口,增加规则时先只针对一个测试目标;如果把拦截改为默认,应另外维护允许的目标,不要以为数组里第二项会在第一项失败时自动接手。备用节点和故障转移需要有明确的选择机制,普通出站数组并不表达重试顺序。

把协议配置与传输配置分开

有远端的出站通常还会出现 settings 和 streamSettings。前者装的是该代理协议定义的参数,后者通常描述连接服务端所用的传输与安全层。服务地址、端口、协议和身份信息必须与服务端对应;传输类型、路径、主机名与安全层要求也必须作为一组核对。仅仅看到协议名称一致,并不能认定配置兼容。同一个域名可以部署不止一项服务,证书使用的名称也不一定等于实际拨号地址。

导入订阅后,优先参照订阅导入教程核对客户端识别出的协议和传输,不要把多个节点里看起来熟悉的字段拼在一起。需要判断当前内核是否支持某个选项时,可参考Xray 与 V2Fly 内核区别。在图形界面更换内核后要重新启动实际连接,并查看启动信息;仅更换下拉列表里的名称,不足以证明进程已经切换。

区分目标地址与服务器地址

应用请求的目标是它要访问的服务;远端出站的服务器地址则是内核先要连接的另一端。二者都可能用域名,但不属于同一次解析。以直连出站为例,AsIs 保持地址形态供拨号阶段处理,不等于要求内置 DNS 为所有目标解析。使用远端出站时,还需要分别确认本机能建立到服务端的连接,以及远端能否访问最终目标。有网站无法加载不能直接推出服务端地址写错,有出站选中记录也不能推出目标已经返回数据。

遇到超时,按“选中了哪个出口、出口连向哪里、连接停在哪个阶段”记录。若基线直连也失败,先查本机网络和目的服务;若仅某个远端出站失败,再看传输和握手。参照v2rayN 节点超时排查顺序时,建议用同一个目标反复测试,不要每次同时换目标、内核和节点,否则无法知道是哪一项造成差异。

routing:匹配顺序与目标信息

路由规则解决的是“这条请求交给哪个已定义出口”,不是给请求修改代理协议。字段规则依次检查,先符合条件的规则取得选择权,后续同类规则不会再补判。精确例外应放在较广范围的规则前面;若把所有请求都能命中的规则放在顶部,再完整的域名列表也形同未写。规划时要明确默认出口,因为未命中并非没有结果,而是回到出站数组的第一项。

写一条能单独验证的规则

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "domain": ["full:example.org"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

把片段并入已定义 direct 和 blocked 的配置,并保留 local-socks 入站。第一条同时要求请求来自该入站,且其目标域名完全等于 example.org;第二条覆盖这个入站的其余流量。如果另有 HTTP 入站,它不会满足这两条的来源条件,将回到默认出口。把两条对调后,SOCKS 入站的请求会全部提前命中第二条所表达的宽条件,精确规则因此得不到执行机会。

同一条规则中,不同条件字段应一起满足;同一字段的多个候选值则提供可选匹配项。例如加上 network 限定为 TCP,表示还必须符合网络类型,而不是“来自这个入口或使用 TCP”。要表达两个场景中的任何一个都可以命中,通常应写成两条规则,分别引用同一出口。不要为了缩短文件把两条独立的规则硬合成一条,否则匹配范围可能从并集变成交集。

按域名匹配,还是按地址匹配

full: 是精确域名匹配,不覆盖子域名。需要同时覆盖根域名及其下级域名时,通常使用 domain:,并测试一个边界相近却不应该命中的名字。裸字符串匹配范围比直觉更宽,不适合表达“只允许某个域”;正则也应在确有必要时使用,避免宽泛表达式把相似名字一并囊括。IP 规则应写数字地址或网段,不能用域名代替。若规则引用域名集或地址集,要确认当前内核能够找到对应资源,并且资源中确实包含所用分类。

routing.domainStrategy 决定路由匹配是否需要把域名补充解析成地址。AsIs 只用当前已有的目标信息,因此一条 IP 规则不会靠它主动解析域名。IPIfNonMatch 可以在原本无法匹配时补查地址;这意味着提前命中的宽域名规则仍可能让地址规则没有机会。IPOnDemand 则可能在检查 IP 条件时就发起解析。不要把这几个策略当作性能预设,先确认设计上究竟需要以域名分类,还是必须用解析后的地址分类。

测试未命中,比测试命中更有价值

调整顺序后,至少复测一个应拦截的主机、一个应直连的无关主机,以及一个与规则名称相近却应排除的子域名。若应用先把域名解析成 IP,再把 IP 交给代理,精确域名规则在没有额外识别信息时本来就匹配不到。也要注意浏览器可能复用旧连接,或者由页面脚本向多个主机发起请求;用单独的一次请求作为测试基准,比看整页加载结果容易解释。

如果出口确实如预期选中却仍然失败,原样保留这条路由,将排查移到出站、DNS 或目标服务。若出口标签拼错,检查出口定义和规则,不要在数组里再建一个只为了迁就拼写的重复出口。对长期维护的配置,顶部留少量精确例外,随后按职责分组,再明确默认路径。每次变动要能说清受影响的目标和不该受影响的目标。

V2Ray DNS 设置:谁解析,在哪里解析

看到域名解析失败时,第一件事是确定发起查询的是谁。浏览器或系统可以在连接代理之前解析,内核可以为路由匹配或者出站拨号调用内置解析器,远端也可能负责最后一次查询。配置里的 dns 对象描述的是内核自己的解析设置,不会自动替换操作系统的 DNS,也不会强制所有应用停用内置的解析功能。只改这里而客户端日志没有相应查询,往往意味着测试请求根本没走到这层。

用固定映射验证内核解析链

下例用于本机验证,不是通用上网配置。准备一个绑定在 127.0.0.1 的本地 HTTP 服务,使用不同于代理入站的端口,例如 8000。以结构总览的完整基线为底稿,把此处的 dns 加到根对象,再替换 outbounds。通过 SOCKS 把 demo.test 原样交给内核,访问 http://demo.test:8000/。服务须接受这个主机名,或至少能在日志中记录收到的请求。此例把保留测试域名指向回环,不需要外部解析服务回答该名称。

{
  "dns": {
    "hosts": {
      "demo.test": "127.0.0.1"
    },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    }
  ]
}

hosts 是内核解析器的静态映射,servers 中的 localhost 表示使用本机系统解析能力处理需要查询的名称,不是要求有一台监听在回环地址的 DNS 服务。这里对直连出站使用 UseIP,目的是让它先取得域名的地址,因此能观察到前面的静态映射。如果测试应用坚持先自行解析,可能直接报告域名不存在;若传给内核的已经是 IP,则即使访问成功,也没有验证这张静态表。

不要把两个同名策略当成一个开关

路由对象里的 domainStrategy 控制匹配阶段怎么补充目标信息;出站设置中的同名字段控制该出站在连接前如何处理目标域名。只改出站策略,不能让此前未命中的路由规则重新求值。反过来,为路由匹配解析到某个 IP,也不能保证后续拨号总会使用刚才的地址,实际还要看出站实现与配置。定位时一次只改一层,再检查出口名与最终目标,避免把两处变化归因给同一个开关。

如果使用特定解析服务器,先确认内核能从当前网络访问它,再考虑分域查询和回退。按域名指定服务器是选择查询去向,不等于指定应用连接的出站;二者可能受不同规则影响。使用域名形式的解析服务器时,也要想清楚服务器自身的域名如何得到首次解析。若这一步依赖同一台尚未连通的服务器,改动可能形成循环,表现为很多域名同时查询超时。

从错误类型判断下一步

域名不存在与请求超时不是同一种错误。前者说明收到了可解释的否定结果,可能是域名写错、查询发给了不认识内部域的解析器,或者本应命中的静态映射没被调用。后者表示等待期间没有得到可用响应,要查解析路径、网络可达性和服务器响应。查询得到地址后连接仍然失败,还应检查返回的是 IPv4 还是 IPv6、网络是否能访问该地址,以及匹配规则是否让请求改走了另一个出口。

测试结果偶尔不一致时,把应用缓存、系统缓存、内核缓存以及已经建立的连接分开考虑。关闭一个页面未必会结束浏览器持有的连接;修改内核配置也未必会清掉应用的域名缓存。最好用新发起的独立请求重测,比较明确记录的目标与结果,不依靠刷新次数判断。与系统代理交织的情况,可参照连接后无法上网排查清单先分离入口问题,再缩小 DNS 的排查范围。

policy:握手、空闲与统计

策略不决定访问哪个域名、选哪个节点,也不等同于系统防火墙。policy.levels 针对内核识别的用户等级提供连接设置;policy.system 则包含系统范围的统计开关。这里的等级不是系统账户权限,也不对应订阅套餐。入站或协议中的用户参数负责选用等级,策略块只规定该等级的行为。检查一个等级为什么没生效,应先确认当前连接使用的入口和协议实际应用了这个等级。

给测试入站配置明确的等待边界

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 300,
        "uplinkOnly": 5,
        "downlinkOnly": 5
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true
    }
  },
  "stats": {}
}

将这两个顶层字段并入配置,并用前文设置了 userLevel: 0 的 SOCKS 入站测试。levels 的键是字符串形式的等级号,时间设置则用数字,单位为秒。这些数值是便于讨论的示例,不是推荐给所有网络的统一参数。实际受哪些设置约束取决于协议的实现,也要分清是在内核处理入口时中断,还是远端服务、应用或网络设备先结束了连接。

字段关注阶段可观察现象
handshake适用协议的初始握手。连接建立后,握手一直没有完成。
connIdle连接一段时间没有数据交换。活跃时正常,长时间静置后断开。
uplinkOnly下行结束后,上行仍可继续的时间。只剩客户端向目标发送数据。
downlinkOnly上行结束后,下行仍可继续的时间。发送结束后仍在等待读取剩余响应。

从连接阶段判断是否需要改时间

握手时间过短可能让慢速连接还没协商完就被结束,但将它调大也不能修复端口写错、目标拒绝连接或协议参数不一致。空闲时间也不是连接总寿命。定期有数据经过的会话,不能用“打开了多少秒”来判断是否达到空闲阈值。若需要验证它,可以先记录最后一笔数据的时间,再观察是否在接近设定间隔时结束,并和应用自身超时、服务端空闲超时对照。

单向剩余时间容易被误当成上传和下载的速度限制。实际上它关注的是另一方向已经结束后,还能保留多长时间来处理这一方向的数据。比如测试程序发完请求后关闭发送方向,服务可能还需要较长时间准备最后一段响应;等待偏短时,最后的内容可能没机会完整返回。但如果测试程序直接关掉整条连接,增加这个时间也不会让应用重新读取数据。最好同一时间只调整一个字段,并用能重现断开的请求复测。

统计开关、读取渠道与使用范围

stats 开启统计组件,policy.system 的两个开关允许为入站累计上行和下行计数。示例没有配置对外的统计读取接口,也不会自动在客户端界面增加图表。图形客户端是否展示这组数据、如何读取和何时清零,要看它的集成方式。用户级统计另有等级设置,也需要协议能识别用户,不能把无认证入站的总流量直接拆成每个本机应用的用量。

排查时先对照相同口径:累计值和速率不同,入站流量和出站流量也未必一一相等。重启进程前后的读数不能当成连续的一段;客户端在切换配置时也可能启用新的进程。只想知道一次测试有没有进入某个入站,优先看该连接的标签与日志。如果仅为此次调试开启详细统计或访问记录,完成后恢复日常设置,不要为了读取计数额外开放网络监听。

配置验证与故障排查

有效的排查不是把所有可疑开关都重置,而是先保留现象,再做范围最小的对照。记录当前内核、启动的配置来源、代理入口和复现目标;有多个客户端或多个进程时,还要确认日志是哪个进程写的。按“配置能读入、端口能连接、请求到达内核、出口按预期选中、目标返回响应”的顺序验证。前一个条件没有成立时,后一个阶段的数据即使看起来异常,也未必对应本次测试。

先查读取错误,再查监听失败

内核读不进文件时,优先查看启动日志的第一条相关错误。有行号时,除了那一行,还要看上一项结尾的逗号与外层括号:解析器通常在遇到第一个无法继续读取的字符时报告,并不保证那个字符就是原始错误所在。能解析为 JSON 只证明语法结构完整,不能证明协议受支持、端口可用或引用标签正确。若切换到某个配置后客户端马上退回断开状态,不必先刷新订阅或测速,应从启动错误开始。

启动成功后也不要只看有没有同名进程。核对进程实际绑定的地址和端口,把它与测试请求填写的值对照。若提示连接被拒绝,先排查没有监听、代理地址写错、地址族不同或进程启停时间不一致;若能连到本地端口但代理握手失败,再核对该端口运行的是 SOCKS 还是 HTTP。一个端口被别的程序占用时,客户端仍可能保留看似正确的界面选项,只有启动日志和实际请求能说明谁在处理连接。

用一条请求复现并缩小范围

如果系统已安装 curl,可在命令行使用下列请求验证完整基线。socks5h 表示把域名交给 SOCKS 代理,--noproxy "" 用来避免环境中的代理例外使测试绕过显式代理。在将 example.org 交给拦截出口的路由例子里,第一条应失败;第二条可作为未命中该域名规则的对照,但仍需要本机网络能访问对应服务。第三条用于 DNS 节的本地映射测试,必须先准备本地服务并加载那一节的配置。三条不要求在同一份配置下都成功。

curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.org/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.com/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 http://demo.test:8000/

若独立请求可用、浏览器不可用,重点查浏览器自己的代理模式、连接复用、解析设置以及系统代理例外;若两者都失败,先在日志里找这次测试的入站标签与出口走向。没看到请求不一定代表它没进入内核,也可能是当前日志级别或客户端展示范围没有记录访问细节。可暂时把基线中的 loglevel 改为 info 并重试,必要时从客户端查看内核访问日志,再恢复平时使用的级别。

让改动能够复测,也能够回退

处理复杂故障时,从只包含一个入口和一个直连出口的副本开始。先证实应用确实通过本地代理访问目标,再加入用于区分结果的路由规则,随后按需要插入解析或连接策略,最后才验证远端出站。每次改完都用同样的协议、端口和目标复测,另留一个应该不受改动影响的请求。若出现新的错误,只撤回刚才那次变更,观察是否恢复;这样得到的是可用的因果线索,而不只是一次碰巧成功的连接。

记录可以简化为入口、目标、出口、阶段和结果五项。向他人描述问题时,保留错误类型、相关标签和必要的字段结构即可,不要直接贴出整份导出文件。订阅地址、账户信息、内部地址和详细访问记录都应移除;配置片段若经过删改,也应说明哪些名称只是测试用。错误发生在远端传输时,按节点超时排查继续;只是第一次设置入口与连接模式时,回到快速上手教程更省时间。