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

1. How subscription URLs, Base64, and JSON differ

“V2Ray subscription” does not refer to one specific file format. The HTTPS URL you receive is just the access point; the client fetches the actual response from it. That response may be a list of share links, one per line, or text containing the entire list encoded in Base64. Some services return different content depending on the request headers, so the URL suffix alone does not tell you the format.

Just because two items are JSON does not mean they are interchangeable. A VMess share object describes one server and its transport settings; an Xray config tells the core how to listen on local ports, create outbound connections, and apply routing. Saving the former as config.json does not turn it into the latter. Base64-encoding the entire config does not make it a subscription a client can use either.

2. VMess and VLESS share link fields

A common VMess share link consists of vmess:// followed by Base64-encoded JSON. The example below shows only the decoded JSON. All domains and UUIDs are fictional and for illustration only; they cannot be used to connect. v: "2" identifies the share object format, not the client or core version.

{
  "v": "2",
  "ps": "Example 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 is the server address, port is the remote port, and id is the user ID. net, host, and path specify the transport and WebSocket request settings. aid: "0" corresponds to the common VMess AEAD configuration in use today; do not change it to an arbitrary value just to silence an error. The example’s type: "none" is not a switch for disabling TLS.

VLESS share links usually use a URI format. The identity goes before @, the server and port follow it, and transport settings go in the query string. This example is also nonfunctional; keep the link on a single, complete line:

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

URI parameter values must be encoded according to URL rules. For example, the path /ws?ed=2048 used as a parameter value should be written as path=%2Fws%3Fed%3D2048, so its question mark is not mistaken for the start of another query string. Encode notes containing non-ASCII characters, spaces, or special symbols correctly too. Do not percent-encode the entire URI at once, or the protocol prefix and separators will be corrupted.

3. Decode and re-encode Base64 subscriptions locally

A typical conversion is “multiple share links → join with line breaks → Base64-encode the entire text.” If the list contains VMess links, there are two encoding layers: the outer layer wraps the list, and the inner layer wraps each VMess JSON object. Once decoding the outer layer reveals vmess://, split the text by line instead of treating the entire result, protocol prefixes included, as Base64 again.

Run the following plain JavaScript in the developer console of a local blank page. Read the code first, and put your own data only in local variables; it makes no network requests. The encoder uses UTF-8 to avoid errors when Chinese notes are passed directly to btoa(). The decoder handles both standard Base64 and common URL-safe variants.

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("The content is not a valid Base64 character sequence");
  }

  encoded = encoded.replace(/=+$/, "");
  if (encoded.length % 4 === 1) {
    throw new Error("Invalid Base64 length; check that the content was copied in full");
  }

  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));

• Turn a list into a subscription body: Join the links with links.join("\n") to create one link per line, then pass the result to encodeSubscription(). Do not encode each line separately and concatenate the results.
• Turn a subscription body into a list: Decode it once, confirm the protocol prefixes, then split on line breaks and remove empty lines. If the result is still HTML or an error message, go back and troubleshoot how you retrieved it.
• Convert one VMess link to JSON: Remove the vmess:// prefix, decode the remaining content, then check its structure with JSON.parse().
• Convert VMess JSON to a share link: Run JSON.stringify() on the object, encode the resulting text, then add vmess:// at the beginning. This only applies to the corresponding share object format.

4. Import options in v2rayN and v2rayNG

Choose the import option based on what you have. Add a subscription URL to a subscription group, import one or more share links from the clipboard, and load a complete core JSON through a custom config option. Menu locations may vary by desktop and Android version. The labels below reflect common menu names; if they differ slightly, use the equivalent import function. Do not enter a subscription URL in the server address field.

v2rayN: Create a group, then update the subscription

1. Create a group

   In the main window, open “Subscription Group” → “Subscription Group Settings,” click “Add” to create a group, enter a label and subscription URL, then save and return to the server list.

2. Fetch the content

   From the “Subscription Group” menu, choose “Update Current Subscription (without proxy)” or the equivalent option to update through a proxy. Use the first option when your current network can reach the subscription service directly. The second requires a working proxy and a correctly configured proxy route.

