V2Ray Subscription Formats Explained: Base64, Native JSON, and Share Links

Identify the content first: a subscription URL isn’t a subscription format

What people commonly call a “V2Ray subscription” isn’t a single file standard supported by every client. A subscription URL beginning with https:// only tells you that the client needs to access an endpoint; the response body determines whether it contains a list of links, Base64 text, or a config file. The same endpoint may return different content based on request parameters or client identifiers, so the URL suffix alone can’t tell you whether it’s compatible.

When retrieving a subscription response, check that it isn’t actually an error page. HTML at the start, a sign-in prompt, or a message saying access has expired means the request didn’t return the expected node data. Base64-encoding the error page again only gives you an encoded error page; it won’t fix the subscription.

Choose a format for the task: manage routine updates separately from full configs

In v2rayN, v2rayNG, and v2flyNG, server lists and runtime configs are separate layers. A client can generate a core config from server details, but local ports and routing rules in a full config may not fit into a share link. Before choosing a format, decide whether you’re migrating “nodes” or “nodes plus local policies.”

v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. For v2rayN, compatibility depends on the selected core. JSON configs aren’t automatically interchangeable, and support for VLESS doesn’t mean every transport and security setting works in every target version. Check the target client and core’s actual capabilities before converting.

How to decode a Base64 subscription: unwrap it, then check each line

A common way to create a Base64 subscription is to join multiple share links with newlines, then encode the whole string. After decoding the outer layer, you may see a mix of vmess:// and vless:// links. Note that traditional VMess share links contain another Base64 layer, so decoding the subscription doesn’t also decode each VMess node.

Base64 is an encoding, not encryption. Standard Base64 commonly uses +, /, and trailing = padding. The URL-safe variant uses - and _, and some outputs omit padding. Handle Chinese labels as UTF-8; converting character encodings directly can produce garbled text.

The function below can be run locally in a blank browser tab’s developer console. It only processes the text you pass in and makes no network requests. The example domain, UUID, and port illustrate the structure; they aren’t usable connection details.

function decodeBase64Utf8(input) {
  let text = input.trim().replace(/\s+/g, "")
    .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(input) {
  const bytes = new TextEncoder().encode(input);
  const binary = Array.from(bytes, byte => String.fromCharCode(byte)).join("");
  return btoa(binary);
}

const exampleLink = "vless://[email protected]:443?encryption=none&security=tls&type=tcp&sni=example.com#TLS-demo";
const encodedList = encodeBase64Utf8(exampleLink + "\n");
console.log(decodeBase64Utf8(encodedList));

1. First check whether the response already lists protocol links in plain text. If it does, inspect the list directly; there’s no need to decode it.
2. If the response is one encoded block, use a decoder to remove the outer wrapper, split the result by line breaks, and skip blank lines.
3. Check the protocol prefix on each line. Only decode the content after the prefix when you’ve identified the traditional VMess format.
4. If decoding fails, keep the original text and check for truncation, webpage content, or character substitutions. Repeated blind decoding won’t fix the problem.

VMess and VLESS share links: different structures, not interchangeable prefixes

Traditional VMess links: JSON encoded as Base64

A common traditional VMess share link consists of vmess:// followed by Base64-encoded node JSON. This node JSON isn’t a full core config; it doesn’t describe all local inbounds and routing rules. The example below shows a typical field structure before encoding. Here, v identifies the share format version, not the client or core version.

{
  "v": "2",
  "ps": "VMess TLS example",
  "add": "example.com",
  "port": "443",
  "id": "11111111-1111-4111-8111-111111111111",
  "aid": "0",
  "scy": "auto",
  "net": "tcp",
  "type": "none",
  "host": "",
  "path": "",
  "tls": "tls",
  "sni": "example.com"
}

Serialize this object, then use the encoding function above to build a traditional link: "vmess://" + encodeBase64Utf8(JSON.stringify(node)), where node is the object shown above. To parse one, remove the prefix, decode the rest, and read it with JSON.parse. Here, aid: "0" corresponds to a common VMess AEAD config; don’t change it to another value based on outdated guides.

VLESS links: URI fields and query parameters

VLESS usually uses a URI structure: the user identifier comes before @, the server address and port follow it, transport and security settings go in the query string, and the label follows #. Encode Chinese labels as percent-encoded text. Special characters in other fields should also be encoded with a URI utility; don’t concatenate raw text without handling it.

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

• encryption=none is a VLESS protocol setting; it doesn’t disable TLS. Use settings such as security=tls to indicate whether TLS is enabled.
• sni is the server name used in the TLS handshake. Don’t confuse it with the WebSocket HTTP Host or connection address.
• type=tcp specifies the transport type in this example. Switching to another transport also requires its corresponding parameters and server-side support.
• VMess and VLESS use different authentication and config structures. Changing vmess:// to vless:// won’t convert the protocol or change the server.

Converting native JSON: extract a node, don’t expect to preserve the entire setup

A full config covers both how traffic enters the local device and how it’s sent to remote servers. The compact Xray-style example below listens for SOCKS traffic on a loopback address and routes it through a VLESS TLS outbound to an example domain. It illustrates the field hierarchy; it contains no usable credentials and isn’t a universal config for every core.

{
  "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": "vless",
      "settings": {
        "vnext": [
          {
            "address": "example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-1111-4111-8111-111111111111",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "example.com"
        }
      }
    }
  ]
}

