V2Ray 订阅格式详解:Base64 订阅、原生 JSON 配置与分享链接如何互相转换

一、订阅地址、Base64 与 JSON 的层级区别

“V2Ray 订阅”不是一种唯一的文件格式。日常收到的 HTTPS 地址只是获取入口；客户端访问它之后，才得到实际响应。响应可能是每行一条的分享链接，也可能是把整个链接列表做了一次 Base64 编码的文本。某些服务还会根据请求头返回不同内容，因此不能只看地址后缀判断格式。

两个对象即使都是 JSON，也不代表能够互换。VMess 分享对象描述一台服务器及其传输参数；Xray 配置描述内核如何监听本地端口、建立出站以及执行路由。把前者保存成 config.json，不会自动变成后者；把后者整体做 Base64，也不会自动成为客户端支持的订阅。

二、VMess 与 VLESS 分享链接的字段结构

常见的 VMess 分享格式是 vmess:// 加上一段 Base64，解码结果为 JSON。下面仅展示该 JSON 的内容，所有域名和 UUID 都是教学用虚构数据，不能用于连接。v: "2" 是这种分享对象的格式标记，不是客户端版本，也不是内核版本。

{
  "v": "2",
  "ps": "示例 VMess WS",
  "add": "edge.example.com",
  "port": "443",
  "id": "00000000-0000-4000-8000-000000000001",
  "aid": "0",
  "scy": "auto",
  "net": "ws",
  "type": "none",
  "host": "edge.example.com",
  "path": "/ws",
  "tls": "tls",
  "sni": "edge.example.com"
}

add 是连接地址，port 是远端端口，id 是用户标识；net、host、path 分别参与传输方式及 WebSocket 请求设置。aid: "0" 对应当前常见 VMess AEAD 配置，不应为了消除报错而任意改成其他数字。示例中的 type: "none" 也不能当成关闭 TLS 的开关。

VLESS 分享链接通常直接使用 URI 结构，身份信息放在 @ 前，服务器与端口放在其后，传输参数写在查询串中。下面同样是不可连接的示例，链接应保持为完整的一行：

vless://[email protected]:443?encryption=none&security=tls&type=tcp&sni=edge.example.com#demo-vless

URI 参数值需要按 URL 规则编码。例如路径 /ws?ed=2048 作为一个参数值时，应写成 path=%2Fws%3Fed%3D2048，避免其中的问号被误解为另一层查询串。备注中的中文、空格和特殊符号也应正确编码。不要对整条 URI 一次性做百分号编码，否则协议头与分隔符也会被破坏。

三、Base64 订阅的本地解码与重新编码

典型转换链条是“多条分享链接 → 用换行符连接 → 对整个文本做 Base64”。如果其中包含 VMess，就会出现两层编码：外层包住列表，内层包住单条 VMess 的 JSON。外层解开后已经出现 vmess:// 时，应先按行拆分，而不是把带协议头的整段内容继续当成 Base64。

以下原生 JavaScript 可在本地空白页的开发者工具控制台中运行。先阅读代码，只把自己的数据放入本地变量；它不发起网络请求。编码函数使用 UTF-8，避免中文备注直接传给 btoa() 时出错；解码函数同时处理标准 Base64 与常见的 URL 安全字符变体。

function encodeSubscription(text) {
  const bytes = new TextEncoder().encode(text);
  let binary = "";
  for (const byte of bytes) {
    binary += String.fromCharCode(byte);
  }
  return btoa(binary);
}

function decodeSubscription(text) {
  let encoded = text.trim()
    .replace(/\s+/g, "")
    .replace(/-/g, "+")
    .replace(/_/g, "/");

  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
    throw new Error("内容不是有效的 Base64 字符序列");
  }

  encoded = encoded.replace(/=+$/, "");
  if (encoded.length % 4 === 1) {
    throw new Error("Base64 长度异常，请检查是否复制完整");
  }

  encoded += "=".repeat((4 - encoded.length % 4) % 4);
  const bytes = Uint8Array.from(atob(encoded), char => char.charCodeAt(0));
  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
}

const demoLink =
  "vless://[email protected]:443"
  + "?encryption=none&security=tls&type=tcp&sni=edge.example.com#demo-vless";

const encodedDemo = encodeSubscription(demoLink);
console.log(encodedDemo);
console.log(decodeSubscription(encodedDemo));

• 列表转订阅正文：先用 links.join("\n") 生成逐行文本，再交给 encodeSubscription()。不要把每一行分别编码后直接拼接。
• 订阅正文转列表：解码一次，确认协议头，再用换行符拆分并去掉空行。若结果仍是 HTML 或报错信息，应回到获取环节排查。
• 单条 VMess 转 JSON：先移除 vmess:// 前缀，再解码后面的内容，最后用 JSON.parse() 检查结构。
• VMess JSON 转分享链接：对对象执行 JSON.stringify()，编码得到的文本，再加上 vmess://。这一步只适用于对应的分享对象。

四、v2rayN 与 v2rayNG 的导入入口

