配置参考 · 内核与客户端
V2Ray 配置文件参考
从本地入站到出站选择,按连接经过的环节查阅参数和排错线索。
第一次安装、导入订阅或验证连接,先看v2rayN 快速上手。这份手册适合在遇到具体字段时回来查阅:前六章讲内核读取的 JSON,最后两章讲图形客户端怎样选择内核、维护订阅和接管流量。示例以 V2Fly 与 Xray 常见的共有字段为主,实际能否使用某项能力,以当前运行的内核为准。
JSON 结构与连接处理顺序
先确认内核读到的是哪份文件
在 v2rayN 里,服务器条目、订阅资料和界面偏好是客户端管理的数据;内核真正读取的则是启动时交给它的配置。某个条目能够在界面里保存,只说明客户端接受了输入,不等于内核已经接受生成结果。排查时先确认当前选中的条目、正在运行的内核和日志对应的启动时间。如果修改的是临时生成文件,重新选择条目或重启后它可能被重新生成。希望长期保留的修改,应写在客户端支持的设置位置,或者保存在自行维护的配置副本里。
最小配置:本地接入、直接出站
{
"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": {} }
]
}
这是一份用于建立对照的独立示例。应用通过本地 SOCKS 监听提交连接,内核用 freedom 出站直接连接目的地,不经过远程服务器。测试它时先确认示例端口空闲;如果正在运行的 v2rayN 已经占用该端口,另起进程会发生冲突。也要确认测试应用确实使用了这个 SOCKS 入口。网页能打开并不能单独证明配置有效,因为应用可能根本没有使用代理。反过来,已有程序占着监听端口时,连得上也不代表连到了刚启动的进程。
区分字段所在层级与取值类型
顶层是一个对象,inbounds 和 outbounds 是数组,每项分别描述一个入口或出口。routing、dns 和 policy 是对象,内部可以再包含数组或按名称组织的子对象。settings 则跟随所在条目的 protocol 解释:同样叫 settings,SOCKS 入站里的认证结构不能原样搬到其他协议中。端口写成数字,开关写成不带引号的布尔值,标签写成字符串。手工合并时要向已有数组添加条目,而不是在顶层再写一个同名数组;重复键可能被后面的值覆盖,使前半份配置看起来存在却没有生效。
保存配置时优先采用标准 JSON:双引号包围键名和字符串,数组与对象的末项后不加逗号,不插入注释。启用严格校验的编辑器能提前捕捉这些问题,但语法通过只说明文本可解析。协议是否受支持、标签能否解析、端口能否绑定,都得看内核加载与实际连接结果。遇到一串报错时,应从第一次启动失败时的首个错误查起;后续的连接失败、重试和退出信息往往只是连锁反应。
建议把一次修改记成可以复查的实验:写下入口端口、测试应用、目标域名、预期出口和观察到的结果。若改动后失败,先恢复单项改动并用同一个目标重试,避免把目标服务偶发异常误认为配置回归。不要把“运行中”图标当作全链路通过的证据:它通常不能回答某条请求是否已进入内核,也不能证明请求采用了预期路由。
inbounds 入站:监听与应用接入
监听地址决定谁能连进来
listen 决定内核在哪个本地地址上接收连接。只有本机应用需要接入时,可显式绑定 127.0.0.1。这与绑定所有 IPv4 接口不是一回事,也不等同于绑定 IPv6 回环地址。若应用把 localhost 解析成 IPv6 而内核仅监听 IPv4,应用可能报连接被拒绝;先把应用地址改成与监听一致的回环地址来做对照。不要为了让本机测试通过就扩大监听范围。若确有受控局域网接入需求,应单独考虑接口范围、访问限制与身份验证,不能直接照搬下面的本机示例。
"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": {}
}
]
这段用于替换总览示例的 inbounds 字段。两个数字是便于对照的示例,不代表当前客户端一定使用这组端口。实际端口应以设置和启动日志为准。同一地址上需要同时提供两种监听时,分别分配端口并给它们不同的 tag。应用不能仅凭端口号判断服务协议:将 HTTP 代理指向 SOCKS 端口,即便底层连接能够建立,后续握手也会失败。
| 字段 | 示例 | 核对重点 |
|---|---|---|
| listen | 127.0.0.1 | 地址与测试应用的代理目标一致。 |
| port | 10808 | 端口未被其他实例占用。 |
| protocol | socks | 与应用选择的代理类型一致。 |
| tag | local-socks | 供日志识别和路由规则引用。 |
系统代理与 UDP 为什么要分别验证
系统代理是操作系统提供给应用读取的设置,并不等于操作系统强制转发所有流量。启用自动配置后,仍应确认目标应用遵循系统代理,以及应用是否被系统例外列表排除。某些工具优先采用自己的代理配置或环境变量,浏览器也可能由扩展或管理策略覆盖。出现“一个应用正常,另一个不通”时,先用能手工指定代理类型和端口的应用验证监听,再回到故障应用核对它实际取得的设置,而不是先修改服务端。
上面的 SOCKS 示例显式关闭了 UDP。即使在适用的场景下开启 SOCKS 的 UDP 能力,也还需要应用使用相应的 SOCKS 关联方式,并且后面的出口和链路支持该流量。普通的 HTTP 代理测试只能说明被测的 HTTP 请求或 TCP 隧道工作,不能据此推断实时通话或其他无连接流量已经正常。将测试按应用、协议与入口分别记录,能避免用一项成功结果解释所有症状。
退出前如果曾手工配置系统代理,应核对设置是否已按预期恢复。残留的回环地址看起来仍像一个有效代理,实际却没有进程接收连接。遇到退出客户端后浏览器无法联网的情况,可先检查故障排查问答中的系统代理与本地监听线索,区分应用没有连接到入口,还是入口之后的链路出了问题。
outbounds 出站:协议、标签与传输
用可验证的出口建立基线
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} },
{ "tag": "block", "protocol": "blackhole", "settings": {} }
]
freedom 用于直接建立外部连接,blackhole 可用于终止命中指定规则的请求。两个名字是协议值,而 direct 与 block 是供规则引用的自定义标签,不是客户端内置的语义开关。仅把 block 写进出站数组不会拦住所有请求;要让特定流量使用它,还需要对应的路由规则。没有可用的规则匹配时,常规配置会使用第一个出站。调整列表顺序可能改变默认行为,因此应把默认出口放在容易一眼确认的位置。
远程出站分开核对三层参数
导入经过授权使用的连接参数后,可把生成结果拆成三层阅读。第一层是应用协议,包括远程地址、端口与协议要求的身份材料;第二层是承载协议数据的传输方式;第三层是所选传输适用的安全设置。远程地址回答的是连接实际发往哪里,安全握手中使用的服务名则用于满足对端的名称要求,两者有可能相同,也可能不同。订阅中的名称有时只是便于识别的备注,不应照抄为服务器地址或握手名称。
protocol 与 settings 描述出站协议本身;适用的传输和安全参数通常放在 streamSettings。例如,接口中显示某条连接使用某种承载方式,并不意味着可以把另一条连接的路径直接复制过来。连接前端对路径、名称或握手方式的要求由实际服务决定。不要为了绕过证书错误而把验证关掉:先检查系统时间、对端名称和证书链,再确认客户端选用的传输是否正确。协议字段或传输类型在两个内核之间相似,也不代表所有组合都能互换。
按失败阶段阅读日志与测试结果
如果本地入站已经接到请求,但日志显示找不到出站,应先检查路由中写的标签,尤其是大小写、前后空格、重名和更新后的旧引用。若日志显示已尝试连接远程地址,则继续区分域名解析失败、连接超时与握手失败。解析失败发生在得到可连接的地址之前;连接超时可能涉及路径、网络状态或对端监听;握手失败则更值得检查协议参数是否与服务相符。仅靠通用的“连接失败”提示,无法判定是哪一阶段出了问题。
测试远程出口时,用同一条请求先复核入口,再对照完整连接测试。端口可连只表明探测时建立了相应的连接,不保证后续协议握手成功,也不代表下载速率。Tcping、真连接延迟与测速结果的区别解释了不同测试覆盖的范围。若测试目标本身不稳定,可以增加一个性质相近的对照目标,但不要在更换目标的同时修改出站参数,否则结果很难归因。
多个出站并存时,给每个出口分配稳定、互不重复的标签,并让标签说明用途,而非记录某次测速结果。更新出站详情后复查所有引用,尤其是手工编写的路由。需要把日志交给同事排查时,先删去远程身份材料、订阅地址及请求明细;保留错误类别、入口标签与出口标签,通常已经足以指出下一步该查哪一层。
routing 路由:匹配顺序与目标类型
从上往下读,在第一条命中处停止
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-http"],
"domain": ["full:example.org"],
"outboundTag": "block"
},
{
"type": "field",
"domain": ["domain:example.org"],
"outboundTag": "direct"
}
]
}
这段与前两章的入站、出站示例搭配使用,用示例域名说明顺序。第一条要求请求来自 local-http,且供路由使用的目标名称恰好是 example.org;两个条件都成立才走 block。如果相同域名来自 local-socks,第一条不会命中,第二条则可匹配。若请求是子域名,第二条同样适用。交换两条规则的顺序,较宽的域名规则会先覆盖精确规则的匹配范围,结果也就不同。
区分完整域名、后缀与地址段
full: 用于精确域名匹配,domain: 匹配所写域名及其子域名,不应把它理解为任意位置的字符串包含。需要正则时可用 regexp:,但最好先把规则想匹配和不想匹配的样例列出来;有些反斜杠还需要经过 JSON 字符串的转义。geosite: 引用域名数据集合,geoip: 引用地址数据集合,两者是否能用取决于运行环境提供的数据和对应标签。复制规则前先核对数据来源,避免把加载失败误判为匹配顺序问题。
ip 可匹配明文目标 IP 或 CIDR 地址段。写地址规则之前,应先弄清应用传给入口的是域名还是已经解析的地址。如果应用已经解析,路由未必还能看到原来的域名;同一地址也可能由多个不同名称共用,不能可靠倒推出访问的是哪个站点。反过来,当入口得到的是域名时,能否用它的解析地址来匹配 IP 规则,还取决于 domainStrategy 与内核 DNS 是否正常。
domainStrategy 影响何时尝试解析
AsIs 不为路由匹配额外解析目标域名。IPIfNonMatch 可在按现有目标未匹配时尝试解析并重新进行匹配,因此一条靠前命中的规则,或一条在首次匹配就抓住全部流量的兜底规则,都可能使预期的地址匹配没有机会发生。IPOnDemand 则会在匹配需要地址信息的规则时触发相应解析。选择策略前先明确是不是确实需要用解析后的地址做决策;单纯增加解析会引入另一个可能超时的环节,也未必能解释已有的域名规则为何没命中。
组合规则时,同一字段中的多个候选通常用于匹配其中任意一项,而同一条规则内不同条件需要同时成立。若希望同一个出口既处理某些域名,又处理某段 IP,通常写成两条分别引用该出口的规则更清楚,不要默认把域名和地址条件写在一起就是“或者”。修改后应重新加载并验证实际出口。更多语法对照见自定义路由规则的匹配语法与优先级。
dns 配置:查询来源、静态映射与回落
浏览器解析、内核解析和系统解析不是一回事
系统解析通常为使用系统解析接口的程序提供结果;浏览器或其他应用也可能自己维护缓存,或者使用独立的解析服务。内核的 dns 配置则用于内核自身需要查名字的场景,例如某些路由策略需要根据域名的解析结果判断 IP 规则。它不会因为出现在配置文件中就接管整台机器的查询。若测试应用最终只把 IP 交给入站,先前那次解析可能早已在应用或系统一侧发生,修改内核 DNS 也不会让同一请求恢复成域名目标。
"dns": {
"hosts": {
"example.org": "192.0.2.10"
},
"servers": ["localhost"],
"queryStrategy": "UseIP"
}
这是顶层 dns 字段的独立示例。hosts 演示内核自己的静态映射,示例地址属于文档地址段,不用于实际连通性测试。留下这条映射时,不应期待对该名称的内核查询得到真实服务地址。用于普通测试时可删除该映射。localhost 在这里是使用本机解析能力的特殊值,并非把 DNS 数据包发往回环地址的简写。UseIP 不将查询限制为某一个地址族,也不保证收到两种地址;最终结果与上游回答及目标记录有关。
查询使用哪条路径,要按场景确认
路由作决定时获得的地址,不一定就是最终出口拨号时使用的地址。前者可能只为判断一条 IP 规则,出口仍可能拿着原域名进行自己的解析或交给另一端处理。以 freedom 为例,出站自己的域名处理选项与 routing.domainStrategy 分属两个阶段,不要把两处的配置视为一个全局开关。要确认究竟是哪一层查了名字,可以先关掉其他测试流量,结合入口收到的目标、命中的规则与出口日志交叉判断。
使用多个解析来源时,也不要把它们简单看成按照数组顺序轮流重试的列表。某些配置允许为解析服务器限定适用域名,或者限制其能否参与回落。域名没有匹配到预期的解析服务器、该服务器超时、返回空结果,是不同情况。涉及细化选项时应依据当前内核识别的字段确认行为,而不是搬用另一个内核的配置。可以从单个已知可用的来源开始,先验证只有基础查询的情况,再加域名条件并分别比较命中和未命中的结果。
排查缓存、地址族与启动依赖
修改配置后看起来没有变化,先复查测试应用与内核是否仍持有旧缓存,或正在复用已经建立的连接。对同一名称测试时,重新建立应用连接,并记录查询和连接发生的时间。得到 IPv6 地址却连不上,不一定是 DNS 返回有误,也可能是出口缺少对应的 IPv6 连通性。尽量分别验证地址是否查得到、路由是否选择正确、对应地址是否真的可达,再判断是否有必要限制查询的地址族。
还有一种常见卡点出现在启动阶段:某个上游或远程端点以域名填写,解析该名称却依赖一条尚未建立的连接。此时不是多加几个解析地址就能解决,应该先画出依赖关系,找出哪次查询必须在连接建立前完成,以及它是否有独立可用的路径。Tun 模式开启后也要重新验证这一点,因为它可能改变查询实际走的接口,单看系统界面中填了哪个解析地址并不足够。
policy 策略:超时、用户级别与统计
按级别指定连接生命周期
"policy": {
"levels": {
"0": {
"handshake": 4,
"connIdle": 300,
"uplinkOnly": 2,
"downlinkOnly": 5
}
}
}
这是顶层 policy 示例,不是某个出站的 settings。levels 用字符串键表示级别;这里示范级别零,数值以秒计,是为了说明字段含义,不是统一的调优建议。不同协议在配置中指定用户级别的位置可能不同。修改某一级别却没有观察到变化时,先确认正在测试的连接是否使用该级别,以及运行内核是否把该项策略用于相关环节。策略主要约束连接生命周期和统计行为,不负责选择出口,也不赋予用户访问权限。
| 字段 | 约束阶段 | 常见误读 |
|---|---|---|
handshake | 相关协议的握手阶段。 | 不是覆盖解析、拨号与网页加载的总限时。 |
connIdle | 连接没有数据活动的阶段。 | 不是连接自建立起可以持续的总时长。 |
uplinkOnly | 下行已结束,仅剩上行。 | 不是上行速率限制。 |
downlinkOnly | 上行已结束,仅剩下行。 | 不是下行缓冲区大小。 |
先分辨握手失败、空闲结束与单向结束
偶发的首次连接失败,不一定和已经稳定运行一阵后才断开的连接属于同一问题。记录从何时开始无数据、是否仍有上行或下行,以及重连是否立刻恢复。若异常总在接近固定的空闲时间出现,既可能涉及内核空闲策略,也可能由应用、远程服务或中间设备结束连接。延长本地策略只改变本地一层,不能修改对端或网络设备的超时行为。反之,缩短时间后看到断开提前,可以提供一条佐证,但还需要确认测试期间没有切换网络或更新配置。
对于长时间不发送数据的应用,先判断它是否本来就有保活机制,再决定是否修改策略。保留空闲连接会消耗资源;把超时一律调大也可能让已经失效的连接更晚被发现。与其照搬他人的参数,不如建立小范围对照:在同一网络下用同一种应用建立新连接,先测基线,再仅调整与症状对应的字段。旧连接可能继续持有此前的状态,比较前应重新加载并建立新的会话。
统计开关与统计读取分开配置
如果需要诊断传输方向,可区分 policy.levels 中按用户级别控制的统计选项,以及 policy.system 中控制入站或出站方向的系统统计选项。设置统计开关不等于图形界面一定显示数字:支持相关机制的内核还需要启用统计功能,客户端也需要以兼容方式读取。标签为空、选错观察对象、重启后计数重置,都可能让读数和预期不同。某些界面还会汇总多个连接,因此数字增加并不能单独证明哪一条应用请求用了哪一个出口。
处理统计与日志时,应把本地诊断范围限制在实际需要的程度。为了看一条连接而长时间保留详细访问日志,容易积累没有必要的目标地址和时间信息。若要使用管理接口读取统计,不应把未经妥善隔离的管理入口开放到外部网络。完成定位后恢复日常日志级别,撤掉临时统计设置,并保留一份只写故障表现、改动和结论的简短记录,下一次遇到相同症状时更好复查。
内核选择与订阅配置边界
先看实际启动的内核,而非客户端名称
桌面建议从v2rayN 安装包开始,按照系统与处理器架构选择对应入口。客户端提供界面、订阅管理和设置保存,内核负责处理加载后的协议配置与连接。Android 上的 v2rayNG 使用 Xray 内核,v2flyNG 是选用 V2Fly 内核的备选客户端。Project V 是理解这一生态的起点;V2Fly 延续了 V2Ray 的社区维护路线,Xray 则从相关代码发展为自己的项目。字段名称可能相同,但不同内核支持的协议组合、传输方式与附加选项并不会始终同步。
要判断是界面选择问题还是内核加载问题,最有用的证据是本次运行的启动记录。先确认日志对应当前选中的配置,再确认运行的是预期内核。如果更换内核后出现未知协议、未知传输或字段类型错误,不应立即把对应字段删掉重新试;有些字段对于远端服务的连接是必要的,删掉只会把启动失败变成后续握手失败。更稳妥的顺序是先恢复已知能工作的内核与条目,再逐项核对兼容性。
使用共同字段做本地对照
"log": { "loglevel": "warning" },
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
示例是内核顶层片段,只描述日志和直接出站,完整测试还需要配合总览中的本地入站。适合在独立测试配置中先确认常见字段和本机监听都正常,再转回实际条目查差异。不要把示例加到已有配置尾部造成重复字段,也不要拿它覆盖图形客户端生成的实际出站列表。桌面界面选择可参考v2rayN 桌面版与 WPF 版的选择说明,界面框架与内核协议能力是两个不同的选择维度。
订阅分组、刷新与本地改动
订阅分组用于组织客户端里的来源和条目;它不是内核配置的顶层字段。刷新订阅,是客户端向已获授权的来源获取内容并尝试导入。一次刷新可分成取回内容、解析条目、在界面里更新列表几个阶段,任一阶段出错都可能让列表看起来没有变化。能刷新则只说明这条获取和导入链路可用,不等同于每个条目均能连接;同样,已经导入的条目暂时能连接,也不表示当前订阅地址仍可刷新。
手工调整某个订阅条目后,下一次刷新可能以来源数据覆盖本地改动,具体取决于客户端的合并方式。需要做对照时,可将获准使用的条目放在明确区分的本地测试副本中,并记录改了什么。遇到“更新后连错条目”,先核对分组、选中状态和实际启动记录,不能只认备注名称,因为不同来源可能使用同样的备注。若需要发截图协助排查,先遮住完整订阅地址、身份参数和各条目的远程信息。
初次导入按快速上手的导入步骤完成即可,不必先手写协议字段。若问题出在一份新订阅,但旧订阅正常,先分别验证来源可达和客户端是否识别其内容,不要同时修改路由和内核。弄清问题属于资料获取、解析入库、配置生成还是连接建立之后,再选择查阅本手册的相应章节。
Tun 模式:虚拟接口、系统路由与验证
分清接口接管和内核路由
系统代理依赖应用采用系统提供的代理设置;Tun 模式则通过虚拟网络接口和系统路由让选定流量进入处理链路。系统先决定数据包交给哪个接口,流量进入相应组件后,内核才有机会按规则选择出站。两层决策不能相互替代:把一条内核规则改成直连,并不会阻止数据包先经过虚拟接口;若系统层没有把流量交给虚拟接口,修改内核规则也不一定能影响这条流量。
通过已知入口隔离接管故障
"routing": {
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
这段属于内核路由示例,引用前文定义的 local-socks 和 direct,不是 Tun 配置。它适合放在独立配置中,借助受控的本地入口验证路由识别,再与虚拟接口接入的测试作比较。若两种接入方式都走向同一个默认出口,单看目标是否可达无法证明这条规则确实命中,需要结合日志观察入口和出口。不要假定虚拟接口接管后产生的流量也叫 local-socks,应根据客户端生成配置和记录确认它实际采用的处理路径。
按启用前、启用后、关闭后三次观察
启用之前,先确认没有开着会影响同一测试的其他接管工具,记下正常使用时的连接情况,并确认能够关闭新模式。启用时若提示授权失败或虚拟接口创建失败,先核对当前用户权限、系统限制与客户端启动记录。开关显示已打开只代表界面状态,还要确认虚拟接口实际出现,所需路由已经建立。若遗留的系统代理仍然开启,测试应用可能先连接回环代理而非直接交给系统路由,这样即使测试成功,也无法独立证明 Tun 路径已经生效。
启用后可以把测试分成两组:一组是需要经新接口处理的请求,另一组是本来应保持可达的局域网或工作网络资源。第一组失败时,查看客户端出口能否通过物理网络连接,确认连接出口的流量没有被接管路径重新捕获;第二组失败时,检查接口优先级、网段重叠和已有网络策略。若只有名称访问失败而直接用地址可以访问,应回到 DNS 章节,查清名称查询实际由谁发起、是否也被接管,以及查询是否依赖尚未建立的连接。
关闭后,再确认虚拟接口相关路由和代理设置已恢复到预期状态。切换网络、休眠唤醒或更新客户端后出现的故障,应重新检查实际接口和路由,而不是默认沿用上次的结果。若工作设备受统一管理,不要将提升权限或修改系统路由作为绕过限制的手段;可先采用批准的应用代理方式测试,必要时请维护者核对策略。
Android 客户端的接管由系统 VPN 授权机制管理,选定应用的机制与桌面设置不宜逐项套用。需要检查授权、后台限制或分应用范围时,从Android 快速上手确认基本路径,再看v2rayNG 的 VPN 权限、电池优化与分应用设置。无论在哪个平台,定位时都先回答两个问题:请求是否进入预期接口,以及进入后究竟选了哪个出口。