The outbound subfields in the table above refer to outbounds[0]. When extracting fields manually, first select the actual proxy outbound, then read its protocol and transport settings. Don’t always take the first array item: in a real config, the first may be a direct outbound, and there may be multiple proxy outbounds, chained connections, or load balancing.

1. JSON to share link: Extract the fields that can be represented by the target outbound, then generate a link using the relevant protocol’s share format. Save DNS, routing, local listeners, and other outbounds separately.
2. Share link to JSON: Import the node into a client first so it can generate a runtime config using its current settings. If writing the config by hand, define the local inbound and default outbound behavior as well as the remote fields.
3. Link list to a Base64 subscription body: Join valid share links on separate lines, then Base64-encode the text as UTF-8. The result is a subscription body, not a remotely updateable subscription URL.
4. Base64 to full JSON: Decode the text and identify its contents, then convert each node individually. Putting the encoded text directly in outbounds doesn’t produce a valid core config.

Importing and migrating between clients: back up first, then test one node

Before converting anything manually, export or back up your current settings and keep the original subscription URL. Don’t overwrite a subscription group you’re actively using. Create a test group and import a few nodes to distinguish a format parsing error from a server connection failure. The menu names below describe common Chinese-language interfaces and may vary by client version.

After importing, open the node editor and compare the address, port, user identifier, transport, and TLS settings with the original. Then start the connection and check the logs. If the list looks fine but the handshake fails, check the connection details and server status. If there are no nodes, investigate the response body and import method before changing routing rules.

• Local connection: Apps using the system proxy or a manually configured proxy should connect to the address and port the client is actually listening on. The example 127.0.0.1:10808 isn’t a default for every installation.
• Remote connection: Connection timeouts, authentication failures, and TLS name mismatches are different problems. Use the logs to investigate each one separately; don’t change every field at once.
• Update behavior: A static node imported from the clipboard won’t necessarily update when the original subscription URL changes. To get automatic updates, save the subscription URL and its group.

Subscription conversion FAQs: decoding doesn’t guarantee a connection

Follow this order: verify that you received the right response body, identify the encoding layers, check the node fields, then verify the target core and local traffic entry point. Subscriptions, share links, and native JSON each serve a different purpose. Manual conversion is safer when you know what each step preserves and discards, rather than mixing up connection issues with config issues. For related concepts, see the Glossary. For routing and core settings, see Advanced configuration.