V2Ray for All Platforms Complete Setup Guide

01 · PREPARE

How to read this guide and prepare

How the quick tutorial and this handbook differ

If your goal is simply to establish a connection as quickly as possible, start with the quick-start tutorial. It follows the basic flow of downloading a client, importing a subscription, selecting a node, and enabling the proxy, making it easy to follow the interface step by step on your first attempt. This handbook is intended for long-term use and reference: it explains not only where buttons are located, but also how system proxy and TUN modes work, why subscription updates fail, why desktop and mobile platforms need different background policies, and how to turn failure messages in logs into concrete checks. When you encounter platform permissions, routing conflicts, or mismatched node parameters, use the contents above to jump directly to the relevant section.

This guide covers only three clients. On desktop platforms, v2rayN is the preferred choice because it supports Windows, macOS, and Linux with a largely consistent interface and subscription workflow. On Android, v2rayNG is the default choice and uses the Xray core; choose v2flyNG when you need the V2Fly core. The client handles the graphical interface, configuration organization, and system network integration, while the core actually executes protocols and routing rules. Once this division is clear, troubleshooting becomes a matter of identifying whether the issue lies with the subscription, client permissions, core configuration, or local network—instead of repeatedly deleting and reinstalling everything.

Four things to prepare first

First, prepare a working subscription URL or the sharing content for an individual node. Subscription URLs are usually generated by the service provider; the client can only read the nodes and groups they contain and cannot restore an expired subscription. When copying, preserve the complete URL and do not include periods, spaces, or line breaks added by a messaging app. Second, verify the system clock. TLS handshakes and certificate validation depend on accurate time, and a significant date, time-zone, or minute offset can make every node fail at once. Enable automatic time and time-zone settings in the operating system, then sync once before configuring the client.

Third, identify the device architecture. Common Windows devices use x64; macOS requires distinguishing Apple Silicon from Intel; most recent Android phones use arm64, while the universal build is suitable when you cannot confirm the architecture. On Linux, choose deb or rpm according to the distribution in addition to selecting x64 or arm64. Fourth, keep a fallback way to access the internet directly. During initial setup, do not enable system proxy, TUN, and complex routing rules all at once. Import the subscription, select a node, and complete a basic connectivity test first, then add features layer by layer. This makes it clear which change caused a problem.

Establish a recoverable baseline first

Before configuring anything, record the current system proxy state, the subscription names already stored in the client, and the active routing mode. On desktop, fully exit other software that modifies the system proxy or virtual-interface routes. On mobile, check whether the system already has an active VPN connection. Letting multiple tools control the system proxy or default route at the same time often sends requests back through the local machine, creates confusing DNS paths, or shows a connected status while applications remain inaccessible. After the basic connection works, restore only the software you actually need, one item at a time.

Subscriptions and nodes typically contain fields such as the server address, port, user identifier, protocol, transport, TLS settings, and server name. These fields must match the server configuration; do not guess from a node name or change settings arbitrarily in search of a “faster” option. VMess, VLESS, Trojan, and REALITY represent different configuration combinations, and there is no universally best protocol for every route. The safest approach is to import the configuration exactly as provided, changing only local client settings such as proxy mode, routing rules, log level, and subscription update frequency.

Basic download and permission principles

Client downloads are available from the download center. The download page lists the appropriate installation format for each platform and explains architecture choices. This handbook does not lock in a specific version number because interface details change as clients are updated, but the core sequence remains stable: install or extract, launch the client, create a subscription group, update the subscription, select a node, start the core, and enable system integration. When the system asks for permission for a network extension, firewall access, or VPN connection, read what is being requested and why before approving it. If a required permission was denied, allow it again in system settings rather than repeatedly clicking Connect.

02 · WINDOWS

Windows: installing v2rayN and configuring the system proxy

Choose the desktop or classic WPF edition

v2rayN is the recommended client for Windows. The download page offers a desktop edition and a classic WPF edition. The desktop edition uses a newer cross-platform interface and suits users who want similar workflows across desktop systems; the WPF edition is the long-established Windows interface, with menus closer to many existing tutorials. Both support subscription management, node switching, system proxy, routing, and log viewing. Choose one rather than running both at the same time, since they may compete for system proxy settings and local listening ports.

