v2ray 配置怎么写？内核区别、JSON 模板与连接排查

更新于 2026-10-24 · wkacc.top

简答：v2ray 配置不是一份通用 JSON：V2Fly v4 与 Xray 的 VMess 字段层级不同。先确认实际内核，再替换地址、端口和 UUID，最后用对应命令检查配置并查看连接日志。

定义：v2ray 配置是由 JSON 描述入站、出站、路由、DNS 和日志等模块的文件，客户端配置与服务端配置的流量方向和字段位置并不相同。

先确认内核：V2Ray、V2Fly、Xray 和客户端不是一回事

搜索“v2ray 配置”时，最容易踩的坑是把客户端名称、核心程序和配置格式混为一谈。V2Ray是项目名称；V2Fly是社区维护的 V2Ray 分支与核心实现；Xray是另一套兼容部分 V2Ray 配置思路、但持续增加自身字段和功能的核心。V2Fly 核心仓库与Xray 核心仓库都应以各自文档为准。

v2rayN和v2rayNG是客户端界面，不等于核心本身。v2rayN 官方说明支持 Xray、sing-box 等核心，实际使用哪一个要看客户端的核心设置和安装包；v2rayNG 是 Android 端客户端，不能把它的界面字段直接当作 V2Fly 或 Xray 的原始配置格式。v2rayN 官方仓库 v2rayNG 官方仓库

因此，拿到一份配置后，第一步不是改 UUID，而是打开客户端的核心设置、运行日志或配置详情，确认它加载的是 V2Fly、Xray 还是其他核心。配置文件名、自动生成路径和字段兼容性都可能随客户端变化。

JSON 配置的基本结构：先读懂入口、出口和数据流

V2Ray 类核心通常把流量拆成 inbounds 和 outbounds。客户端的 inbounds 接收浏览器或本机应用的 SOCKS/HTTP 流量，再由 outbounds 连接远端节点；服务端则通常由 inbounds 接收客户端连接，再由 outbounds 访问目标地址。V2Fly 的官方指南也用“入口与出口”解释这一数据流。V2Fly VMess 配置指南

• log：访问日志和错误日志。排查启动失败、连接失败时应先打开或查看错误日志。
• dns：核心内部的域名解析设置。DNS 能解决“域名解析失败”，但不能修复远端端口不通或 UUID 错误。
• inbounds：本机或服务器监听的入口，包括监听地址、端口、协议和认证信息。
• outbounds：下一跳出口，例如客户端连接远端节点，或服务端直接访问目标地址。
• routing：根据域名、IP、端口或标签选择出口；规则顺序和目标标签必须对应。
• transport：传输层参数，例如 TCP、WebSocket、gRPC 等。客户端与服务端的传输类型、路径和安全参数必须成对匹配。

JSON 语法本身也会导致启动失败：对象使用花括号，数组使用方括号，键和值之间用冒号，多个成员之间用逗号；字符串必须使用双引号，数字和布尔值不能写成字符串。示例中的地址、端口、UUID、路径和域名都是占位符，不能直接照抄为真实连接参数。

先做纯语法检查，再做核心检查。Linux 上可以使用以下命令检查标准 JSON；如果配置含有某些核心支持的注释，通用 JSON 工具可能报错，此时应删除注释后再检查。

jq . config.json

V2Fly 与 Xray 的检查命令不要混用。V2Fly 常见写法如下，具体参数以所安装核心的帮助信息为准：

v2ray test -c config.json

Xray 使用运行命令的测试参数：

xray run -test -c config.json

测试通过只代表配置能够被核心解析，不代表远端地址可达、服务端参数匹配或系统代理已经生效。

最小客户端与服务端配置：V2Fly v4 和 Xray 不要混用字段层级

下面只演示最小 VMess TCP 配置，用于理解字段对应关系和本地排查。它不是可直接使用的节点，也没有包含 TLS、WebSocket、gRPC、路由规则或 DNS 分流。请将尖括号中的值替换为你有权使用的服务器参数，并在修改前备份原文件。

V2Fly v4 客户端写法

V2Fly v4 的 VMess 出站通常把服务器信息放在 settings.vnext 数组中，用户 ID 放在 users 数组内。服务器地址、服务器端口和 UUID 必须与服务端对应。

{
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "<服务器域名或IP>",
            "port": <服务器端口>,
            "users": [
              {
                "id": "<UUID>",
                "alterId": 0,
                "security": "auto"
              }
            ]
          }
        ]
      }
    }
  ]
}

V2Fly v4 服务端写法

服务端的 inbounds[0].settings.clients[0].id 应与客户端的 UUID 相同；服务端监听端口应与客户端 vnext[0].port 相同。alterId 也不能一端写成其他值。V2Fly 的官方示例使用 alterId: 0，新配置不要随意照搬旧教程中的非零值。V2Fly VMess 官方示例

{
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": <服务器端口>,
      "protocol": "vmess",
      "settings": {
        "clients": [
          {
            "id": "<UUID>",
            "alterId": 0
          }
        ]
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

Xray 客户端字段层级

Xray 当前文档给出的 VMess 出站示例使用扁平字段：settings.address、settings.port 和 settings.id。这与 V2Fly v4 的 vnext 写法不是同一份模板，不能把一份配置的字段直接搬到另一套核心中。Xray VMess 出站文档

{
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vmess",
      "settings": {
        "address": "<服务器域名或IP>",
        "port": <服务器端口>,
        "id": "<UUID>",
        "security": "auto"
      }
    }
  ]
}

