Xray 设置 IPv4 优先：三处配置与实际验证步骤

更新于 2026-11-01 · ghproxy.cyou

简答：一句话结论：想让 Xray 尽量使用 IPv4，先按连接对象配置对应字段——Freedom 直连使用 sockopt.domainStrategy，代理出站的目标域名使用 targetStrategy，Xray 内置 DNS 查询使用 dns.queryStrategy。普通排查先用 UseIPv4，只有确认必须拒绝 IPv6 时再考虑 ForceIPv4；修改后还要通过 Xray 的本地代理端口和服务端记录验证实际链路。

定义：Xray 的“IPv4 优先”不是一个全局开关，而是分别控制目标解析、代理服务器解析和 DNS 查询的多组策略。

先试这一步：按连接对象选择字段

本站是第三方使用指南站，不是 Xray 官方站。假如你遇到 IPv6 连接不稳定、应用要求 IPv4，或修改 DNS 后实际出口没有变化，先不要同时修改路由、TUN 和 DNS。先判断请求经过哪一段连接，再只改对应字段。

Project X 文档明确区分了这些作用范围：代理出站的 targetStrategy 控制被代理请求的目标域名，而代理服务器自身的域名以及 Freedom 直连目标则由 sockopt.domainStrategy 控制，可参考 Outbound 配置说明 和 Sockopt 配置说明。

UseIPv4、UseIPv4v6、ForceIPv4 怎么选

这三个值不能混为一谈。按照当前 Project X 字段说明，UseIPv4 和 UseIPv4v6 属于“优先或限制解析”的策略，但在解析失败或结果不符合要求时可能回退到 AsIs；ForceIPv4 则要求解析结果满足 IPv4 条件，否则连接不能建立。具体行为以当前核心版本的文档和实际日志为准。

建议先使用 UseIPv4 做单变量测试。确认目标域名有 A 记录、运行 Xray 的主机具备可用 IPv4 出口，并且业务确实需要拒绝 IPv6 后，再逐个出站评估 ForceIPv4。不要为了绕过断连关闭 TLS 校验或降低安全设置。

在 Sockopt 官方说明 中，AsIs、Use 与 Force 的回退行为，以及 sendThrough 与地址族冲突时的处理都有明确说明。

最小配置示例：Freedom、代理出站和 DNS

1. Freedom 直连：优先 IPv4

下面是字段片段，不是完整配置文件。它只展示 Freedom 的关键位置，原有的入站、路由和其他字段不要删除。

{"outbounds":[{"protocol":"freedom","tag":"direct","streamSettings":{"sockopt":{"domainStrategy":"UseIPv4"}}}]}

Freedom 连接的是最终目标，因此它的目标域名解析使用 streamSettings.sockopt.domainStrategy。如果要求强制 IPv4，可把值改为 ForceIPv4，但应先完成兼容性验证。相关作用范围见 Freedom 出站说明。

2. VLESS 代理出站：同时控制目标与代理服务器

下面是一份“替换占位符后才能使用”的最小骨架，包含本地 SOCKS 入站、VLESS 出站和 IPv4 策略。proxy.example.com、端口、UUID、TLS 服务名必须替换为你已有且可核验的配置；不要把示例值当成真实服务器。

{"log":{"loglevel":"warning"},"inbounds":[{"listen":"127.0.0.1","port":10808,"protocol":"socks","settings":{"udp":true},"tag":"socks-in"}],"dns":{"servers":["https://1.1.1.1/dns-query"],"queryStrategy":"UseIPv4"},"outbounds":[{"protocol":"vless","tag":"proxy","targetStrategy":"UseIPv4","settings":{"vnext":[{"address":"proxy.example.com","port":443,"users":[{"id":"00000000-0000-0000-0000-000000000000","encryption":"none"}]}]},"streamSettings":{"network":"tcp","security":"tls","tlsSettings":{"serverName":"proxy.example.com"},"sockopt":{"domainStrategy":"UseIPv4"}}},{"protocol":"freedom","tag":"direct","streamSettings":{"sockopt":{"domainStrategy":"UseIPv4"}}}],"routing":{"rules":[{"type":"field","inboundTag":["socks-in"],"outboundTag":"proxy"}]}}

这里有两个容易混淆的字段：targetStrategy 控制被代理请求的目标域名是否在本地解析以及使用哪种地址族；sockopt.domainStrategy 控制连接到 proxy.example.com 时如何解析代理服务器地址。VLESS 出站字段结构可对照 VLESS 官方配置说明。

3. Xray 内置 DNS：只查询 A 记录

如果目标只是限制 Xray 内置 DNS 查询，可以设置：

{"dns":{"servers":["https://1.1.1.1/dns-query"],"queryStrategy":"UseIPv4"}}

dns.queryStrategy: UseIPv4 只查询并允许查询 A 记录，但它不等于强制所有出站连接使用 IPv4。当前 DNS 文档还说明，全局 queryStrategy 会约束 DNS 子项；全局与子项策略冲突时，子项查询可能返回空响应。详情见 Xray 内置 DNS 文档。

修改、检查并通过本地代理验证