After choosing an installation format, close any older client that is still running. For an installer, follow the system prompts. For an extracted package, fully extract it to a directory where the regular user has read and write access; do not launch it from a compressed-file preview window. Keep the path simple and avoid locations that are frequently synchronized, cleaned, or subject to execution restrictions. On the first launch, Windows Firewall may ask whether network communication is allowed. Grant access according to your needs and only on trusted networks; ordinary single-device use usually does not require inbound access from public networks.

Create a subscription group and update it

Open subscription group or subscription settings, add a group name, and paste the complete subscription URL into the address field. The group name is only for local identification and can describe its purpose; it does not change the remote subscription. Save it, then run “Update current subscription” or the equivalent update command. Normally, new entries will appear in the node list. If nothing changes, check the status bar and logs first instead of clicking repeatedly. The returned HTTP status, certificate error, or timeout usually explains the problem better than a short message in the interface.

After the update succeeds, select a node as the active server and start the service. For the first test, do not immediately measure every node: batch tests create many connections at once and can be affected by the local firewall, network fluctuations, and the target site's response. A safer sequence is to choose one complete configuration, enable the system proxy, and visit two different sites in a browser. Once the basic connection works, run latency tests or switch nodes individually. Latency reflects only a brief link condition at test time and does not equal sustained throughput.

How to choose a system proxy mode

After v2rayN starts the core, it usually listens on local HTTP and SOCKS ports, but a listening port alone does not make every program use it. When “Automatically configure system proxy” is enabled, browsers and desktop software that follow system proxy settings send requests to the client. If you clear the system proxy, the core may continue running, but system applications will no longer forward traffic automatically. During troubleshooting, distinguish between “the core is running” and “the system proxy is active” so that a tray icon is not mistaken for proxy coverage across all programs.

Some programs have their own proxy settings and ignore the Windows system proxy. In that case, enter the local HTTP or SOCKS address shown by v2rayN in the program. The host is usually the loopback address, and the port must match the client's current settings. Do not copy a port from another device or enter the remote server port as the local proxy port. If a program supports both the system proxy and a manual proxy, keep only one path enabled to prevent duplicate forwarding.

TUN mode and administrator permissions

Consider TUN when you need to handle traffic from programs that do not read system proxy settings, command-line tools, or some games. TUN uses a virtual network interface and routing rules, so its coverage is generally broader than the system proxy and more sensitive to permissions, DNS, and other virtual adapters. The first activation may require administrator permission or installation of a network component. After enabling it, test a browser and common applications first, then check whether LAN devices, corporate network clients, and virtual-machine networking are affected.

If enabling TUN cuts off internet access across the system, disable TUN first and confirm whether the ordinary system proxy still works. Then check for conflicts with other VPNs, virtual-machine bridges, container networks, or security-software drivers. Do not change MTU, DNS, routing rules, and node parameters at the same time while the system is unstable; change one item per test. Before quitting v2rayN, clear the system proxy or use the client's normal exit command to reduce the chance of leaving the system pointed at a closed local port.

netsh winhttp show proxy
ipconfig /flushdns
nslookup example.com

Windows-specific issues

If a browser works but Store apps or command-line tools do not, different programs are probably reading different proxy sources. Use the command above to check WinHTTP status, then inspect the program's own proxy settings. If all webpages stop loading after the client exits, open Windows proxy settings and disable the manual proxy, or restart v2rayN and clear the system proxy. If antivirus or security software blocks the core process, use the path shown in its logs to inspect the rule instead of repeatedly reinstalling to hide a permissions problem. Find more common errors by symptom in Troubleshooting.

03 · MACOS

macOS: installing v2rayN, permissions, and network integration

Confirm the chip architecture and install the client

When using v2rayN on macOS, first confirm the chip type in “About This Mac” or System Information. Choose an arm64 package for Apple Silicon and an x64 package for Intel devices. A mismatched architecture may prevent the app from opening, trigger an unsupported-app warning, or cause unusual resource usage under a compatibility layer. After downloading, place the app in the Applications folder according to the package format, then launch it from there. Avoid running it long-term from Downloads or a mounted disk image, where updates, permissions, and configuration storage may behave inconsistently.

The first launch may show prompts about the app's source, network access, or background items. Find the app in System Settings and grant the required permissions explicitly. If no window appears, check the Dock, menu bar, and Activity Monitor to see whether it is already running in the background. Starting multiple instances can occupy the same local port. If macOS blocks the app, use the system's confirmation option for that individual app rather than weakening global security settings.