选择入口的依据是“手上有什么”。订阅地址放进订阅分组，单条或多条分享链接走剪贴板，完整内核 JSON 走自定义配置。桌面版与安卓端的菜单位置会随版本调整，下列使用常见中文菜单名称；若界面文字略有差异，应以对应的导入功能为准，不要把订阅地址误填进服务器地址栏。

v2rayN：先建分组，再更新订阅

1. 创建分组

   在主窗口打开「订阅分组」→「订阅分组设置」，使用「添加」建立分组，填写备注和订阅地址，保存后返回服务器列表。

2. 获取内容

   在「订阅分组」菜单中选择「更新当前订阅（不通过代理）」或对应的通过代理更新项。当前网络能够直达订阅服务时先用前者；后者需要已有可用代理及正确的代理通路。

3. 导入链接

   如果只有分享文本，复制完整链接，在「服务器」→「从剪贴板导入批量 URL」执行导入；常见桌面界面也可使用 Ctrl+V。此方式添加的是节点快照，不会建立远程订阅更新关系。

4. 核对参数

   打开导入条目的编辑窗口，检查服务器地址、端口、传输协议、TLS 与 SNI。只有列表中出现条目还不够，应启动该条目并检查底部核心日志是否出现配置解析错误。

v2rayNG：订阅与剪贴板分别处理

• 订阅地址：从主界面菜单进入「订阅分组设置」，点击「+」填写备注与地址，保存后返回主界面，再从菜单执行「更新订阅」。
• 分享链接：复制完整文本，点击主界面「+」→「从剪贴板导入」，确认新增条目的传输和安全参数，再选择条目启动连接。
• 原生 JSON：使用「+」菜单中对应的自定义配置导入入口，按文件或剪贴板来源选择；不要假设普通分享链接入口会接受任意 JSON。
• 内核兼容：v2rayNG 使用 Xray 内核，v2flyNG 使用 V2Fly 内核。能被某个客户端识别的链接，不代表其中每项扩展参数都能被另一个内核执行，尤其要核对 Reality、Flow 等功能。

如果把订阅解码后手工导入，后续服务端改了地址、端口或身份信息，本地快照不会自动跟着变。需要持续更新时保留原订阅分组；迁移时也应分别备份订阅地址和本地自定义设置，而不是只保存一份分享链接列表。

五、分享链接映射到 Xray 原生 JSON

客户端生成内核配置时，不只是把字段改名，还会加入本地入站、出站标签、日志与路由等运行信息。下面将前文 VLESS TCP + TLS 示例映射为一份最小 SOCKS 配置：本地仅监听 127.0.0.1:10808，远端仍是教学域名，因此只用于理解结构，不能直接联网使用。

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "edge.example.com",
            "port": 443,
            "users": [
              {
                "id": "00000000-0000-4000-8000-000000000001",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "edge.example.com"
        }
      }
    }
  ]
}

本地端口 10808 是这里明确设置的示例值，不应据此推断所有客户端当前都监听此端口。运行前先确认端口未被其他程序占用。只监听回环地址可以避免把未设认证的 SOCKS 入站暴露到局域网；也不要为了修复远端连接而把它改成所有网卡监听。

完整 JSON 反向导出为分享链接时，通常只能提取某一个兼容的代理出站。routing.rules、DNS、多个入站、多个出站之间的组合关系，不属于单节点分享链接的完整表达范围。原配置如果依赖这些设置，应继续保留 JSON，而不是认为导出一个二维码就完成了完整迁移。

• 可尝试往返：服务器地址、端口、UUID，以及双方都支持的传输与 TLS 参数。
• 需要额外核对：客户端特有参数、未被导入器识别的查询项、指纹与高级传输选项；解析器可能忽略它们而不立即报错。
• 应单独备份：订阅更新关系、路由规则、DNS 策略、本地端口和客户端界面设置。

六、导入为空、解码报错与转换丢字段

排查时按“获取 → 解码 → 解析 → 运行”分层记录结果。订阅更新成功仅说明客户端完成了某次处理；是否生成条目、字段是否完整、内核是否启动、远端是否可达，仍是不同的检查点。先在最早失败的环节修正，避免同时修改 TLS、端口和订阅地址而失去对照。

七、转换后的验证与备份顺序

最稳妥的迁移单位不是“一个看起来很长的字符串”，而是明确用途的三份数据：原订阅地址用于后续更新，分享链接用于节点交换，完整配置或客户端备份用于恢复本地行为。三者可以同时保存，但不能彼此替代；包含身份信息的备份应放在受访问控制的本地位置。

1. 保留原件：在转换前保存原始响应或原始文件，避免只剩一份经过多次处理的结果。
2. 核对单条：先选一个条目比对协议、地址、端口与传输参数，确认没有把 UUID、Host 与 SNI 混为一项。
3. 检查启动：启用条目并查看核心日志；先解决配置解析和端口占用，再处理证书、握手与远端连通问题。
4. 检查应用：桌面应用还需正确接入系统代理或指定的本地代理端口；安卓端则需确认已启动连接并授予系统要求的 VPN 权限。
5. 验证更新：若迁移目标包含订阅，在目标客户端手动更新一次，确认新增内容进入预期分组，而不是仅存在一批静态节点。