V2Ray Subscription Formats: Base64 Lists, Native JSON, and vmess:// Links

First, distinguish subscription URLs, node lists, and native JSON

“V2Ray subscription” is not a single file format. An HTTPS URL might return a Base64-encoded list of share links, a plain-text list, full JSON, or even a login page. Neither the file extension nor the presence of “subscribe” in the URL tells you what it contains; the client processes the response body returned by the server.

A typical Base64 subscription has two layers: the entire list is encoded once, and each line in the decoded text is a share link. If a line is a traditional JSON-based vmess:// link, its payload after the protocol prefix is Base64-encoded again. These layers encode different data, so you can’t parse the entire subscription as a single VMess node.

Where to import in v2rayN and v2rayNG

Choose the import method based on the content before considering conversion. Importing an HTTPS subscription URL from the clipboard as a node, or pasting full JSON into a subscription URL field, usually won’t work as expected. The steps below use common Chinese UI labels; wording may vary slightly by release, so choose the menu item by function.

Both clients can handle common traditional JSON-based VMess share links and typical subscriptions containing lists of share links. Import full native JSON through the custom configuration option; support for VMess does not mean support for every JSON subscription structure. Some configurations contain core-specific fields, so check both the client version and the selected core.

v2rayNG uses the Xray core; v2flyNG uses the v2fly core. They are not the same configuration interpreter with different interfaces. Before loading an Xray-specific configuration in v2flyNG, check protocol and field support instead of simply renaming the file. In v2rayN, confirm which core will run the configuration.

Decode locally: inspect the list, then the vmess:// payload

The JavaScript below is for inspecting text in your local browser’s developer tools; it makes no network requests. Read the code first, then run it in the console of a blank offline page. The functions take text you’ve already copied locally and do not download subscriptions. Don’t handle credentials in the console of an unfamiliar website.

function decodeBase64Utf8(input) {
  let text = input.trim().replace(/\s+/g, "");
  text = text.replace(/-/g, "+").replace(/_/g, "/");
  if (text.length % 4 === 1) {
    throw new Error("Invalid Base64 length");
  }
  text = text.padEnd(Math.ceil(text.length / 4) * 4, "=");
  const bytes = Uint8Array.from(atob(text), ch => ch.charCodeAt(0));
  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
}

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

function decodeVmessJson(uri) {
  const text = uri.trim();
  if (!text.startsWith("vmess://")) {
    throw new Error("Not a VMess share link");
  }
  return JSON.parse(decodeBase64Utf8(text.slice(8)));
}

// Self-test uses local examples only; no subscription credentials included.
console.log(decodeBase64Utf8(encodeBase64Utf8("Sample node")));

1. Identify the response: If the body already contains lines beginning with protocol prefixes such as vmess://, process them as-is; don’t decode the whole response again. If it starts with HTML or a login prompt, resolve the subscription request issue first.
2. Decode the outer layer: For a confirmed Base64 list, call decodeBase64Utf8, then split it into lines with split(/\r?\n/) and filter out empty lines.
3. Decode an individual link: Pass a traditional JSON-based VMess link to decodeVmessJson. The expected result is an object with fields such as add, port, and id.
4. Don’t keep retrying blindly: If decoding doesn’t produce JSON, check for a different share-link format. Not every legacy implementation using the same protocol prefix follows the JSON payload convention described here.

atob returns a string representing bytes; it does not decode UTF-8 for you. Without TextDecoder, Chinese node names may appear garbled. Calling btoa directly on Chinese text may throw an error. Also distinguish Base64URL’s - and _ from standard Base64’s + and /; don’t apply these substitutions to the subscription URL itself.

How fields map between vmess:// and native JSON

The example below is a traditional VMess share payload for demonstration only. The domain and UUID illustrate the structure and do not represent a connectable service. v is the share-format version, not the core version. aid is alterId; modern VMess AEAD configurations typically use 0, but check the server’s requirements when migrating.

{
  "v": "2",
  "ps": "Sample VMess WS TLS",
  "add": "node.example.com",
  "port": "443",
  "id": "8a7e4f30-5b91-4f8e-9e42-2c6d1b0a73f5",
  "aid": "0",
  "scy": "auto",
  "net": "ws",
  "type": "none",
  "host": "node.example.com",
  "path": "/gateway",
  "tls": "tls",
  "sni": "node.example.com"
}

The full example below uses the common vnext structure and includes one local SOCKS inbound and one VMess outbound. Whether the client retains inbound settings after import depends on how it runs custom configurations. Before use, check that the current core supports this field structure.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "node.example.com",
            "port": 443,
            "users": [
              {
                "id": "8a7e4f30-5b91-4f8e-9e42-2c6d1b0a73f5",
                "alterId": 0,
                "security": "auto"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "tlsSettings": {
          "serverName": "node.example.com",
          "allowInsecure": false
        },
        "wsSettings": {
          "path": "/gateway",
          "headers": {
            "Host": "node.example.com"
          }
        }
      }
    }
  ]
}

Re-encoding and converting back: what can be lost

To create a share link from a traditional JSON-based VMess payload, encode the JSON as UTF-8 and prepend the protocol prefix. Join multiple links with newlines and Base64-encode the result to create a common Base64 list body. The code below continues from the encoding functions above and still uses demonstration data.

const sample = {
  v: "2",
  ps: "Sample VMess WS TLS",
  add: "node.example.com",
  port: "443",
  id: "8a7e4f30-5b91-4f8e-9e42-2c6d1b0a73f5",
  aid: "0",
  scy: "auto",
  net: "ws",
  type: "none",
  host: "node.example.com",
  path: "/gateway",
  tls: "tls",
  sni: "node.example.com"
};

const share = "vmess://" + encodeBase64Utf8(JSON.stringify(sample));
const links = [share];
const subscriptionBody = encodeBase64Utf8(links.join("\n"));

console.log(share);
console.log(subscriptionBody);

Generating a list body does not create a subscription service. It becomes a refreshable remote entry point only when hosted at an address the client can access, with appropriate access controls. If you’re only moving nodes between devices, use the share links exported by the client; there’s no need to host a file.

• Converting a full configuration to a single node loses context: A regular VMess share link can’t fully represent DNS, routing rules, local listening ports, relationships between multiple outbounds, or outbound chains.
• A JSON file may contain multiple candidate outbounds: Find the target VMess outbound by checking protocol and tag. Don’t assume the first item in the array is the node you want to share.
• Transport extensions may not convert losslessly: If extra TLS or transport parameters are involved, confirm that the receiving client supports the corresponding share-link fields. Export, then import into a temporary configuration and compare each field.
• Changing protocols is not an encoding conversion: You can’t turn VMess into VLESS or Trojan by changing the prefix. The server must provide the corresponding protocol and credentials.

Troubleshooting failed imports, empty node lists, and garbled text

For a reliable migration, keep three things to compare: the original subscription body, the decoded node fields, and the imported client settings. Test one node first, then move on to the full list. For DNS and routing in a full JSON configuration, check each field alongside Advanced Setup. If you’re unsure what a field means, consult the glossary before trying multiple converters—it’s easier to pinpoint differences that way.