Import a subscription and establish a basic connection

Open subscription group management, add a name and subscription URL, save it, and run an update. macOS and Windows can use the same subscription content, but local client settings are not shared automatically. System proxy state, TUN permissions, LAN bypass rules, and log levels must be configured separately. Once the nodes appear, select one as active, start the core, and then enable the system proxy. For browser testing, open a new window to avoid old connections, cached DNS, or existing HTTP/3 sessions affecting the result.

If a subscription update reports that the domain cannot be resolved, first confirm that system DNS works while the client is not taking over network traffic. If it reports a certificate or handshake failure, check the system time, subscription URL, and current network. If only the subscription update fails while already imported nodes still connect, the subscription request path and node connection path are separate issues. Keep the working node in use while investigating the subscription service independently; there is no need to delete a valid configuration.

System proxy and application differences

After enabling the system proxy, most browsers and applications that follow macOS network settings will use the local proxy provided by the client. Whether terminal commands follow the system proxy depends on each command-line tool. Some read environment variables, some read system network settings, and others require explicit parameters. Do not assume that all terminal traffic follows the same path just because the browser works. To set a temporary proxy for the current terminal session, use the actual port displayed in the client.

export HTTP_PROXY=http://127.0.0.1:HTTP port shown by the client
export HTTPS_PROXY=http://127.0.0.1:HTTP port shown by the client
export ALL_PROXY=socks5://127.0.0.1:SOCKS port shown by the client

scutil --proxy
dscacheutil -flushcache

Replace the Chinese port description in the examples above with the numeric port currently shown by v2rayN; the setting applies only to the current terminal session. When it is no longer needed, close the terminal window or use unset HTTP_PROXY HTTPS_PROXY ALL_PROXY to clear the variables. Do not permanently add temporary variables to every terminal startup file unless you understand what commands will do when the client is not running. A system proxy and terminal environment variables can coexist, but having both increases the number of paths to check.

TUN and network-extension permissions

TUN mode requires deeper network integration. The first activation may trigger a network extension, VPN configuration, or system-password prompt. After granting permission, return to the client and confirm that its status actually changes to enabled rather than assuming it worked because the system prompt disappeared. If multiple network filters or enterprise-management profiles are present, TUN may fail to initialize, disconnect immediately, or alter LAN access. Close other network-integration tools first, then restart the client and test again.

After switching between Wi-Fi, wired networking, and a hotspot, old routing and DNS state may linger briefly. If every node fails just after a network change, wait for the system to finish obtaining an address, then stop and restart the client core. If the problem persists, disable TUN, refresh DNS, and verify basic connectivity in system-proxy mode. If the system proxy works but TUN does not, focus on permissions, virtual interfaces, and routing conflicts rather than changing the remote node first.

Sleep, the menu bar, and recovery after quitting

After a laptop wakes from a long sleep, existing TCP connections, network interfaces, and DNS upstreams may have changed. A client that still appears to be running does not mean old connections can be reused. Disconnect and reconnect once, then test a new request. If the app window closes while the client remains in the menu bar, that is normal for desktop clients; use the app menu's Quit command to exit completely. Clear the system proxy before fully quitting to prevent traffic from being sent to a closed local port.

If LAN printing, file sharing, or discovery of development devices is affected, check whether routing rules are sending private addresses through the proxy. Common private ranges and local domains should remain direct according to the actual network. Do not copy an unfamiliar full routing set, because corporate, home, and development networks do not always use the same private ranges. Record the address of an inaccessible device first, then add a precise direct rule; this is usually easier to verify than allowing all traffic through one path.

04 · ANDROID

Android: configuring v2rayNG and v2flyNG

Choose the client and package

On Android, v2rayNG is the default choice and uses the Xray core, making it suitable for most common subscriptions and protocol configurations. Choose v2flyNG when you need the V2Fly core. The two clients have similar basic workflows, but their configuration databases, core capabilities, and some menus differ, so do not keep both connected at the same time. Most recent phones use arm64 packages; if you cannot confirm the architecture or the arm64 package will not install, return to the Android downloads section and choose the universal build.

