JSON 结构总览
先分清根对象、列表和协议参数
常见的 V2Ray 兼容 JSON 配置以一个对象为根。inbounds 和 outbounds 是数组,因为一份配置可以承载多个入口和出口;routing、dns、policy 与 log 通常是对象,分别描述转发选择、域名解析、连接策略和日志。进入这些对象后仍需逐层看类型。例如 routing.rules 是数组,policy.levels 却是以等级编号为键的对象。缩进只帮人阅读,不会把相邻字段组织成同一层。
看到 settings 要先回看同级的 protocol。这个名字在许多入站和出站里都会出现,但没有一份通用的参数表。SOCKS 入站的认证选项不能挪到 HTTP 入站,出站的目标也不能拿入站监听地址代替。查配置时记下完整路径,例如“第一个入站的监听端口”或“第二条路由规则的目标标签”,比只记一个字段名更容易判断改动发生在哪一层。
可独立启动的本机基线
{
"log": {
"loglevel": "warning"
},
"inbounds": [
{
"tag": "http-local",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
],
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
}
]
}
这是一份完整的单文件基线,可交给支持这组字段的内核装载。入口仅监听本机的 127.0.0.1:10809;有代理设置的应用可显式使用该 HTTP 代理。出站只有一个,未写额外路由时,交给内核的普通请求按默认出口直连。基线不包含远端服务信息,不会替系统设置代理,也不会自动创建虚拟网卡。桌面客户端如果另占用这个端口,应先换一个空闲端口,并同步修改测试应用。
判断基线是否正常,要分两次看。启动后没有配置报错,只能说明内核接受了配置并尝试建立监听;还要发一条目标明确的请求,才能证明应用、入口和出站都参与了连接。先用同一应用直接访问目标,再用显式代理访问同一目标。直连本来就失败时,基线也可能失败,这不能作为入口配置有误的证据。测试时不要顺手更改整机代理,以免其他应用的请求混入结果。
独立文件与章节片段的合并方法
下文标题标为“替换字段”或“加入根对象”的配置窗是局部示例。外层花括号用于说明归属,不代表另开一个文件启动,也不能把第二个根对象粘在文件末尾。已有同名根字段时,用示例替换该字段或按业务需要合并其中的数据。合并路由要重新检查顺序,合并入站要重查端口;不能因为编辑器没有标红,就认为合并结果符合运行时约束。
保持严格 JSON 写法可减少不同导入入口之间的歧义。键和字符串使用半角双引号,数字端口不加引号,对象末项和数组末项不留逗号,也不要把解释写成代码内注释。重复键尤其难看出:有的解析器拒绝,有的会保留后出现的一项,结果看起来像前面的设置没有生效。保存时使用 UTF-8,把运行副本与修改草稿分开。客户端生成的配置则优先通过客户端对应的界面修改,避免下次切换配置时被重新生成。
inbounds 入站
监听地址、端口和协议要同时对应
入站定义内核在哪里接收连接,以及用什么协议读懂应用发来的数据。listen 是绑定在运行设备上的地址,不是远端服务器地址;port 是应用应连接的本地端口,不是对方服务的端口。用回环地址能把本机测试与局域网访问隔开。即使两种地址最后都指向同一台电脑,监听在回环上的入口也不会因此接受发往网卡地址的请求。
应用里的代理类型同样不能省略。选了 HTTP 代理,就需要对接 HTTP 入站;选了 SOCKS 代理,就需要对接 SOCKS 入站。地址和端口都填对但选择了不同协议时,套接字可能成功连接,随后的代理协商却会失败。还要留意应用默认填入的 localhost:如果它先尝试 IPv6 回环地址,而配置只绑定 IPv4,临时把应用地址写成 127.0.0.1 可以排除地址族差异。
把两个入口分开标记
{
"inbounds": [
{
"tag": "socks-local",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": false
}
},
{
"tag": "http-local",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
]
}
双入站例子把两个协议分到不同端口,便于对照。tag 是配置内部的标记,应用填写的仍然是地址与端口。标记应当唯一且稳定;如果要将来自不同应用的请求分开测试,先让它们使用不同入口,再用 routing.rules 中的 inboundTag 区分,避免仅凭应用名称推断路由。配置里没有要求入口名和出口名相同;刻意用不同的命名,可以一眼分辨日志中记录的是连接进入还是离开的位置。
示例给 SOCKS 入口设置了无需认证,并限制为本机监听。这里关闭了 SOCKS 的 UDP 转发,适合先验证普通网页请求等 TCP 流量。测试软件若主要使用 UDP,即使 SOCKS 的 TCP 测试通过,也不能据此推断它可用;需要同时核对应用是否实现相应的代理转发、入口是否允许,以及后续出站是否能承载该流量。不要为了观察到连接就扩大监听范围,本机验证不需要让其他设备访问代理。
从连接失败的阶段判断入口问题
若内核启动时报告绑定失败,先核对监听地址是否属于本机,再检查端口是否已经被旧实例、客户端内置入口或其他程序占用。分配新端口时,不只要改文件;浏览器的手动代理、系统代理记录以及测试命令都可能还指向原端口。配置新旧不一致时,有时并非请求被拒绝,而是测试程序连到了另一套仍在运行的代理,看起来像改动完全无效。
若端口可连接但日志没有预期的入口标签,应优先检查应用是否使用了自己的代理配置,是否设置了目标例外,或本次请求是否重用了此前建立的连接。入口标签出现后,才有必要检查出站和域名匹配。还要区分入站收到的目标是域名还是应用已经解析好的地址:应用提前解析时,域名规则未必有可匹配的信息,问题不一定出在监听协议。先保留输入条件,记录应用实际提交的是哪一种目标,再去改后面的规则。
outbounds 出站
首项是默认出口,标签供路由引用
入站接收请求后,内核还要决定由谁连接目标。outbounds 中每项的 protocol 定义这一项的实际行为;tag 只是路由引用的标识。把标签写成 direct 不会让任意协议变成直连,把标签写成 blocked 也不会自动拦截。对于没有命中路由规则的普通请求,配置数组中的首项承担默认出口。并列写了两项并不意味着并发尝试或失败后自动切换。
以直连为默认出口,适合本页的本机实验,因为不依赖服务端;实际使用时不能照搬为任意场景的默认选择。应先明确不在规则清单内的目标是否可以直连,再决定默认出口。若希望检查分类规则是否完整,可以在独立测试配置里用拒绝出口作默认项,显式放行已知目标。这样做是为了观察未命中情况,不宜直接替换正在服务多个应用的现有配置。
直连和拒绝两种最小行为
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
},
{
"tag": "blocked",
"protocol": "blackhole",
"settings": {
"response": {
"type": "none"
}
}
}
]
}
freedom 直接建立到目标的连接,实际使用的本地网络和解析行为取决于运行环境及出站设置。它不会因为请求曾经过代理入口,就把请求发给某个远端代理服务。blackhole 则不会连接目标。例子将响应类型设为 none,应用侧因此可能看到连接被关闭或通用代理错误,并不会得到一张说明拦截原因的页面。区分主动拒绝与目标故障时,应结合所选出口和目标服务的访问日志,不只看应用弹窗。
这个例子的第二项在尚未加入路由时不会处理普通请求。可以保留数组顺序,添加一条小范围的规则来验证拒绝行为;测试失败后先找该规则是否被前面的规则截住。若重命名出口,要把所有引用原标签的规则一起更新,并核对大小写。一个无法解析的出站标签不是可用的备用路线,即使内核成功加载文件,也不能假定请求一定会回落到首项。
远端连接应逐项对照服务参数
配置远端出站时,先区分代理协议、承载连接的传输方式以及传输安全层。这几项彼此相关,但不能互相代替。同一种代理协议可以由不同传输承载,地址与端口相同也不足以证明双方配置一致。导入分享链接后,优先在客户端查看转换后的协议、传输与安全设置是否与提供方的说明一致。内核家族不同,部分字段和取值可能不兼容,不要从另一份示例抽取几行设置直接拼接。
改动远端配置时,保留已知可用的本地入口,固定测试应用和目标,每次只改一个条件。入口日志出现而远端连接超时,先分别核对远端地址能否解析、端口能否连接,以及失败发生在建连还是握手阶段。同一台机器用本页直连基线能访问测试目标,只能说明本机入口到该目标的直连路径可用,不能证明远端服务参数正确。协议字段的含义可参照代理协议对比,再回到实际配置定位差异。
routing 路由规则
先写专用规则,再写通用规则
routing.rules 按数组顺序检查。对下面这类字段规则,命中靠前的一条后就选用它指定的出口,不再比较后续规则的精细程度。比如先放一条覆盖某网段的直连规则,再写同网段里某台设备的拒绝规则,后一条通常没有机会执行。需要例外时,把更窄的规则放在覆盖范围更广的规则之前;调试时应从列表开头找第一条可能命中的规则,而不是只看最后编辑的那一条。
同一条字段规则若同时填写 inboundTag 与 ip,例子要求入口和目的地址两个条件都成立;单个字段的列表则可列出多个候选值。若目的是“来自指定入口,或者目标属于指定网段”,通常应分别写成两条选同一出口的规则。混淆这两种写法时,常见现象是样例里的一个目标恰好匹配,但换一个应用或地址后就走了默认出口。
用本机请求验证顺序和边界
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["socks-local"],
"ip": ["127.0.0.1/32"],
"outboundTag": "blocked"
},
{
"type": "field",
"ip": ["127.0.0.0/8"],
"outboundTag": "direct"
}
]
}
}
准备一个已可直连的本机 HTTP 测试服务,目标使用 127.0.0.1 和服务自身的端口,不要把目标端口写成代理监听端口。经 SOCKS 入口进入的连接满足第一条规则,走拒绝出口;经 HTTP 入口进入的同一个目标不满足第一条,继续检查并命中第二条。把两条规则顺序互换,再建立新连接,就能看到宽范围的地址规则先于入口特例生效。这里用字面地址,是为了不把域名解析的差异混进路由实验。
正式配置要把三种概念分开:已命中的规则、未命中时的默认出站、以及命中后出站执行失败。没有显式兜底规则时,首个出站依旧有实际作用;加上范围很广的兜底规则后,后续规则可能不再可达。若日志显示走的是预期出口,但连接依旧失败,应排查这个出口本身及目标服务,而不是不停调整路由先后。为现有规则插入例外时,可另外选择一个不应受影响的目标做对照,避免只测试刚新增的情形。
域名规则与地址规则使用不同输入
精确匹配可用 full:example.test;需要覆盖对应域名及其子域名时,可用 domain:example.test。用清楚的前缀比依赖字符串包含关系更容易审查。geosite:cn 这类写法引用域名数据中的分类;内核需要能找到相应资源,而且分类结果以实际加载的数据为准。它不是地理位置检测,也不保证能覆盖某项服务的所有附属域名。域名列表是否命中,应结合实际请求的目标检查。
AsIs 不为路由匹配把域名额外解析成地址;而 IPIfNonMatch 可在首轮未命中时再尝试以解析地址匹配。选择后者前要考虑查询延迟、解析结果与之后连接目标的关系,以及现有兜底规则是否已经在首轮匹配。两种策略都不能把应用主动提交的任意 IP 自动恢复成域名。需要测试某条域名规则时,应先确保应用把目标域名交给入站,再观察是否进入了预期的匹配分支。
dns 域名解析
先确认是谁发出查询
根对象里的 dns 配置属于内核的解析逻辑,不等于操作系统的 DNS 设置,更不会接管应用自行发起的每次查询。应用可以先解析域名再把地址交给代理,也可以把域名保留到代理请求中;有些应用还带有独立的解析选项。判断某个配置项生效之前,先确认本次请求里的目标形态,以及内核的路由或出站有没有调用内置解析器。浏览器显示了一个域名,并不表示同名字符串一定传到了内核。
路由解析与出站解析也要分开。前者用于判断目标是否符合某条地址规则,后者为了最终建立连接。路由查到一个地址,不意味着所有协议、出口和应用一定使用同一个解析结果;不同路径可能各自缓存,也可能因地址族选择不同获得不同答案。排查时不要把“域名能查到”和“当前连接实际使用了这个地址”视作同一件事,必要时同时记录目标和出口的观察结果。
先用静态映射验证内置解析路径
{
"dns": {
"hosts": {
"example.test": "127.0.0.1"
},
"servers": ["localhost"]
},
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {
"domainStrategy": "UseIP"
}
}
]
}
在单入口基线中加入这个 dns 对象,同时替换原有出站。直连出站使用 UseIP,使保留为域名的测试目标可通过内置解析获得地址。hosts 将测试名映射到回环地址,不修改系统的主机名映射。servers 中的 localhost 是使用本机解析能力的写法,不是宣称回环地址上已有一个可查询的服务。测试名使用保留的后缀;应通过代理访问已启动的本机测试服务,而不是把它当成公共网站。
这个示例要放在原始基线上测试,不要盖到上一章仍引用 blocked 的配置上,否则会删除被引用的出口。若应用把测试名跳过代理,或者试图先用自己的解析器查询它,静态映射便不会经过内核。相反,如果改回直连出站默认的域名处理方式,同一名称可能由系统尝试解析。用两份仅出站解析策略不同的配置比较,并在每轮建立新连接,可把内置映射与系统解析的结果区分开。
分组上游、地址族与缓存
需要为不同域名使用不同上游时,可查阅所用内核对 servers 对象项的支持,例如用 address 指定解析端点,用 domains 描述匹配范围。列出专用上游并不必然等于所有其他服务器都不会被用到;需要核对该内核对候选顺序、失败回退和结果过滤的规定。使用基于 HTTPS 的解析端点时,还要检查端点本身如何解析和连接。若端点的域名必须先经它自身查询才能获得,就没有可靠的启动路径。
字面地址能连而域名不能连时,先测实际负责查询的一层,再看结果包含哪种地址族。仅开 IPv4 或仅开 IPv6 的策略都可能让某些目标没有合适的结果,用来缩小排查范围可以,不宜把它作为所有网络问题的通用修复。改设置后还要考虑应用已有的解析缓存、系统缓存和存活连接,各自的更新时机不同。先关闭旧连接并换一个明确的测试目标,确认哪一层仍返回旧地址,再决定是否要清理对应缓存。
policy 连接策略
等级策略控制连接行为,不负责转发选择
policy 描述的是内核如何处理连接期限、缓冲或统计等行为,不负责把域名分给不同出口。policy.levels 用字符串形式的等级编号作为对象键,例如 "0";连接采用哪个等级,取决于相应协议及入口的用户等级设定。配置中定义了某个新等级,也不会自动把请求移到这个等级。查参数前先验证当前协议如何选择等级,默认等级的行为和显式分配的等级应分别测试。
策略很容易被拿来掩盖前面的配置错误。入口端口不能连接、远端传输参数不匹配,或者域名查询走了意外路径时,增加时限并不能修正这些问题,只可能推迟客户端看到错误的时间。建议先用最少的配置确认路径正确,再用具体的应用行为说明调策略的原因。例如在完全没有请求活动时才断开,与一直有数据但传输慢,不能用同一个超时设置解释。
分别理解握手、空闲和单向结束
{
"policy": {
"levels": {
"0": {
"handshake": 8,
"connIdle": 180,
"uplinkOnly": 4,
"downlinkOnly": 12
}
}
}
}
handshake 对适用协议限制初始握手的等待时间,不是所有网络调用的统一连接时限,更不会覆盖远端程序自己的时限。connIdle 则着眼于连接处在空闲状态多久,不能解释成从建连开始累计的最大在线时间。例子的数值只用来区分不同计时对象,不代表任何客户端的默认值。应用自己设定的超时如果更短,先看到的往往是应用主动结束请求。
uplinkOnly 对应只剩上行的阶段,即下行结束后上行还能维持多久;downlinkOnly 是只剩下行的阶段。它们不是上传和下载的速度上限。单向结束后马上截断剩余方向,可能使尚未收完的响应提前终止;留得过久也可能让已失去用途的连接继续占用资源。要测试这组设置,选择能够清楚观察到读写结束行为的应用。普通短请求成功,不足以验证长连接或单向结束的场景。
区分用户等级、系统统计和客户端界面
policy.system 面向内核的系统级策略。部分实现支持在这一层启用入站或出站计数,而用户计数属于相应等级的设置。计数是否产生、是否能被客户端读取,以及是否会展示为界面中的统计数字,是三个不同条件;还需要检查是否启用了相应统计模块及读取能力。只添加策略字段不能保证界面立刻出现数据,也不应为了观察计数而把管理接口开放给其他设备。
调整策略时保留一组对照:固定应用、入口、出口与目标,只替换正在验证的等级参数,并使用重新建立的连接。记录错误是发生在首次发起请求时、空闲恢复时,还是已经收到部分响应之后,再判断与哪个计时器有关。如果只有单个应用异常,而其他应用经同一入口和出站都能工作,还应检查该应用自己的重试和连接池设置。观察到稳定的差异后再保留改动,其余实验参数回到基线,避免下一次变更时因为多个期限同时变化而无法归因。
客户端配置与生效范围
先分清订阅、单条分享记录和内核文件
桌面端首选 v2rayN,Android 可按所需内核选择 v2rayNG 或 v2flyNG;安装入口见安装包页面。客户端管理记录的格式与内核运行时配置并不相同。订阅地址通常用于获取一组连接记录;单条分享记录描述一个连接;完整内核文件则可以同时定义入口、出口、解析和路由。导入某一类资料成功,不意味着可以把另一类资料贴到同一个位置。
已有订阅而只是想新增一个连接时,继续使用客户端的记录管理和更新入口即可。需要修改本页涉及的根对象字段时,先验证客户端是否提供对应设置,或者是否支持导入该格式的自定义配置。不确定入口类型时,先读订阅导入与分享格式说明。客户端保存的内部文件可能包含界面偏好和记录索引,编辑这些文件与修改内核 JSON 不等价;把客户端数据文件直接当作内核文件,常会在启动阶段就失败。
同样的配置字段,不代表接管方式相同
| 平台 | 客户端 | 验证配置时优先检查 |
|---|---|---|
| Windows | v2rayN | 系统代理是否指向当前入口;测试应用是否遵循系统设置。 |
| macOS | v2rayN | 正在使用的网络服务是否启用了相应代理;比较时固定网络服务。 |
| Android | v2rayNG / v2flyNG | 连接授权和应用范围是否包含测试应用;导入格式是否适配内核。 |
| Linux | v2rayN | 桌面代理设置与单个进程的代理配置是否一致;终端工具是否另有环境设置。 |
系统代理通常依赖应用读取并遵循系统设置;保存 JSON 不会自行改变这一行为。桌面端测试一个具体入站时,可先使用应用的手动代理配置,而不是同时打开所有接管方式。若手动指定代理可用、切回系统代理后失败,检查的是应用如何读取系统设置、是否应用了例外项以及客户端写入了哪个端口。这时候把出口换成其他协议,通常只会增加新的不确定因素。
TUN 模式经虚拟网络接口接收流量,受路由范围、应用范围和系统权限等条件约束。它不是把 SOCKS 入口的协议名改成 TUN,也不是绕过所有应用限制的一键替代。Android 的连接范围还要结合系统授权与客户端设置核对;桌面端运行成功的单端口测试文件,不能证明移动端会按同样方式管理设备流量。跨平台移植时,应先复用与协议相关的部分,再单独验证每个平台如何把流量送入内核。
确认实际装载的配置和内核
客户端图形设置常在启动或切换记录时生成运行配置。手动编辑运行目录下的临时文件,可能在下次启动时被正常覆盖。长期改动应落在客户端支持的设置入口,或落在受支持的独立配置文件中。为了验证改动是否进入当前实例,可以改一个无歧义的本机测试端口,重启连接后以应用显式访问新端口,再与旧端口作对照。不要把界面里的“已保存”当成内核已经重读文件的证据。
不同客户端所选的内核可能对同一个扩展字段有不同解释或支持范围。迁移配置时先按根对象和协议查找基础兼容点,再逐项恢复可选功能。若只有加入某一段后才报错,应保留原本能启动的那份,并记录失败段落的完整路径。需要向他人求助时,仅摘录相关结构和报错附近的内容,去掉订阅地址、认证资料和不必要的网络信息;提供重现条件比提供整份运行文件更有用。
配置验证与日志排查
按解析、监听、转发三道关验证
启动就退出,先检视文件是否能被实际运行的内核解析。根据报错位置回看前一行的逗号、引号和括号,再核对字段类型以及这份文件是不是由正确的导入入口加载。语法正确只代表对象能被读出,不代表字段合法。检查时从第一个明确报错开始,解决后再重新启动;一处括号错位可能导致后续多行一起报错,逐条修复派生错误反而会破坏原本正确的内容。
解析通过以后,看日志是否指出地址绑定失败或端口占用,再用固定的目标确认连接是否进入指定入站。下面示例假定本机在 127.0.0.1:8000 已有可访问的 HTTP 测试服务,并使用第一章的基线,不使用带拒绝规则的实验配置。第一条命令绕过代理,第二条明确指定 HTTP 代理并清空本次请求的代理例外。Windows 若命令名与外壳别名重合,可将命令名写成 curl.exe。
curl --noproxy "*" --max-time 5 http://127.0.0.1:8000/
curl --noproxy "" --proxy http://127.0.0.1:10809 --max-time 5 http://127.0.0.1:8000/
两次测试应使用同一个目标和路径,第二次请求的代理端口则要与配置一致。若第一条正常、第二条报告无法连接代理,回查监听;若能连接代理但返回错误,查看是否命中意外的出口或目标是否拒绝连接。两条均成功只证明这一条本机 HTTP 路径正常,不证明其他目标、其他协议或系统接管也正常。随后再逐一加入额外入站、路由或远端出口,哪一步开始出现差异,就从该步的输入和输出查起。
根据日志阶段缩小故障范围
日志应配合一次可重复操作阅读。记下操作时间,关闭无关的测试窗口,发起一条新请求,然后观察同一时段里的入口、目标、出口和失败原因。默认基线使用 warning,成功转发并不一定显示详细记录。若需要更多信息,可临时调高详细程度,并使用客户端提供的访问记录或日志查看入口;不同内核输出的文字可能不同,判断依据是连接发生在什么阶段,不是寻找一条完全相同的模板报错。
如果日志显示选择了正确出口,但远端握手失败,先核对服务端要求的传输和安全参数,同时留意设备时间以及本机可信证书环境。若故障只发生在域名请求,回到解析一章确认谁发起查询;若只在空闲一段时间后才断开,则与连接策略一章的计时场景对照。更多示例见v2rayN 日志与报错定位;客户端选择和连接失败的基本顺序也可查V2Ray 新手常见问题十问。
结束测试时恢复改动并留存可复现记录
验证完成后,先恢复临时设置的系统代理或应用代理,停止不再使用的测试入口,再把日志级别恢复到日常水平。将最终文件与上一份基线并列保存,写下本次变动的字段路径,以及用哪个目标、入口和预期出口验证。下一次连接异常时,先复跑同一用例,再回退有问题的那一项,而不是整份替换。需要补查字段的上下文,可从本页目录回到相应章节;拿不准术语描述的是哪一层时,可参照V2Ray 术语表。