如果 Xray 报未知字段，或 V2Fly 报无法解析 address、id，不要继续改其他参数；先回到上面的内核判断，选择与核心文档一致的结构。Xray 官方配置说明也要求客户端与服务端的 ID 和端口保持对应。Xray 配置与运行说明

v2rayN、v2rayNG 导入与实际配置确认

如果你使用图形客户端，通常不需要手动编辑完整的 config.json。更稳妥的流程是先导入合法来源提供的分享链接、二维码、订阅地址或本地文件，再在客户端中查看生成的配置和运行日志。v2rayN 官方订阅说明列出了 VMess、VLESS、Shadowsocks、SOCKS、Trojan、WireGuard 等支持格式，但具体能否运行仍取决于客户端版本、核心和链接参数。v2rayN 订阅功能说明

1. v2rayN：添加订阅地址后执行更新，或从剪贴板导入分享链接；选中目标配置并设为活动配置，再打开系统代理。随后查看当前核心、运行日志和实际监听端口。不要假定 v2rayN 默认使用某个核心。
2. v2rayNG：在配置页面通过“从剪贴板导入”“从二维码导入”或“从本地文件导入”添加配置，选中配置后启动服务。Android 的 VPN 模式需要系统 VPN 权限；如果只启用应用内代理或分应用代理，未被纳入的应用不会自动走代理。相关菜单名称可随版本变化，功能入口以应用实际界面为准。v2rayNG 官方界面字段
3. 确认加载文件：不要只看磁盘里的旧 config.json。从客户端日志确认核心启动命令、配置路径、监听端口和所选配置；若客户端会根据订阅重新生成运行配置，直接修改原文件可能在更新或重启后被覆盖。

平台差异也会影响结果：Windows 使用系统代理或 TUN 服务模式时，可能需要允许应用创建服务或网络接口；macOS 使用系统扩展、VPN 或网络权限时，应在“系统设置→隐私与安全性”中完成放行；Linux 以专用用户运行服务时，要确保配置文件和日志目录对该用户可读写；Android 的 VPN 模式需要系统授权。iOS 不在本文的操作路径内，不要把 Android 客户端步骤直接套用到 iOS。

按现象排查：启动失败、端口占用与连接失败

建议按照“配置文件→本地端口→远端参数→时间与传输→DNS与路由”的顺序排查。每次只改一个变量，并保留能启动的备份。

如果远端端口完全不可达，先检查服务器防火墙、云平台安全组、局域网出口限制和端口监听状态；如果端口可达但认证失败，重点看 UUID、时间、alterId、传输层和 TLS/SNI 是否一致。排查时不要把“配置测试通过”误认为“网络连接已经成功”。

完成修改后，按以下顺序复核：

• 备份原配置，并记录当前使用的核心和配置路径。
• 运行 JSON 语法检查。
• 运行对应核心的配置测试命令。
• 启动客户端，确认本地监听端口没有冲突。
• 查看连接日志，确认请求命中了预期出站或策略。
• 使用浏览器或应用进行实际连接测试，再对比出口 IP、DNS 解析结果和失败时间。

相关指南

如果你的实际问题不是手写 JSON，而是客户端导入、端口设置或连接故障，可以继续查看：Clash、v2rayN 代理端口与 TUN 模式教程、连接问题排查，以及设备配置指南。这些页面分别承接客户端端口、系统网络和设备差异问题。

常见问题

V2Ray、V2Fly 和 Xray 的配置可以直接通用吗？

不能默认通用。V2Fly v4 的 VMess 出站常见 vnext/users 层级，Xray 文档示例可能使用 address、port、id 的扁平层级。先确认实际核心，再使用对应文档格式。

v2rayN 默认使用 V2Ray 还是 Xray？

不能把默认核心写死。v2rayN 是图形客户端，官方说明支持 Xray、sing-box 等多个核心；应在客户端的核心设置、启动日志或发布包中确认实际核心。

为什么 JSON 看起来正确，启动后仍然无法连接？

JSON 语法正确只代表文件能被解析。还要检查服务器地址、端口、UUID、alterId、传输参数、TLS/SNI、系统时间、防火墙和本地代理设置。

VMess 的 UUID 和端口哪些必须一致？

客户端连接目标的服务器地址和端口，要对应服务端监听地址与端口；客户端 UUID 要与服务端用户 ID 完全一致。若使用传输层，还要逐项匹配路径、服务名和安全参数。

本地 10808 端口被占用怎么办？

先查占用进程，再决定关闭冲突程序或更换端口。Windows 可运行 <code>Get-NetTCPConnection -LocalPort 10808 | Select OwningProcess</code>，Linux 使用 <code>sudo ss -lntup | grep 10808</code>，macOS 使用 <code>lsof -nP -iTCP:10808 -sTCP:LISTEN</code>。

为什么改了 config.json，客户端重启后又恢复原样？

很多图形客户端会根据订阅或配置项重新生成运行文件。应确认客户端实际加载路径，并优先使用客户端提供的配置编辑、覆写或订阅设置入口。

相关阅读

• Clash、v2rayN 代理端口与 TUN 模式教程
• 连接问题排查
• 设备配置指南

参考资料

1. v2fly/v2ray-core 官方仓库
2. XTLS/Xray-core 官方仓库
3. V2Fly VMess 配置指南（guide.v2fly.org）
4. Xray VMess 出站配置文档
5. Xray 配置与运行说明
6. v2rayN 官方仓库
7. v2rayN 订阅功能说明
8. v2rayNG 官方仓库
9. v2rayNG 官方界面字段