Before installation, Android may ask you to allow the current browser or file manager to install apps. Disable this temporary permission after installation. When opening the client for the first time, do not grant every background permission immediately. Import the subscription and establish a basic connection first, then adjust battery settings one by one according to the device's policies. This helps distinguish configuration errors from background restrictions. When migrating from an older version, confirm that existing settings are still visible before deciding to import again, preventing duplicate nodes and groups from complicating selection.

Import subscriptions, shared links, and QR codes

Open subscription group settings from the client menu, create a group, and paste the complete subscription URL. Save it, return to the main screen, and update the subscription. If the source provides a single sharing link, import it from the clipboard. Use a QR code only when its source is clear, and check that the imported address, port, protocol, and server name are complete. Camera scanning only enters the content; it does not determine whether a configuration has expired or repair missing fields.

When the node list appears, tap a node to make it the active configuration, then tap Connect. Android displays a system VPN connection request because the client needs to create a local virtual network interface. After approval, a VPN indicator usually appears in the status bar. Test a browser first, followed by commonly used apps. If the connection quickly returns to a disconnected state, open the logs immediately. They usually identify the specific cause, such as configuration parsing failure, a port conflict, interrupted permission, or core startup failure.

Per-app proxy and routing modes

On mobile, app traffic generally enters the client through the system VPN interface. To proxy only selected apps, enable per-app proxying and choose include or exclude mode. Include mode sends only selected apps through the client; exclude mode bypasses the client for the selected apps. After changing the app list, disconnect and reconnect so the system can rebuild the routes. System components, embedded browser pages, and external services called by an app may run in different processes, so verify per-app behavior with actual tests.

The routing mode determines whether requests entering the client use the proxy, connect directly, or are blocked. For the first connection, use the client's basic rules and do not import multiple rule sets from unknown sources at once. If an app opens its home page but images or login fail, it may use several domains while the rules cover only some requests. Find the failed domain in the logs, then decide whether to route it through the proxy or directly. Assigning the entire app to one path is quick but makes the rules harder to understand.

Background operation and battery policies

Background restrictions vary widely between phone systems. Typical symptoms include a connection dropping after a few minutes of screen lock, recovering as soon as the app is reopened, or losing the VPN indicator after the system clears background apps. Check battery optimization, background activity, auto-start, and locking the app in recent tasks in that order. Change only settings related to the current client; there is no need to disable the device's entire power-saving system. Subscription updates should not run too frequently either, since repeated wakeups, large group updates, and speed tests on mobile networks consume additional battery and data.

For background battery usage, read Troubleshooting v2rayNG battery usage and power-saving settings. Start by checking the system battery statistics and distinguish foreground screen use, the client's own activity, and network activity generated by proxied apps. A client continuously showing the VPN service does not necessarily indicate abnormal battery drain; repeated retries, verbose logs, frequent subscription updates, granular routing rules, and unstable network signal can all increase wakeups.

Android-specific issues

If only certain apps fail after connecting, check the per-app proxy list and Private DNS settings first. When Private DNS uses a specific hostname, it can produce different results in combination with the client's DNS routing; temporarily switch it to Automatic for diagnosis. If the connection drops when switching between Wi-Fi and mobile data, reconnect manually after the system finishes switching networks. If it never recovers, disconnect the system VPN, force-stop the client, and open it again. Do not switch repeatedly between v2rayNG and v2flyNG while connected.

If importing a configuration reports a format error, copy it again from the source instead of manually deleting characters that appear unnecessary. REALITY, TLS, transport paths, and server names are interdependent; one inconsistent field can cause a handshake failure. If every node times out, check the current network, system time, subscription validity, and DNS first. If only one node fails, compare its parameters with other nodes in the same group. Checking from broad conditions to specific parameters is more effective than repeatedly changing cores.

05 · LINUX

Linux: installing v2rayN, desktop proxy, and TUN

Choose deb, rpm, and the processor architecture

Use v2rayN on Linux desktops. Debian, Ubuntu, and common derivatives generally use deb packages; distributions such as Fedora, Rocky Linux, and openSUSE that use rpm-based package management can use rpm packages. Select x64 or arm64 according to the processor as well. The distribution name alone does not determine the architecture, especially on development boards, mini PCs, and cloud desktops. Run uname -m in a terminal: the common x86_64 value corresponds to x64, while aarch64 corresponds to arm64.