1. 备份当前配置：复制正在运行的 JSON、YAML 或面板导出文件，确认修改的是实际启动配置，而不是下载目录中的另一份文件。
2. 确认链路：记录请求最终走 Freedom 还是 VLESS、VMess、Trojan 等代理出站；同时确认代理服务器地址是域名、IPv4 还是 IPv6。
3. 先只改一个字段：普通代理先改目标出站的 targetStrategy: "UseIPv4"；如果代理服务器是域名，再检查同一出站的 streamSettings.sockopt.domainStrategy；需要限制内置 DNS 时，最后再改 dns.queryStrategy。
4. 检查配置文件：在运行 Xray 的机器上执行 xray run -test -c /实际路径/config.json。-test 只测试配置，不启动服务，字段说明见 Xray 命令行参数。
5. 重启正确的实例：如果由 systemd、面板或桌面客户端托管，应使用对应的重载或重启入口。配置检查通过只代表文件可被读取，不代表运行中的进程已经加载了它。
6. 通过 SOCKS 入站发起请求：假设本地 SOCKS 入站监听 127.0.0.1:10808，可执行 curl -v --proxy socks5h://127.0.0.1:10808 https://example.com。socks5h 表示让 SOCKS 代理解析目标主机名；如果你使用的是 HTTP 入站，则改为 curl -v --proxy http://127.0.0.1:10809 https://example.com。参数行为可对照 curl 官方命令手册。
7. 验证实际地址族：这条 curl 命令只能证明请求确实经过本地 Xray 代理，不能单独证明远端最终使用 IPv4。要确认地址族，应结合 Xray 实际连接日志、目标服务端记录，或使用你自己控制且会记录客户端地址族的测试服务。

如果 Xray 日志没有显示足够的连接细节，不要把“请求成功”直接等同于“已经使用 IPv4”。可以临时提高日志级别进行单次对照测试，完成后恢复原日志设置；日志字段和级别应以当前版本的 Xray 日志配置 为准。

IPv6 仍生效、改后断网与 UDP 异常排查

当前 Sockopt 文档指出，UDP 默认偏向 IPv4，但发送失败不会自动切换到另一地址族；因此“网页能打开”不能证明 QUIC、DNS over UDP 或其他 UDP 流量同样满足 IPv4 要求。涉及 TUN、路由器或桌面客户端时，还要确认客户端是否生成了自己的出站配置；如果客户端覆盖了原生 Xray 字段，应以实际导出的配置和运行日志为准。

常见问题

只设置 dns.queryStrategy: UseIPv4，能保证 Xray 使用 IPv4 吗？

不能。它主要限制 Xray 内置 DNS 的查询类型，使其只查询 A 记录。Freedom 的连接还要看 sockopt.domainStrategy，代理出站目标还要看 targetStrategy，代理服务器自身域名则要看对应出站的 sockopt.domainStrategy。

UseIPv4 和 ForceIPv4 应该选哪个？

一般先用 UseIPv4 排查和验证。确认业务必须拒绝 IPv6，并且目标域名、DNS、主机 IPv4 路由都正常后，再考虑 ForceIPv4。Force 策略不满足地址族要求时不会像普通兼容性配置那样继续建立连接。

UseIPv4v6 是不是 IPv4 连接失败后自动换 IPv6？

不是。它优先进行 IPv4 解析，只有 IPv4 查询报错或没有 IPv4 结果时才查询 IPv6。如果已经得到 IPv4 地址，但后续连接失败，不会因为连接失败再自动回退到 IPv6。

targetStrategy 能控制代理服务器地址吗？

不能。它控制的是被代理请求的目标域名。代理服务器自身的域名解析应放在该出站的 streamSettings.sockopt.domainStrategy 中。

为什么配置检查通过，重启后仍像没有变化？

常见排查方向是：修改的文件不是运行实例使用的文件、面板启动时重新生成了配置、客户端覆盖了原生字段，或只改了 DNS 没改实际出站。请核对启动参数、面板导出路径、运行日志和本地代理端口，再用同一网址重新验证。

curl 通过 SOCKS 访问成功，是否就能证明出口一定是 IPv4？

不能。它主要验证请求经过了指定的本地代理；要证明实际地址族，还需要查看 Xray 的连接信息、目标服务端记录，或使用可记录客户端 IPv4/IPv6 的自有测试服务。TCP 测试也不能替代 UDP 或 QUIC 测试。

常见问题

只设置 dns.queryStrategy 为 UseIPv4，能保证 Xray 使用 IPv4 吗？

不能。它主要限制内置 DNS 查询 A 记录，实际连接还要按 Freedom、代理目标和代理服务器分别检查对应字段。

UseIPv4 和 ForceIPv4 应该选哪个？

先用 UseIPv4 做兼容性验证；确认必须拒绝 IPv6 且 IPv4 网络正常后，再考虑 ForceIPv4。

UseIPv4v6 是不是 IPv4 连接失败后自动换 IPv6？

不是。它只在 IPv4 查询报错或没有 IPv4 结果时查询 IPv6，已有 IPv4 结果但后续连接失败时不会自动换 IPv6。

targetStrategy 能控制代理服务器地址吗？

不能。targetStrategy 控制被代理请求的目标域名；代理服务器自身域名应使用对应出站的 streamSettings.sockopt.domainStrategy。

curl 通过 SOCKS 访问成功，是否证明出口一定是 IPv4？

不能。curl 主要验证请求经过本地代理；实际地址族还应结合 Xray 日志、目标服务端记录或自有测试服务确认。

相关阅读

• 继续看 v2rayN DNS 设置与解析失败排查
• v2rayN 连接失败的时间、代理与日志排查
• 代理连接超时：从本地端口到上游链路定位
• 浏览器能用、软件不能用时检查实际请求链路

参考资料

1. Project X：Sockopt 配置说明
2. Project X：Outbound Proxy 配置说明
3. Project X：内置 DNS 服务器
4. Project X：VLESS 出站配置说明
5. Project X：Freedom 出站配置说明
6. Project X：命令行参数
7. curl 官方命令手册（curl.se）
8. xtls.github.io