配置文件参考
V2Ray JSON 配置手册
首次安装、导入订阅和验证连接,请先走入门指南的主线。已经能连接,需要查字段含义、判断流量从哪里进或改写规则时,再回到本手册。示例以本机回环入站和普通直连为基准;需要补齐术语时,可对照概念速查。
JSON 结构总览
先沿一条连接读配置
应用向本机监听端口发起请求,入站按自己的协议读出目标地址。路由再根据可用的目标信息、入站标签和其他条件选择出站。出站负责建立实际连接;它可以直接拨号,也可以按节点配置与远端交互。要判断一个字段会影响哪里,先把它归到这条链路上的某一段。改了监听地址不等于改了节点,改了出站地址也不会让原本不使用代理的应用开始进入入站。
顶层是一个对象,而不是把入站、出站和规则并排填进一个列表。inbounds 和 outbounds 是数组,分别容纳多个入口和出口;routing、dns 和 policy 是对象,各自有内部结构。字段名区分大小写,数组顺序也可能决定行为。特别要记住出站数组的首项与规则数组的首条不是一回事:前者承担默认出站,后者只是最早接受匹配判断的候选规则。
建立可运行的直连基线
下面是一个完整的原生配置文件。它在本机回环地址开放 SOCKS 入站,并把进入的流量交给直接出站。它不依赖订阅、远端账号或地理规则库,只用于明确验证「应用能否把请求交给内核」。使用前确认端口未被其他实例占用。若本机本来就无法访问测试目标,直连基线也不会改变这一点,应先选一个在当前网络中已知可达的目标。
{
"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": {} }
]
}
基线刻意没有添加路由,因为这里只有一个出站,未匹配任何规则的请求已经有明确去向。也没有添加内置 DNS 或连接策略,避免把系统解析、内核解析和等待超时混到第一次测试里。启动成功后,应使用明确支持 SOCKS 的应用指向示例地址,而不是仅观察托盘图标或界面状态。打开网页之前还可访问一个已知仅由本机提供、且允许当前用户访问的服务,先确认本地链路。
把示例合并到正确的层级
后文标成顶层片段的代码仍是合法 JSON,但不一定能独立启动。添加新的顶层字段时,把对应键和值并入基线的同一个对象;修改已有字段时,替换对应值或在数组内加入对象。不要把两个带外层大括号的文件直接相接,也不要在同一个对象里重复写两个同名键。不同解析器对重复键的处理可能不同,即使成功读入,也可能只采用后出现的那一段。
| 顶层字段 | 结构 | 修改后的第一项检查 |
|---|---|---|
inbounds | 对象数组 | 应用使用的协议、地址和端口是否完全一致。 |
outbounds | 对象数组 | 默认出站的位置与规则引用的标签是否仍然正确。 |
routing | 对象 | 规则是否按期望顺序判断,目标是否命中第一条预期规则。 |
dns | 对象 | 触发解析的是应用、路由判断还是出站拨号。 |
policy | 对象 | 被测连接实际使用的等级是否对应修改项。 |
建议保存一份基线和一份正在编辑的副本,用同一个请求比较修改前后的结果。标准 JSON 使用双引号,末项不留逗号,布尔值写成小写字面量而不是字符串。格式检查只能回答文件能否解析,不能保证字段在当前内核中受支持,也不能证明引用标签一定存在。格式通过后还要看启动结果,再看单条连接的实际行为;把这三次判断分开,排错时才知道该往哪一层查。
本手册里的最小文件用于单独运行。若客户端正在管理同一个端口,请先停止旧实例或改用一个空闲端口;不要把两个进程间的监听冲突误判为配置语法错误。
inbounds 入站
监听地址与应用协议必须成对检查
每个入站要回答三个问题:接收连接的地址是什么,监听哪个端口,按什么协议阅读数据。listen 是绑定地址,并不是客户端要访问的目的站点;port 是本地入口,不是远端节点端口;protocol 决定应用端需要选择哪种代理类型。把 HTTP 代理请求送给 SOCKS 端口,或者把 SOCKS 请求送给普通 HTTP 服务,都可能出现「端口能连,实际请求失败」的结果。
本机应用使用时,先从 127.0.0.1 开始。它把监听限制在本机,但本机上的其他进程仍可能访问该入口。不要把无认证的示例改成全接口监听来解决连接失败。若应用和内核明确使用 IPv4 回环,就始终填写同一个地址,避免应用把 localhost 优先解析到 IPv6 回环,而内核只在 IPv4 上监听。容器或虚拟机里的回环也属于各自的网络环境,不能代替宿主机地址。
用两个独立入站区分 SOCKS 与 HTTP
下面的顶层片段可以替换基线文件原有的 inbounds。它把 SOCKS 与 HTTP 代理放在不同端口,并为每个入口分配独立标签。浏览器支持哪一种、终端工具应该用哪个参数,要看工具的代理设置。HTTP 入站能接收支持 HTTP 代理的应用发出的请求,包括通过 CONNECT 转发的请求;它不是用来接收任意浏览器页面请求的站点服务。
{
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
},
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
]
}
标签只在配置内部标识入口。应用填写的是类型、地址和端口,不会把标签发给内核。路由可通过 inboundTag 读取这个标识,因此应用 A 固定使用 SOCKS、应用 B 固定使用 HTTP 时,可以用不同入站区分路径。如果两个应用都使用同一入口,标签就不能区分它们。更改标签时还要搜索所有引用;只改了入站对象本身,旧规则就可能永远不再命中。
UDP 与目标识别不是同一个开关
示例关闭 SOCKS 的 UDP 支持,因为基线只验证普通网页类连接。如果要排查支持 SOCKS UDP 的应用,需要同时确认应用确实发起 UDP 转发、对应 SOCKS 入站允许 UDP,以及后续出站支持传递这类流量。仅打开入站开关不能补齐剩余两段。反过来,如果测试的是明确走 TCP 的请求,修改 UDP 开关没有诊断价值。先确认连接类型,再决定是否需要增加一组测试。
应用可能把域名直接交给 SOCKS,也可能先在本机解析,再只把 IP 交给内核。后一种情况下,单靠域名路由条件可能无法看到原来输入的域名。某些入站可以通过 sniffing 从支持的上层流量中识别目标信息,但结果取决于协议、可见数据和当前内核实现,不能替代清楚的应用代理设置。排查时先关闭额外识别逻辑,比较域名交给代理和 IP 交给代理的两次结果,再决定是否需要它。
本地监听失败时,先区分地址不可绑定与端口已占用。前者优先检查本机是否能使用填写的地址,后者先确认占用进程是谁,再选择停止旧实例或调整端口。改端口后必须同步浏览器、终端和系统代理等所有指向这个入口的设置,否则新实例虽然正常,应用还在访问旧端口。可按本地端口冲突排查定位,不要仅凭看到一个监听进程就结束它。
outbounds 出站
首项是默认出站,标签是引用名
出站定义内核拿到目标后如何处理连接。freedom 用于直接访问目标,blackhole 用于丢弃送到该出站的流量。两者都不需要远端账号,适合作为规则调试的对照。标签可以按用途命名,但叫 direct 的出站不会因命名自动获得直连能力,实际行为由 protocol 等字段决定。规则写的是标签,不是协议名称,更不是订阅中显示的节点备注。
没有匹配规则时,连接默认交给出站数组的第一项。于是「新增一个对象」和「把对象插到首位」是不同操作。若首项原来是直连,后来把丢弃出站移到首位,没有被任何规则处理的普通请求也会被丢弃。反过来,原本预期使用远端节点的流量在规则漏配时,若首项是直连,就会回到直连。决定默认行为后再排列出站,不要让顺序只取决于界面中哪个节点先显示。
{
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} },
{ "tag": "blocked", "protocol": "blackhole", "settings": {} }
]
}
用上面的片段替换基线文件中的 outbounds 后,尚未添加规则时不会有请求主动进入 blocked。这个片段和下一章的路由片段配套使用。给备用出站起不同的标签,保留首项不动,可以在规则中缩小试验范围,避免影响所有普通请求。要恢复基线,应先确认规则不再引用将要删除的标签,再移除备用对象。
分别核对协议、传输与安全设置
使用远端节点时,出站里的协议、节点地址与端口、认证参数、底层传输方式及安全设置要对应服务端。协议字段解释如何组织会话;settings 放该协议所需的目标和认证信息;常见的 streamSettings 描述与远端建立链路时使用的传输及安全参数。代理请求最终要打开的网站,与出站连接的远端节点地址是两个不同目标,两者也可能分别触发域名解析。
排错时,不必立刻重写全部配置。先比对当前节点的主机名和端口,再比对传输类型及其关联参数,最后查看安全协商是否与服务端一致。若 TCP 已经接通,但协商阶段失败,仅更改本地监听端口通常没有帮助。不要通过关闭安全校验来掩盖主机名、证书或时间错误;应保留当前安全约束,检查配置是否与节点提供方给出的连接参数相符。
客户端列表里的订阅地址、显示名称和原生出站也不是同一类对象。订阅负责提供节点条目;客户端按所选节点与内核生成运行所需的出站。把订阅地址填进远端节点地址字段不会得到同样结果,把界面备注复制到规则的 outboundTag 也未必有效。要核对生成结果,应查看当前实例实际加载的配置,而不是早先导出的示例。订阅中不同节点的条件可参考节点选择说明。
用对照请求缩小故障范围
选同一个测试目标,分别通过正常的直接出站和需要验证的远端出站发起新请求。若直连正常而远端失败,说明本次测试的应用代理、监听和直接路径可用,下一步再核对远端参数与握手阶段。若两个出口都失败,就先回到共同的入口、目标可达性与解析过程。切换后要重新建立连接;浏览器保留的旧会话可能继续复用已有通道,让一次成功或失败看起来像是新配置的结果。
routing 路由规则
首条命中生效,未命中回到默认出站
routing.rules 从前向后判断,一条规则命中后,后面的规则不会为同一个请求重新选择出口。在一个字段规则中同时写入域名和入站条件,表示这些条件同时成立才命中;在同一域名条件数组中列出多个可选值,一般是其中一个匹配即可。要表达「来自某入口的指定域名」可写在一条中,要表达「任一入口条件或某个独立目标条件」则通常应拆成两条规则。
把范围窄的例外放在范围宽的规则前。例如,先判断「来自本地 SOCKS 且目标是某个完整域名」,再判断「所有来自本地 SOCKS 的请求」。如果先写后一条,前者就没有机会命中。规则没有匹配到任何条目时,不会自动按照列表最后一条的出口处理,而是按出站的首项处理。因此既要读规则列表,也要同时确认出站排序,尤其是从客户端生成配置里提取一小段规则时。
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["full:example.com"],
"outboundTag": "blocked"
},
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
}
把该片段并入基线,并使用上一章包含 blocked 的出站数组,可以用两个域名对照检查。经由 SOCKS 并把域名交给代理时,精确名称 example.com 会命中第一条,其他域名会继续判断第二条。来自本地 HTTP 入站的请求不满足这两条的入口条件,会使用默认出站。应用若把目标预先解析为地址,第一条便可能不成立;这时优先确认目标表示方式,而不是怀疑规则顺序。
域名匹配与地址匹配分别验证
full: 表示完整域名匹配;需要匹配某个域及其子域时,使用 domain: 形式。没有前缀的普通字符串按子串匹配,写得过短容易把不相关的名称也纳入。同样的规则目标可以用域名或 IP 来描述,但它们面对的是不同形式的输入。面对共用地址的站点,IP 规则通常无法区分不同域名;面对应用已经解析好的地址,域名规则也不能自动恢复原始名称。
domainStrategy 控制的是路由在什么情况下利用解析结果判断 IP 规则,并不等于让出站使用相同方式拨号。AsIs 不为路由匹配主动把域名变成 IP;IPIfNonMatch 在按原信息未命中时尝试解析域名后再匹配;IPOnDemand 则可在判断遇到需要 IP 的规则时解析域名。若前面已经有宽泛规则命中,后面的规则便不会参与判断,增加 DNS 服务器也不能改变这一点。
给新增规则安排正例和反例
新增规则时,保留一个应命中的请求,一个名称相近但不应命中的请求,再保留一个完全无关的目标。分别记录入口标签、交给内核的目标形式以及实际出口。使用 geoip: 或 geosite: 前还要确认内核能读取配套数据,而且类别确实存在;规则文本写得正确,并不表示本机已经安装对应数据。需要快速确认匹配顺序时,优先使用不依赖数据文件的精确域名或明确地址范围。
最后区分「流量有没有进入内核」和「进去之后如何分流」。系统代理是部分应用把请求交给本机入口的一种方式;路由规则只对已经进入内核的请求生效。调整分流不会自动捕获未使用代理的终端连接,也不能代替系统代理开关。需要对比界面上全局与分流选项时,可以先读系统代理与路由模式说明,再回来核对实际生成的规则。
DNS 设置
先查是谁发起解析
顶层 dns 配置内核的解析能力,不等于替换系统的所有 DNS 查询。应用可以在连接前使用系统解析器,也可能使用应用自己配置的解析服务;当它只把一个 IP 交给 SOCKS 入站时,内核不需要再为这个目标解析域名。相反,应用把域名原样交给入站后,路由可能为判断地址规则使用内置 DNS,出站也可能为建立连接解析名称。先查解析发生在哪一步,再决定改哪一层。
下面的片段将本机系统解析器列为内核 DNS 的服务器选项,并通过 hosts 为两个保留的测试名称配置固定映射。把它并入基线,只是定义了内核在相关解析场景中如何查询,不会让它默认监听本机 DNS 端口。测试地址来自文档保留网段,目标是验证匹配过程而不是真正提供网页服务;访问失败本身不是判断映射是否生效的依据。
{
"dns": {
"hosts": {
"test.example": "192.0.2.10",
"control.example": "198.51.100.10"
},
"servers": ["localhost"]
}
}
用地址路由验证内核解析
若要实际区分上面的两条映射,可保留直连与丢弃两个出站,将路由替换为下面的片段。用能够把域名交给代理的 SOCKS 应用发起请求。路由遇到 IP 条件时会尝试解析目标,因此 test.example 对应地址会进入丢弃出站;control.example 对应地址不在该规则范围内,将回到默认出站。应以当前实例可用的路由或访问日志确认路径,不能以两个保留地址都无法提供页面来推断结果相同。
{
"routing": {
"domainStrategy": "IPOnDemand",
"rules": [
{
"type": "field",
"ip": ["192.0.2.0/24"],
"outboundTag": "blocked"
}
]
}
}
用来判断路由的解析结果与实际拨号时采用的目标不是一回事。对直接出站,若需要显式采用内置 DNS 提供的地址,还要检查该出站的域名策略;对远端代理出站,则要区分在本机解析的远端节点主机名和交给远端处理的网站名称。两类域名可能恰好都出现在同一串日志里。修改 routing.domainStrategy 不保证改变远端看到的目标形式,也不保证浏览器改用内核做名称查询。
拆开服务器选取、地址族与缓存问题
dns.servers 可以包含简单服务器项,也可使用带域名匹配条件的服务器对象。按域名为某个解析服务安排优先查询范围,不等于强制整个系统走这台服务器;回退规则以及可用字段还需查运行中的内核说明。实际部署时从一项可达的服务器开始,记录一个应命中专用解析器和一个应走普通解析的域名。存在分域需求时再扩展列表,避免同时调整地址、域名匹配和回退行为。
如果部分名称能解析但连接迟迟未建立,分别识别返回记录的地址族和本机到该地址的可达性。拿到 IPv6 记录并不说明所在网络具有可用的 IPv6 路径,反之也不应只因一条 IPv6 连接失败就永久关闭该地址族。先做一组受控对照,确认是哪类地址与失败伴随出现,再调整查询策略或网络环境。DNS 查询失败与解析成功后连接超时是两种不同故障,日志中的时间点可以帮助区分。
更改映射或解析器后,旧结果可能仍在浏览器、系统或内核缓存中。重启其中一层不会当然清除其他层的记录,已有连接也不必重新解析。测试时用新的连接,必要时换成从未查询过、由自己控制的测试名称。若普通程序与 SOCKS 程序给出不同结果,保留这组差异作为证据,而不是立即把两个程序都改到同一套解析设置。
policy 连接策略
先确定连接属于哪个等级
policy 用于配置内核连接策略,例如握手等待、空闲时间和部分统计开关。它不选择出口,也不替代路由规则。policy.levels 是一个对象,键是用户等级对应的字符串,如 "0";配置里让协议关联某个等级时,字段值通常是数字。自定义的等级不会因名字出现在 levels 中就应用到所有连接,必须看所用协议如何为连接指定等级。
基线入站未显式提高用户等级,这里以零级作为对照。下面给出以秒为单位的示例值,用于观察改变等待窗口会有什么影响,并不是建议所有网络照抄。把片段并入基线后,先确认当前连接仍走该入站,再验证策略。若客户端生成了另一套入站,或者另一个协议为用户指定了不同等级,修改零级并不能解释那个连接的行为。
{
"policy": {
"levels": {
"0": {
"handshake": 8,
"connIdle": 180,
"uplinkOnly": 10,
"downlinkOnly": 10
}
}
}
}
握手、空闲和单向收尾分开理解
handshake 是代理协议在相应握手阶段的等待限制,不是整个网页访问的总用时,也不是所有底层连接超时的统一开关。connIdle 针对一段时间没有传输数据的已建立连接。若连接每次都在建立后、空闲相近时长时断开,它才值得优先检查;如果从未成功建立连接,则应先查看监听、远端地址、节点协商或网络错误。
uplinkOnly 与 downlinkOnly 管理连接进入单向收尾时剩余方向的等待窗口,而不是上传限速和下载限速。例如应用已经结束发送,但仍需等待服务返回尾部数据时,会遇到仅剩下行的阶段。把该阶段的窗口压得太短,可能让迟到的响应来不及返回。排查文件上传完成后迟迟未返回结果的情形时,应区分处理端真的慢、连接在中间设备被关闭,以及内核在收尾阶段先结束。
| 字段 | 关注阶段 | 不适合解释的现象 |
|---|---|---|
handshake | 相关协议建立会话 | 握手成功后长时间传输缓慢。 |
connIdle | 连接建立后的无数据时段 | 应用从来没有连接到本地端口。 |
uplinkOnly、downlinkOnly | 剩余单向传输阶段 | 域名被一条更早的路由规则匹配。 |
超时和统计都需要核对作用范围
测试超时时,选一条已知能稳定建立的连接,记录开始时间、最后一次有效传输和关闭时间。每轮只改一个字段,并重新建立连接。应用的请求上限、系统与中间设备的空闲限制,以及服务端自身的等待策略都可能比内核更早到期。若内核数值调整后,断开时间仍固定在应用的等待截止点,就应检查应用或远端,不要继续延长一组彼此无关的策略字段。
统计项也有分层。等级下的用户上传与下载统计和系统层按入站或出站汇总的统计不是同一口径;只有对应功能已启用、当前协议和连接提供了所需的统计维度,才有相应数据可供读取。开启策略开关不表示客户端界面会立刻显示数字,也不等于定义了流量配额。调试进程首次启动时,不需要先接入统计接口才能判断规则是否命中;一个入口和一个目标的访问结果更直接。
不要把超时一律调到很大来消除报错。较长的等待可能延后失败提示,并让已无法完成的连接占用资源。先确认限制发生在哪一层,再只改负责该阶段的配置。
如果为了诊断临时放宽了等待值,应在验证完原因后恢复原配置,或者只保留有证据支持的一项调整。记录目标、内核、入口标签、连接等级和时间点,下一次出现相同错误时才有可比的条件。没有这些上下文,一张显示「超时」的截图通常无法判断究竟是代理握手没结束,还是一个已经建立的连接在等待数据。
客户端配置与原生 JSON
区分界面输入、生成产物与实际运行文件
日常使用优先从客户端界面设置代理;桌面端首推 v2rayN,Android 可按内核需求选择 v2rayNG 或 v2flyNG。客户端下载页按系统和架构给出入口,本手册只解释内核读取的配置。客户端可以保存节点、订阅、分流方案与程序状态,但这些数据未必以原生内核配置形式存放。看到一个后缀为 JSON 的文件,不代表它应当直接交给内核运行。
订阅更新影响节点条目,图形设置会影响下一次生成的运行配置,而内核真正生效的是当前实例加载的文件。直接修改客户端临时生成的文件,可能在切换节点、重启内核或重新应用设置后被覆盖。要长期维护一项修改,优先使用客户端提供的对应设置;确实需要原生文件时,在支持自定义配置的模式下保存独立副本,并明确哪些变更由客户端管理,哪些变更由维护者自行跟踪。
| 平台 | 客户端 | 先核对的运行条件 |
|---|---|---|
| Windows | v2rayN | 分开核对应用采用的系统代理与内核监听端点。 |
| macOS | v2rayN | 区分系统代理设置、应用自己的网络选项和启动的实际内核。 |
| Android | v2rayNG、v2flyNG | 区分系统 VPN 接管状态、纳入的应用和内核路由结果。 |
| Linux | v2rayN | 区分桌面网络设置与终端进程继承的代理参数。 |
内核切换应比较有效字段,而不是整份复制
Xray 与 V2Fly 有共同的配置概念,但特定协议、传输、安全选项以及专有字段不一定通用。移植时可先保留独立的本地入站和直接出站,确认最小文件可以启动,再逐段引入原文件中的规则、解析配置和远端出站。留意错误指出的是未知字段、无效字段值还是资源文件缺失。若一份配置在某个客户端里工作,不表示换一个客户端或换一个内核后就能原样运行。
下面的顶层片段仅保留一个本地回环的 HTTP 入口和一个直接出站,可用于跨内核排查这两个基本对象。它与第一章的 SOCKS 基线是两套独立入口约定:应用必须显式使用 HTTP 代理和本例端口。如果目的是比较两个内核,就让两边依次运行同一份文件,并确保旧的进程退出。不要同时启动两个配置去争用同一个端口,否则得到的是监听冲突而不是兼容性结果。
{
"inbounds": [
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
],
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
}
如果原生文件能启动且显式代理测试有效,但客户端启动的实例表现不同,接下来比较运行文件的出站顺序、入口端口、路由标签和 DNS 策略,而不是只核对节点名称。若只有开启系统代理或虚拟网卡模式后才产生差异,则要进一步检查流量接管方式。入口接管是客户端与系统之间的问题,原生 JSON 中写好出站并不能替应用开启它原本未使用的代理通道。
分享片段时只保留复现所需的数据
需要请别人协助定位时,先复制一份临时配置,删除订阅地址、远端凭据、真实节点地址、个人目录和可识别的访问记录。保留必要的键、值类型、数组顺序及标签之间的引用关系;只替换一端标签会让新片段产生本不存在的错误。对必须依赖远端的症状,说明失败阶段和对应报错,不要上传完整运行文件。首次启动与节点导入的界面操作可回看v2rayN 初始设置。
每次持久化修改前,先写明是为了改变哪个请求的行为,以及撤销动作是什么。比如分流应通过恢复原规则顺序撤销,系统代理则应在应用或系统设置中恢复。两者最好都有各自记录;关闭客户端后仍保留指向本地旧端口的代理设置,会造成与内核配置无关的访问失败。遇到这种情况,应先恢复原来的接管方式,再比较文件差异。
分层验证与回退
先确认读取成功,再确认请求进入内核
开始排错前,记下当前客户端、实际内核、监听地址、端口、默认出口和测试目标。保存能工作的配置副本,再编辑候选文件。若内核拒绝启动,先看最早出现且明确指向字段的错误:格式不合法、类型不对、协议不支持、规则数据缺失和端口占用是不同问题。后续错误可能只是第一个故障的结果,先修复最前面的原因,再重新读启动日志,不要一次改动多个模块。
启动以后,先用显式传入代理设置的程序做一次短请求。下面命令适用于使用基线文件、已安装 curl 且能直接访问示例站点的环境;把执行结果与同环境下的「不经这个代理」请求作比较。两个 SOCKS 参数的主要区别是由哪一侧处理目标域名,在对照路由和 DNS 时尤其有用。若使用其他监听端口,应有意识地保持两条命令一致,而不是改变目标的同时也顺手改变代理地址。
curl --socks5 127.0.0.1:10808 --max-time 12 https://example.org/
curl --socks5-hostname 127.0.0.1:10808 --max-time 12 https://example.org/
如果命令报告不能连接本地端口,优先检查内核是否在运行、是否绑定到了同一地址;如果已经连接本地端口但代理协议交互失败,再复核应用使用的代理类型。如果显式代理有效而浏览器或终端平时的操作无效,回到应用的接管设置:浏览器扩展、系统代理和终端环境变量可能各有作用范围。可按系统代理排查将浏览器和终端分成两条验证线。
用短时日志关联一条具体请求
连接到达内核仍无法判断去向时,可临时提高日志详细度。下面片段替换整个顶层 log 对象,适合在基线副本中短时观察,不指定持久化日志路径。客户端如何接收和显示内核输出取决于运行方式;提高日志等级也不保证界面会列出每条规则的完整判断过程。可从请求时间、目标、入站到出口的记录以及对应的错误阶段拼出一次完整路径。
{
"log": {
"loglevel": "info"
}
}
只复现一次并记录清楚目标。若目标以 IP 出现,就不要先修改域名匹配表达式;若日志显示进入默认出站,就对照是否有规则命中、标签是否存在,以及首项是不是预期出口。若出口已经正确但连接失败,则开始核对 DNS 或拨号。域名解析错误、连接被拒绝和连接超时不能互相替代:它们分别指向地址获取、目标监听状态或等待阶段,下一步查看的模块也不同。
测试新旧配置时应保持目标、应用、入口协议、网络和所选节点不变,只替换待测试的文件。每轮重建连接,避免把浏览器连接池和客户端内旧会话带进结果。若故障只在长连接空闲后出现,应让对照测试等待相同时间;若只在某一类名称出现,应保留一个已知有效的名称作为对照。无法稳定复现时,先记录发生条件,比无目标地重装客户端更能保留排查线索。
回退配置和回退接管分别完成
如果候选文件不能通过启动或基本连接测试,停止候选实例,恢复之前的配置副本和应用指向的本地端口,再验证一个已知可用的目标。若验证过程中临时开启了系统代理或虚拟网卡模式,也应恢复到原先状态;这一步与替换 JSON 是两项不同操作。确认应用回到原路径后,恢复常用日志等级,并移除测试时加入的额外监听、固定主机映射和专用规则。
最后保留三类结果:应用是否进入指定入站,路由是否选中预期出站,出站是否成功访问目标。每类只记可观察的事实。共享记录前,删去目标明细中不需要公开的内容。
若回退后仍失败,不要继续在候选文件上叠加修改。重做基线测试,确认本地端口、接管状态和网络环境是否真的回到原点,再检查是否有新进程占用端口或使用旧文件。此时如果只想恢复日常使用,可返回入门指南按导入、选择模式和连接验证走完一轮;等基本路径恢复,再从本手册相应章节查单一字段。