With a graphical software installer, double-click the package and confirm its dependencies. From the command line, run a local installation against the actual file in the download directory. Package managers can resolve dependencies and are usually safer than invoking low-level installation commands directly. The filenames in the commands below illustrate the operation; use the actual filename provided on the download page when executing them.

uname -m

cd ~/Downloads
sudo apt install ./v2rayN-linux-x64.deb

sudo dnf install ./v2rayN-linux-x64.rpm

Do not repeatedly install packages for different architectures on the same device. If the package manager reports missing dependencies, refresh the distribution's software sources and complete a normal system update before trying again. If the system version is no longer maintained, forcibly replacing system libraries may affect other desktop applications; upgrading to a supported distribution release is safer. After installation, launch v2rayN from the application menu and verify in the logs that the core and configuration directory can be read normally.

Subscription import and desktop-environment differences

The workflow for creating a subscription group, pasting its URL, updating nodes, and selecting an active server is the same as on other desktop platforms. Linux mainly differs in desktop proxy behavior: GNOME, KDE, lightweight desktops, and standalone window managers read proxy settings differently. Some apps use desktop settings, some read environment variables, and browsers may have their own proxy options. After enabling v2rayN's system proxy, test the browser, terminal, and each desktop program you need separately.

If the browser works but terminal commands connect directly, the command-line tool is not reading the desktop proxy. Set an HTTP, HTTPS, or SOCKS proxy for the current session according to that tool's documentation, using the port shown in v2rayN. If the client is not running, these environment variables point to an unoccupied local port, so do not blindly add them to every shell startup script. Servers and headless environments are outside this handbook's main scope; this page focuses on graphical clients and local desktop sessions.

TUN, permissions, and DNS

TUN mode creates a virtual interface and changes routes, usually requiring administrator authorization, system capabilities, or a network-management service. It can cover programs that do not read desktop proxy settings, but is also more vulnerable to conflicts with container networks, virtual-machine bridges, corporate VPNs, and custom firewall rules. For the first test, disable these extra network layers and confirm that v2rayN's TUN works by itself, then restore them one at a time. If interface creation fails, check permission details in the client and system logs rather than broadly weakening permissions on system directories.

On Linux, DNS may be managed by systemd-resolved, NetworkManager, a desktop network service, or a local resolver. If domain requests fail while direct access to a known address responds, inspect the resolution chain. Use resolvectl status to view current DNS upstreams and interface states, and resolvectl query example.com to test resolution. If the command is unavailable, use the equivalent tool for the network service used by the distribution. Record the original configuration before changing it so it can be restored after troubleshooting.

ip address
ip route
resolvectl status
resolvectl query example.com
ss -lntup

Port conflicts and session startup

If the client reports a port conflict when starting the core, use ss -lntup to find local listeners. Common causes include an old instance that did not exit, another proxy tool using the same port, or a leftover process restored in the background with the desktop session. First exit the old process normally, then restart the client; do not terminate unfamiliar system services. After changing a local port, update browsers, development tools, and environment variables that were configured with the old port.

If the client is configured to start at login, make sure it starts after the user's desktop network services and verify that the system proxy can recover after an abnormal exit. On a shared computer, do not store a personal subscription in a globally readable configuration directory. Configuration files and logs may contain server addresses, subscription request details, and runtime errors; keep them in the current user's directory and regularly remove old logs that are no longer needed. After troubleshooting, change the log level from Debug back to Info or Warning to reduce disk writes.

Checks after a distribution upgrade

A major system upgrade may change graphical libraries, network services, firewall backends, or kernel modules. If the system proxy still works but TUN fails afterward, reconfirm virtual-interface permissions and routing services. If the client cannot start, launch it once from a terminal and read any missing-library or display-service errors. Do not immediately blame the node when a desktop launcher does not respond. Repair the basic environment first, then check the subscription and connection. For long-term stability, record the proxy mode, DNS strategy, and custom routes that currently work, and verify them one by one after system updates.

06 · SUBSCRIPTION

Managing subscriptions, nodes, and protocol parameters

What a subscription is and what the client stores

A subscription is a set of configurations returned by a remote URL. After an update, the client saves its nodes in a local group. It is not a live connection channel and is not contacted for every network request. Node availability depends on the imported server address, port, user identifier, protocol, transport, encryption, and TLS parameters. When a subscription update fails, old nodes usually remain; whether they continue to work depends on the server, not on the update button itself.