3. Import links

   If you only have share link text, copy the complete links and choose “Servers” → “Import batch URLs from clipboard.” On common desktop versions, you can also use Ctrl+V. This adds a snapshot of the nodes; it does not create a link for future subscription updates.

4. Check the settings

   Open each imported entry for editing and check the server address, port, transport protocol, TLS, and SNI. Seeing an entry in the list is not enough: start it and check the core log at the bottom for config parsing errors.

v2rayNG: Handle subscriptions and clipboard imports separately

• Subscription URL: Open “Subscription Group Settings” from the main menu, tap “+” to enter a label and URL, then save and return to the main screen. Open the menu and select “Update subscription.”
• Share links: Copy the complete text, tap “+” on the main screen → “Import from clipboard,” check the new entry’s transport and security settings, then select it to start the connection.
• Native JSON: Use the custom config import option in the “+” menu, then choose a file or clipboard as the source. Do not assume the standard share link import can handle arbitrary JSON.
• Core compatibility: v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. A link recognized by one client does not guarantee that every extended parameter will work with the other core. Pay particular attention to Reality and Flow settings.

If you decode a subscription and import the links manually, later changes to server addresses, ports, or credentials on the server will not automatically update your local snapshot. To keep receiving updates, retain the original subscription group. When migrating, back up the subscription URL and local custom settings separately instead of saving only a list of share links.

5. Map share links to native Xray JSON

When a client generates a core config, it does more than rename fields: it also adds runtime details such as local inbounds, outbound tags, logs, and routing. Below, the VLESS TCP + TLS example from earlier is mapped to a minimal SOCKS config. It listens only on 127.0.0.1:10808; the remote host is still a fictional teaching domain, so this config is for understanding the structure only and will not connect.

{
  "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"
        }
      }
    }
  ]
}

The local port 10808 is the specific example value set here; do not assume every client listens on this port by default. Before running the config, make sure no other program is using it. Binding only to the loopback address prevents an unauthenticated SOCKS inbound from being exposed to your LAN. Do not change it to listen on all interfaces to troubleshoot a remote connection.

When exporting a full JSON config back to a share link, clients can usually extract only one compatible proxy outbound. The relationships among routing.rules, DNS, multiple inbounds, and multiple outbounds cannot be fully represented by a single-node share link. If the original config depends on these settings, keep the JSON; exporting a QR code does not complete a full migration.

• Usually preserved in both directions: Server address, port, UUID, and transport and TLS settings supported by both clients.
• Check separately: Client-specific settings, query parameters the importer does not recognize, fingerprints, and advanced transport options. The parser may ignore them without reporting an error.
• Back up separately: Subscription update links, routing rules, DNS policies, local ports, and client UI settings.

6. Troubleshoot empty imports, decode errors, and missing fields

Troubleshoot in stages: “fetch → decode → parse → run,” and record the result at each step. A successful subscription update only means the client processed something; generating entries, preserving all fields, starting the core, and reaching the remote server are separate checks. Fix the earliest failing step first. Changing TLS, ports, and the subscription URL all at once makes it harder to compare results.

7. Verify and back up after conversion

The safest migration does not rely on “one really long string,” but on three clearly defined items: the original subscription URL for future updates, share links for exchanging nodes, and a full config or client backup for restoring local behavior. Keep all three if needed, but do not treat them as interchangeable. Store backups containing credentials in a local location with access controls.

1. Keep the original: Save the original response or file before converting, so you are not left with only a result that has been processed multiple times.
2. Check one entry: Compare the protocol, address, port, and transport settings for a single node first. Make sure UUID, Host, and SNI have not been confused with one another.
3. Check startup: Enable the entry and review the core log. Resolve config parsing and port conflicts first, then troubleshoot certificates, handshakes, and remote connectivity.
4. Check the app: Desktop apps also need to use the system proxy or the specified local proxy port correctly. On Android, make sure the connection is running and grant the VPN permission requested by the system.
5. Test updates: If migration includes a subscription, manually update it once in the target client and confirm new entries appear in the intended group rather than only as a batch of static nodes.