Create groups by source or purpose instead of putting every URL under one name. Clear groups make it easier to update, delete, and review changes separately, and to determine whether simultaneous failures come from the same subscription. When replacing a subscription URL, add the new one and update it successfully before deleting the old group, so a copying mistake does not leave you without a usable configuration. If the client offers an option to remove old nodes during an update, first determine whether it replaces one group or deletes nodes globally.

A fixed checklist for failed updates

First confirm ordinary network access and the system clock. Second, copy the complete URL again. Third, inspect the status in the subscription request log. Fourth, disable the system proxy in the current client or switch the path used for subscription updates, then retry. Fifth, confirm whether the source requires additional authentication. Do not change the node protocol first: subscription requests are usually ordinary HTTPS requests and are separate from the VMess, VLESS, or Trojan parameters inside a node. See installation and setup questions for the complete process.

If the log shows a timeout, check DNS, the current network, and whether the subscription service is reachable. If it reports an invalid certificate time, sync the system clock first. If it reports unauthorized or access denied, return to the subscription source and confirm the URL and status. If the response cannot be parsed, you may have copied a webpage URL, login URL, or content truncated by an intermediate app. Rapid repeated retries can trigger service limits and make the logs difficult to read. Change one item at a time, run one update, and record the result.

How node fields relate to one another

A complete node usually includes an address, port, user identifier, protocol, security method, transport type, TLS settings, server name, and path. Matching protocol names do not mean configurations are interchangeable. For example, two VLESS nodes may differ in TLS, REALITY, WebSocket, gRPC, or another transport, which determines the required fields that follow. The server name may be used for certificate or handshake validation, while the path may identify a particular service entry point. When editing manually, use the parameters supplied by the source and do not combine seemingly valid fields from another node.

VMess, VLESS, Trojan, and REALITY

Choose a protocol according to the server configuration and subscription content. VMess includes its own user authentication and security parameters. VLESS has a lighter configuration and is often combined with TLS or REALITY. Trojan authentication and TLS settings must match the server. REALITY usually appears as part of a specific handshake combination; it is not a universal acceleration switch that works when enabled on any node. Client support for a protocol means it can parse and run that protocol, not that every server will accept the configuration.

When importing from a subscription, preserve the fields as provided whenever possible. Edit an item manually only when you know the server configuration has changed. When a connection fails, compare working and failed nodes in the same subscription. If they all use the same domain but different ports, focus on the port and remote service status. If only one transport fails, check the path, service name, and TLS. If all TLS nodes fail at once, check the time and network environment. For more on core relationships and protocol support boundaries, read Xray and V2Fly core differences.

Speed tests, sorting, and update frequency

Node testing can cover basic reachability, connection latency, and actual download performance. Reachability asks whether a request can be established; latency reflects round-trip time to the test target at that moment; download performance is more affected by line load, the target site, and the local network. Do not sort nodes permanently based on one latency result or run frequent batch tests on a mobile network. A more practical approach is to keep several nodes verified through real-world access and switch between them by group when conditions change.

The right automatic subscription-update interval depends on how quickly the source changes and how the device is used. A desktop that stays on can use a reasonable schedule, while mobile devices require more consideration of background wakeups and data usage. If an update removes the current node, the client may keep the old configuration until the next restart or immediately ask you to choose another, depending on the implementation. Before important work, manually update and verify one node; this is more controllable than frequent automatic changes during use.

07 · ROUTING

System proxy, TUN, DNS, and traffic routing

Keep the four layers separate

Understanding the traffic path is the foundation of routing configuration. The first layer is whether the application sends requests to the client: a browser may read the system proxy, a terminal tool may read environment variables, and Android apps usually enter through the system VPN interface. The second layer is the client's local entry point, such as HTTP, SOCKS, or TUN. The third layer is the routing rule that chooses proxy, direct, or block. Only the fourth layer selects the remote node and protocol. When a webpage fails, inspect these four layers in order instead of immediately assuming the node is unusable.

The system proxy suits applications that follow the operating system's proxy settings; it is simple to configure and has a clear scope. TUN covers more traffic, including programs without proxy options, but changes routing and DNS paths and is more likely to conflict with other virtual networks. A manual proxy is useful when only a particular development tool or browser should use the client. These methods can be combined in specific scenarios, but initial setup should use one primary integration method. Otherwise, the same request may be forwarded twice or different applications may take completely different paths.

Direct, proxy, and block rules

Routing rules commonly match domains, IPs, ports, network types, or application processes. They are evaluated from top to bottom or according to the priority defined by the client; the first clear match often determines where traffic goes. Direct routing suits LAN devices, printers, gateways, and services that should clearly use the local network. Proxy routing sends requests through the current node, while block rules reject specific domains or protocols. The rules should ultimately define a default outbound path so unmatched traffic behaves predictably.

{
  "type": "field",
  "domain": [
    "domain:intranet.example",
    "full:printer.lan"
  ],
  "outboundTag": "direct"
}

The structure above illustrates the basic meaning of routing a domain directly. Use the actual location and tag names provided by the client's routing editor. domain: usually matches a specified domain and its applicable scope, while full: is used for exact-name matching. Rule syntax depends on the current core version and how the client generates configuration, so do not replace an existing file with the entire block. When the graphical interface can generate rules, add and verify them there to reduce JSON nesting and tag-spelling errors.

LANs, private addresses, and sharing

Home gateways, network storage, printers, and development devices usually use private addresses. If these devices become unreachable after enabling a global proxy or TUN, check whether private addresses are being sent to the remote server by mistake. Common ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16, though real networks may also use local domains or other internal ranges. After adding direct rules, test address access, domain access, and device discovery separately because broadcast and unicast behave differently.

Allowing LAN devices to use the local proxy is a separate feature that makes the client listen on more than the loopback address. Before enabling it, confirm that the current network is trusted and configure the firewall to allow only necessary subnets and ports. The local proxy port shown by the client is not the remote node port. On another device, enter the LAN address of the computer running the client and its local listening port. Sharing naturally stops when the computer sleeps, its address changes, or the client exits, so it is not suitable as an unattended long-term gateway.

DNS paths and misleading leak assumptions

DNS resolves a domain to an address, after which routing handles the connection. Depending on the client and core configuration, domain rules may match before resolution or may require the resolved address. Common issues include domains failing while direct addresses work, domains resolving to results unsuitable for the current network, DNS timeouts after enabling TUN, and system caches retaining records from before a network change. During troubleshooting, test resolution with system tools first, then inspect the client's DNS logs; do not replace several public DNS services at once.

A browser may enable Secure DNS and bypass parts of the system resolution path. If system commands and browser results differ, check the browser's network settings. Android Private DNS, macOS network services, the Windows cache, and Linux local resolvers can also create separate layers. To isolate the issue, temporarily restore automatic system DNS and disable the browser's independent resolver, then test the client's default configuration. Once the basic path works, restore custom settings one at a time.

TUN MTU, virtual adapters, and conflicts

TUN receives traffic through a virtual interface. Some networks are sensitive to packet size, fragmentation, and UDP paths, which can make ordinary webpages work while large files, video, or a specific app stalls. MTU may be a factor, but do not change it to an extreme value without evidence. First confirm that the problem occurs only with TUN, then compare it with system-proxy mode. If it happens only on a particular network, record the network type, failed app, and timeout stage in the logs before making a small, targeted adjustment.

Virtual machines, containers, corporate VPNs, game-acceleration tools, and security filters may all create virtual interfaces or modify routes. The most effective response is a single-variable setup: leave only v2rayN or the Android client's integration active, confirm that it works, then enable other software one at a time. After each change, test DNS, the browser, LAN access, and the target app. This identifies the component competing for the default route or DNS instead of enabling multiple tools at startup and waiting for intermittent failures.

08 · TROUBLESHOOTING

Connection failures, log reading, and routine maintenance

Classify the issue by scope first

The first troubleshooting step is not switching nodes but determining the scope. If every node and application fails, check the local network, system time, client core, DNS, and subscription status first. If only one node fails, focus on its address, port, and protocol parameters. If only one app fails, check whether it reads the system proxy, is excluded by per-app rules, or uses its own DNS. If failure occurs only with TUN enabled, prioritize permissions, virtual interfaces, and routing conflicts. Correct scope classification greatly reduces the number of checks.

Next, establish a comparison. Disable TUN and test with the system proxy; clear custom routes and test with the client's basic rules; keep one known-working node from the same group and compare it with the failed node; switch from Wi-Fi to another working network and record the result instead of simply saying “it still doesn't work.” Comparison testing identifies the failing layer. See the node timeout troubleshooting guide for a detailed fixed order.

Log levels and keywords

For normal use, Info or Warning is sufficient. When troubleshooting, temporarily switch to Debug, reproduce the problem once, save the relevant lines, and restore the previous level immediately. Start reading a few seconds before clicking Connect or sending the request; do not capture only the last line. Earlier configuration loading, DNS queries, and connection targets often explain a later timeout or rejected message. Logs may contain server addresses, domains, and local paths, so remove personal subscription URLs and identifiable information before sharing them.

timeout is not itself the cause; it only means that one step stopped waiting. Check the destination address, network type, and stage immediately before it. A timeout before resolution points to DNS; a TCP connection timeout points to the network or port; a handshake timeout points to protocol or TLS parameters. rejected may come from a routing block, remote refusal, or local policy and must be interpreted in context. See how to read v2rayN runtime logs for more examples.

Connected, but webpages will not open

A connected status only means that the core or virtual interface has started; it does not prove that the target request succeeded. Confirm that the system proxy or TUN is actually enabled, then check whether the browser has an independent proxy setting. Try a previously unopened ordinary page to rule out old caches and existing connections. Test DNS next: if domains fail while other requests work, focus on resolution; if every request times out, check the current node, default routing path, and local firewall.

When only some webpages fail, check which outbound path their domains use in the logs. A webpage commonly requests the main domain, static assets, login APIs, and image domains, and rules may send them along different paths. Temporarily switching to simpler basic routing can confirm whether traffic splitting is responsible. If basic routing works, restore custom rules one at a time. Do not disable all system security components for testing; identify the specific blocked process, port, or interface instead.

Network loss and leftover proxy settings after exit

After a desktop client exits abnormally, the system proxy may still point to a local port whose core has stopped listening. As a result, every application that follows the system proxy loses internet access. Restart the client and clear the system proxy normally, or open the operating system's network settings and disable the manual proxy. On Windows, distinguish the user system proxy from WinHTTP. On macOS, confirm the setting in system network settings; on Linux, check both desktop proxy settings and terminal environment variables.

If routes do not recover promptly after TUN ends abnormally, restart the network connection or device and check whether the virtual interface still exists. Manually remove a route only when you understand where it came from, so you do not delete a valid gateway. On mobile, disconnect the active connection from system VPN settings, then force-stop the client. After ordinary networking returns, reopen the client and verify it; do not import subscriptions while the system still has abnormal routes.

Configuration backups and update maintenance

For long-term use, back up the configuration export provided by the client or record the subscription source, but do not place files containing personal subscription URLs in public locations. When changing devices, reinstall the client on the new device and import the subscription first, then configure the system proxy, TUN, and routing according to this handbook. Copying the entire old configuration directory may carry over old ports, paths, caches, and settings unsuitable for the new platform. After migration, verify subscription updates, node connections, DNS, LAN access, and commonly used apps one by one.

Before updating the client, exit it normally and record the key settings that currently work. After updating, do not change routing and nodes at the same time. First confirm that the original subscription can be read, the core can start, and the system proxy works, then test TUN. If the new interface moves menu items, search by function name instead of relying on fixed screenshots. The core workflow of v2rayN, v2rayNG, and v2flyNG remains centered on groups, nodes, cores, routing, and logs.

A repeatable final troubleshooting sequence

When a connection fails, follow this order: confirm that the device can access the internet normally without the client; sync the system time; close other network-integration tools; check whether the subscription updates; choose a known-complete node; enable only the system proxy or basic mobile connection; send a new browser request; read the complete log from startup through the failed request; check DNS, port, protocol, or permissions according to the failure stage; only then restore TUN, custom routing, and background automation. Record the result after every step.

If the issue remains unresolved, note the operating system, client name, integration method, scope, log keywords, and checks already completed, then compare by category on the Troubleshooting page. Clearly stating “which platform, which mode, all or one node, all or one app” is more useful than providing only a screenshot of a failed connection. The goal of systematic troubleshooting is not to try many settings at once, but to eliminate one layer at a time and leave a configuration that can be verified and restored.