V2Ray Configuration Guide: From Beginner to Advanced

Core concepts: clients, cores, protocols, and routing

Separate the graphical client from the proxy core

v2rayN, v2rayNG, and v2flyNG are primarily graphical clients. They store subscriptions, display nodes, generate configurations, launch the core, and switch the system proxy or virtual network interface into the correct state. The core called by the client actually performs protocol handshakes, encrypted transport, DNS queries, and route matching. v2rayN can use Xray or V2Fly-related cores on desktop platforms; v2rayNG primarily follows the Xray core; v2flyNG targets V2Fly core configurations. When the client is open but webpages do not load, do not check only whether the window exists. Also verify that the core started, the listening port is available, and system traffic is reaching that port.

Client configuration and node configuration are different layers. A node describes the remote address, port, user ID, protocol, transport, and security parameters; client settings also cover local listeners, the system proxy, DNS, routing, and logs. A subscription usually provides nodes and group information, but it does not determine every local network policy. After importing a subscription, you still need to select a proxy mode and, when necessary, configure LAN bypass, direct access for mainland China domains, remote DNS, or TUN. Keeping these layers separate explains why the same subscription may connect on different devices while producing different split-routing results.

Match protocol, transport, and security parameters as a set

VMess, VLESS, and Trojan belong to the node protocol layer; TCP, WebSocket, and gRPC belong to the transport layer; TLS and REALITY cover connection security and identity verification. Every parameter must match the server when the client connects. In a VLESS configuration, a correct address and port do not guarantee success: a mismatched user ID, flow control, transport type, service name, server name, public key, or short ID can appear as a failed handshake, an immediate disconnect, or a timed-out latency test.

Common REALITY node fields include the server name, fingerprint, public key, short ID, and flow control. The server name is not an arbitrary note; it participates in the handshake. The public key must come from the node provider, and the short ID must match the supplied value. When Vision flow control is used, the protocol, transport, and security combination must also remain consistent. Standard share links and subscriptions are usually parsed automatically by the client. Enter fields manually only when their source is clear; never combine parameters from another node with the current one.

Inbound, outbound, and routing form the traffic path

An inbound is where the client receives traffic locally, such as a local SOCKS port, HTTP port, or TUN virtual interface. An outbound describes how traffic is handled after leaving the client; common labels are proxy, direct, and block. Routing rules decide which outbound receives each request. When a browser uses the system proxy, its request first enters a local HTTP or SOCKS inbound, then routing chooses direct or proxy. With TUN enabled, more application traffic enters the core through a virtual interface, but the routing and outbound logic still applies.

Routing commonly matches domains, IP addresses, ports, network types, or process information. Rules are ordered, and the first matching rule runs, so correct rule content is not enough: its position must also be appropriate. LAN and reserved addresses should usually go direct first; explicitly blocked targets belong before direct rules; regional domain and IP rules belong before the proxy fallback. Finally, keep a predictable default outbound so unmatched traffic never falls into an ambiguous state.

Use observable results to identify the current layer

A successful connection test only shows that the client reached the target under specific test conditions; it does not cover every application. If a browser works but the command line does not, check whether the program reads the system proxy. If a domain fails while a known IP responds, check DNS first. If LAN devices suddenly become unreachable, check routing and TUN bypass rules. If every node fails at once, check the local network, system time, core startup, and subscription parameters before deleting nodes one by one.

Logs are the main evidence for identifying the failing layer. Startup logs show whether the configuration was accepted, whether a port is occupied, and whether the virtual interface was created. Connection logs show the domain, destination address, matching rule, and outbound label. Error logs help locate resolution failures, handshake failures, timeouts, and permission problems. Keep the log level at warning for daily use and switch temporarily to info during troubleshooting; restore it afterward to avoid accumulating large files. Logs may contain visited domains and node addresses, so remove unrelated connection details before sharing them.

Choose a client and install it

Choose the client based on platform and core requirements

For Windows, macOS, and Linux desktop environments, v2rayN is usually the best starting point. It brings subscriptions, nodes, the system proxy, routing, DNS, TUN, and logs into one interface, making it suitable for moving from basic connectivity to split routing and virtual-interface configuration. Windows users can choose between the desktop edition and the classic WPF edition: the desktop edition uses a cross-platform interface and suits users who want similar workflows across desktop systems; the classic WPF edition retains the traditional Windows layout and suits users familiar with its menus and tray behavior.

On Android, v2rayNG is the usual choice, with broad support for fields used by the Xray path; choose v2flyNG when a V2Fly core configuration is required. Both can import subscriptions, select nodes, establish local VPN interception, and display logs, but some setting names and entry points differ. When migrating, do not copy only the switch states from a screenshot. Export a standard node link or add the subscription again, then rebuild routing, DNS, and per-app policies one by one.

Check the architecture and existing configuration before installing

Before downloading, choose the correct platform on the client page. macOS requires an Apple Silicon or Intel build; most recent Android devices use arm64, while the universal build is safer when the architecture is unknown; Linux requires checking both the distribution package format and processor architecture. x64, arm64, deb, and rpm in the filename are selection criteria—do not rely on the app name alone. A mismatched architecture commonly causes the installer to refuse to run, the system to report an unsupported format, or the app to exit immediately after launch.

If an older client is already installed, record the current subscription URLs, groups, routing rules, DNS settings, and local ports first. If the client offers configuration backup, save it to a personal documents directory; for a portable configuration directory, fully exit the client and copy the entire directory. During an upgrade, do not change the client branch, core type, and main configuration simultaneously, or the source of a failure will be unclear. The safer order is to preserve the configuration, update the client, verify a basic connection, then update the core or adjust routing.

Complete the first launch on desktop

After installing on Windows, launch v2rayN and check the core status at the bottom of the window or in Settings. If the program appears only in the notification area, open the main window from the tray icon. When a system security prompt appears, grant access only for the network scope actually needed. Port conflicts commonly occur when an old instance is still running or another proxy program occupies the same listener. Exit duplicate programs first, then confirm in v2rayN's local listener settings that the SOCKS and HTTP ports are not in use by another process.

On first launch, macOS may ask you to confirm that the app can run, access the network, or change system proxy settings. After granting permission, verify connectivity with the regular system proxy before enabling TUN. If the Linux main window opens but no tray icon appears, check whether the desktop environment supports status icons; subscriptions and connections can still be managed from the main window. Also confirm that the current user can read and write the configuration directory, otherwise settings may not be saved when the client exits.

Complete the basic permissions on mobile

After installing v2rayNG or v2flyNG on Android, the first connection requests permission to establish a VPN connection. This allows the system to hand app traffic to the client. Approve it in the system dialog. If strict background restrictions are enabled, allow the client to run in the background; otherwise the core may be stopped after the screen locks. Dual-SIM setups, hotspot sharing, and work profiles can change network interfaces. If the connection drops after switching networks, stop it and start it again.

During initial installation, perform only three checks: the client opens normally, a subscription or single node can be saved, and the logs show no recurring startup errors after connecting. Do not import extensive custom rules or change every DNS option yet. Establish a reproducible basic connection with the default routing first, then add the system proxy, split routing, and TUN step by step. If you only need to make the first connection quickly, follow the concise steps in the Quick Start path.

Import subscriptions and manage nodes

Subscription links versus single-node links

A subscription link continuously retrieves a group of nodes and their updates; a single-node link represents one specific connection configuration. For long-term use, create a subscription group instead of converting subscription contents into many manually maintained nodes. A group preserves the update URL, notes, filters, and independent update policy, so changes to addresses, ports, or security parameters require only a subscription refresh. Manual nodes are useful for temporary tests or field verification, not as the primary way to maintain a large node list.

In v2rayN, open “Subscription groups,” add a group name and subscription URL, save it, then select “Update all subscriptions” or update the current group. The group name should describe its source or purpose rather than relying on the original node remarks. In v2rayNG and v2flyNG, the entry is usually under subscription settings or the side menu. After adding it, update first, then return to the node list and choose a target. When copying a subscription URL, make sure it has no leading or trailing spaces, line breaks, or explanatory text added by a chat app.

Check the request chain when subscription updates fail

A failed subscription update and a failed node connection are different problems. During an update, the client must access the subscription URL and parse its response; a node connection uses the resulting server parameters. If updates fail but existing nodes still connect, the current configuration may remain usable. Check that the subscription URL is complete, the system time is accurate, the current network can reach the subscription endpoint, and the group is not configured with an incorrect proxy. Do not delete the old group first, or you will lose both a working configuration and a comparison sample.

If the subscription must be fetched through the current proxy, first connect to a saved, working node and then enable a proxy for the subscription group. If the subscription endpoint is directly reachable from the local network, direct updates are easier to troubleshoot. When the response cannot be parsed, check whether the log shows an HTTP request failure, an unsupported content format, or an invalid field in a particular node. One node failing to parse does not necessarily make the whole subscription unusable; keep successful entries and ask the provider about the invalid fields.

Control list size with groups, notes, and filters

When multiple subscriptions are present, give each group a stable short name and keep searchable structure in node remarks, such as “Region | Route | Protocol.” Filters should affect display or update results, not modify node protocol fields. v2rayN can include or exclude nodes by keyword, which is useful for hiding duplicates or keeping only a certain protocol. Keep rules simple with one or two stable keywords; relying too heavily on temporary text in node names can make the list suddenly empty after a subscription renames its entries.

Automatic updates do not need a short interval. Subscription contents rarely change minute by minute, and frequent requests only add failure notices and list refreshes. Update at startup for everyday use, or choose a schedule based on the actual change rate. After an update, check whether the selected node still exists; if it was removed, choose a replacement manually. For a more complete grouping strategy, read Managing multiple v2rayN subscription groups.

Do not choose nodes based on a single test

A latency test quickly checks whether the client can complete a particular probe, but it does not equal real-world application quality. Different tests may measure TCP connection setup, an HTTP response, or the full connection process, so their results are not directly comparable. When choosing a node, confirm that its protocol fields are complete, run the client's connectivity test, and then verify it with the webpage or app you actually need. A single timeout may come from local network jitter, DNS, remote rate limiting, or a temporarily unreachable test target; test again and compare the logs.

When every node times out, choose one clearly configured node as a sample. Check whether the server address resolves, whether the port is blocked by the local network, whether the system clock is significantly off, and whether the core supports the node's parameters. If one node fails while others in the same group work, compare the actual protocol, transport, security, and other fields—not just the remarks. If all subscriptions fail at once, focus on the local network, core startup, and proxy loopback instead of changing user IDs one by one.

{
  "protocol": "vless",
  "settings": {
    "vnext": [
      {
        "address": "example.com",
        "port": 443,
        "users": [
          {
            "id": "11111111-1111-4111-8111-111111111111",
            "encryption": "none",
            "flow": "xtls-rprx-vision"
          }
        ]
      }
    ]
  }
}

The snippet above illustrates the field hierarchy of a VLESS outbound; the domain and user ID are example values. When using a real subscription, let the client generate the complete configuration from its contents. Do not overwrite an existing node with example fields. The purpose of viewing generated configuration is to confirm that the address, port, user ID, and flow control from the interface landed in the correct layer—not to turn the entire generated file into a permanently hand-maintained configuration.

Choose the system proxy and proxy mode

The system proxy connects applications that support proxy settings

After starting the core, v2rayN listens on local SOCKS and HTTP ports, but a listening port alone does not automatically capture every program. When “Configure system proxy automatically” is enabled, browsers and desktop apps that read the operating-system proxy settings send requests to v2rayN. When the system proxy is disabled, the core can continue running, and programs configured with the local proxy port manually can still use it. This distinction is useful when the client appears to be running but only some applications connect.

System proxy mode suits browsers, office software, and most applications that follow system settings. Its scope is clear, and it is easy to restore after the client exits. For command-line tools that ignore the system proxy, configure an HTTP or SOCKS proxy in the tool itself rather than switching to TUN immediately. Use a loopback address for the local proxy in most cases, and make sure the port matches the client's current listener. Do not mistake the remote node port for the local proxy port.

Global, rule-based, and direct modes represent different routing policies

“Global” generally sends all traffic entering the client through the current proxy outbound. It is useful for checking whether routing rules cause an access problem and for briefly testing the node itself. It is not required for everyday use because LAN services, printers, local development servers, or mainland China resources may also be sent through the proxy. “Rule” mode selects direct or proxy based on domains, IPs, and other conditions, making it the more common long-term setting. “Direct” sends requests entering the client straight to their destinations and can confirm whether the proxy path is causing the problem.

A consistent troubleshooting sequence helps: switch to Global and test the target; if Global works but Rule mode does not, inspect route matching; if Global also fails, inspect the node, DNS, and core. A working Direct mode does not prove that the node is healthy—it only shows that the local network can reach the target directly. Restore the original mode after testing and confirm in the logs that the target domain ultimately used the expected outbound label.

Define clear boundaries for PAC and system-proxy exceptions

Some desktop environments support PAC scripts that decide which requests enter the local proxy. PAC makes one choice before a request reaches the core, while client routing chooses the outbound again after the request enters the core. Combining them increases the mental overhead. For precise routing, it is usually clearer to point the system proxy uniformly at the client and let the core routing handle direct and proxy traffic. Use system-proxy exceptions or PAC only when certain programs or domains must stay completely outside the client.

Add LAN addresses to the bypass range, including common loopback addresses, private addresses, and local domains. This keeps router admin pages, LAN file services, and development environments from being sent through the proxy. A LAN service accessed by domain may still go through DNS first, so adding only an IP bypass will not help if resolution is wrong. Keep the record consistent in DNS hosts, the system hosts file, or the local name-resolution service.

Verify that traffic actually enters the client

Do not judge system proxy status only by whether a webpage opens. Open the client's connection log and visit a previously uncached domain, then check for a new connection record and its outbound. If the browser works but the log does not change, it may be using a browser-specific proxy, another network extension, or a cached connection. If the log shows the request but the outbound is direct, inspect routing; if it shows proxy followed by a handshake failure, return to the node parameters and remote connection layer.

In a command-line environment, test direct resolution, system-proxy handling, and an explicit proxy separately. Support for system-proxy environment variables varies by tool, so each test command must have a known path. Clear temporary environment variables afterward, or later terminal sessions may keep sending software updates or package-manager requests to a local port that is no longer open. The goal is not to force every program through the same entry point, but to make each application's path clear, observable, and recoverable.

Configure routing and DNS

Start with a minimal routing rule set

Common routing goals are direct access for LAN and private addresses, direct access for clearly identified mainland China domains and IPs, and proxy access for everything else. In v2rayN, start with a preset such as “Bypass mainland China,” then add custom domains based on actual use. Presets depend on GeoSite and GeoIP data: GeoSite matches domain collections, while GeoIP matches address ranges associated with destination IPs. Domain rules can choose a policy before resolution; IP rules usually require a resolved address first. Use them together rather than treating either as a replacement for the other.

A minimal rule set should handle private addresses first to keep LAN requests out of remote outbounds, then explicit block targets, then domains and IPs that should go direct, and finally a proxy fallback. More rules are not necessarily more accurate. Repeated domains, stale rules, and overlapping expressions make logs difficult to interpret. When adding a rule, start with one exact domain, verify the match, and only then expand it to a suffix or category tag.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:cn"],
        "outboundTag": "direct"
      }
    ]
  }
}

domainStrategy determines whether the client resolves a domain and tries IP rules when no domain rule matches. IPIfNonMatch means that the client resolves the IP only after the domain rules produce no result, which suits the common combination of GeoSite and GeoIP. If the strategy processes only an existing IP, some domain traffic may miss the expected IP rule; if every domain is resolved in advance, DNS becomes more involved. After changing the strategy, observe both resolution and routing logs.

Understand the matching scope of domain rules

An exact domain matches only the specified host; a domain suffix can cover its subdomains; keyword matching is broader and may include similarly named domains with different purposes. Prefer exact domains or clear category tags. Use suffixes only when the target's domain structure is stable and multiple subdomains genuinely need coverage. A content delivery network may call several domains for one service, so do not build rules from the main domain in the address bar alone; confirm the actual request set in the connection logs.

Routing depends on the domain visible to the client. If an application connects directly to an IP, domain rules cannot match; use IP, port, or process rules instead. With certain DNS-mapping mechanisms enabled, the core can restore the association between domains and connections, but DNS requests must then also be managed by the client. When the same website is sometimes direct and sometimes proxied, check different subdomains, IPv4 and IPv6 results, cached resolutions, and app-specific resolution paths.

Configure DNS and routing as one chain

DNS does more than translate a domain into an IP. It can affect whether routing matches and whether requests are influenced by local caches or resolution paths. A common setup sends mainland China domains to a local or mainland China resolver, sends other domains to a remote resolver, and routes remote DNS requests through the proxy outbound. This reduces mismatches between DNS results and the actual access path. Configure rules according to the DNS structure supported by the current core; do not create conflicting resolution policies in the system, browser, client, and multiple network tools at the same time.

When troubleshooting DNS, remove variables first: disable the browser's independent secure DNS and keep the client's DNS, or temporarily disable custom client DNS and test only system resolution. Keep one primary resolution path at a time. If a domain cannot be reached, check whether a query appears in the logs, which address was returned, and which route matched that address. If resolution succeeds but the connection fails, the problem has moved to the transport layer; if no query appears, the application may be bypassing the client's DNS.

Handle DNS leaks, caching, and IPv6 paths

With the system proxy, some applications may still call the system DNS directly, depending on how they resolve domains. To route all resolution requests through the client, use the client's remote DNS, DNS outbound, or TUN DNS interception. Verification can combine browser checks, system queries, and client logs; see v2rayN DNS Leak Testing and Fixes for detailed steps. Focus on the resolver and request path, not only the final returned IP.

Caching can make a change appear ineffective. The client, operating system, browser, and application may all retain DNS results. After changing rules, restart the relevant application or clear the corresponding cache, then create a connection to a new domain. When IPv6 is available, a domain may return both A and AAAA records; if the local IPv6 path is unstable, the application may prefer an address that fails. Confirm that the system has working IPv6 connectivity before deciding whether to keep, restrict, or route IPv6 separately. Do not hide a persistent network problem by deleting a DNS record.

Maintain GeoIP and GeoSite data

GeoIP and GeoSite data changes as address allocations and domains change. If split-routing results gradually drift while the rules themselves are unchanged, check that the data files can be read by the current core, that updates completed, and that custom files are not overriding the client-managed versions. Keep data files compatible with the core. After updating, restart the core and confirm in the logs that category tags load successfully.

Before manually replacing data files, exit the client and back up the originals so no file remains in use. If startup logs report a missing tag or invalid file format after replacement, restore the backup immediately instead of adding compensating rules. For exact locations, update entry points, and recovery steps, see GeoIP and GeoSite Data Update Guide. The routing database only provides classification; access logs must still confirm that the target reached the expected outbound.

Enable and calibrate TUN mode

Know when TUN is necessary

TUN mode receives IP traffic from the operating system through a virtual network interface. It suits applications that ignore system proxy settings, some command-line programs, and situations requiring unified interception. Its coverage is usually broader than the system proxy, so LAN traffic, software updates, background services, and other traffic that normally bypasses the proxy also enter routing. If you use only a browser and regular desktop applications, the system proxy is usually enough. Enable TUN after confirming that an application cannot be configured with a proxy on its own.

TUN does not improve node connectivity. If the node handshake fails, subscription fields are wrong, or the remote server is unreachable, enabling TUN will not fix the connection; it adds routing-table, DNS, and permission variables instead. Verify the node first in system-proxy mode, then enable TUN while keeping the same node and basic routes. If all access fails afterward, compare the logs and system routes before and after the switch instead of questioning the subscription again.

Check permissions, interfaces, and address ranges before enabling it

Creating a virtual network interface and changing routes usually requires system privileges. When v2rayN reports insufficient permissions, authorize it through the method provided by the client and operating system instead of repeatedly clicking Start. Other virtual-network tools can compete for interface routes, take over DNS twice, or repeatedly change the default route. During troubleshooting, exit other programs that modify system networking, keep only v2rayN running, and create the TUN interface again.

The virtual address range used by TUN must not overlap with the current LAN, corporate network, or another virtual interface. Overlap can make some addresses unreachable, disconnect LAN devices, or create request loops. Check existing local routes first, then choose the client's default range if it does not conflict. Windows users can inspect adapters and routes in the system network interface; macOS and Linux users can use their system network tools. Confirm that the default route, LAN range, and TUN range each point to the correct interface.

ip route
ip route get 1.1.1.1
resolvectl status

These Linux commands are used to view the routing table, confirm which interface a specified destination uses, and inspect the current DNS state. Other desktop systems should use their equivalent network tools. The results are mainly for comparing the system before and after enabling TUN: whether default traffic enters the virtual interface, whether LAN ranges remain direct through the physical interface, and whether DNS switches to the expected entry point.

Configure automatic routing, strict routing, and bypasses

Automatic routing creates system routes that direct traffic to TUN; start with the default values. Strict routing applies stronger limits to bypass traffic and is best tested only after basic TUN operation is confirmed. It can affect local services, virtual machines, containers, and LAN discovery, so create bypasses for private addresses and local interfaces first. Do not send every private address to the proxy outbound, or routers, printers, and local development services will become unreachable.

Process-based bypasses or inclusions can narrow TUN's scope, but process names, child processes, and system-service relationships must be verified in practice. An app may be launched by a separate launcher process or hand network requests to a system component. Adding only the main executable may not cover the complete request path. Start with ordinary routing rules; when per-app control is truly needed, add processes one by one while watching the logs, and keep a default outbound as a fallback.

Handle DNS and MTU under TUN

In a TUN setup, DNS is best handled centrally by the client so domains, mapped addresses, and actual connections remain associated. A common approach is to point system DNS at the client's local entry point, then let the core choose local or remote resolution according to domain rules. If the system also uses another DNS path, results may bypass the core, domain rules may not associate correctly, or tests may disagree. After switching to TUN, check the DNS state before testing webpages.

On some networks, webpages may begin loading while large files or specific requests stall, which may indicate an MTU problem. TUN encapsulation adds overhead, and some devices along the path may handle fragmentation poorly. During troubleshooting, lower the MTU gradually within the client's supported range, changing one setting at a time and retesting the same target. Do not jump straight to a very low value; an overly small MTU increases fragmentation and processing overhead. If only one network is affected, compare it with another Wi-Fi or wired network.

Create a recoverable shutdown procedure

Before normally exiting the client, disable TUN so it can remove the virtual interface, routes, and DNS changes. If the system shuts down unexpectedly or the client crashes and the network remains unavailable, restart the client and toggle TUN off and on normally so cleanup runs. If recovery still fails, check the system proxy, default route, and DNS. Do not install several network tools in succession while the residual state is unclear; this makes route ownership harder to determine.

A stable TUN configuration should meet four conditions: basic access works when enabled, the LAN remains reachable, DNS requests follow the expected path, and the system network is fully restored when disabled. Add strict routing, process rules, or complex DNS only after all four pass. For common TUN problems, return to the Quick Start page and follow its basic connection checks before locating the system-interception layer in this chapter.

Daily maintenance, backups, and troubleshooting

Update the client, core, subscription, and rules separately

The v2rayN graphical client, proxy core, subscription content, and GeoIP and GeoSite data are four independent update targets. Update one at a time, verify basic connectivity and split routing, then move to the next. This makes rollback quick when configurations become incompatible. A client update mainly changes the interface and configuration generation; a core update may change protocol implementation or parameter support; a subscription update changes nodes; a routing-database update changes classification results. Each produces different symptoms.

Before updating, record the currently working node, core type, system proxy mode, TUN status, and custom routes. Back up important configurations and keep the most recently verified working copy. After updating, test with the original node and mode; do not clean up old configurations immediately. Once startup logs show no parsing errors and connection logs look normal, remove expired backups. Automatic updates suit subscriptions and routine data; schedule client-branch changes or broad rule changes manually.

Troubleshoot in the order “entry point—resolution—routing—transport”

First check the entry point: does the program read the system proxy, or does traffic enter TUN? Second check resolution: does the domain receive an address, and does DNS follow the expected path? Third check routing: did the target match direct, proxy, or block? Fourth check transport: verify the node protocol, port, security parameters, and remote response. A fixed order prevents repeatedly changing nodes for a DNS problem or blindly changing routes when the node handshake is failing.

If a browser works but another application does not, check the application's entry point first. If all domains fail while a known IP connects, check DNS. If Rule mode fails while Global works, check routing. If all nodes suddenly fail, check the local network, system time, core process, and subscription changes. If one node fails, compare its fields with a working node in the same group. Keep one known-good sample during troubleshooting; it is more valuable than testing many nodes at once.

Use log levels and timelines correctly

Keep the log level at warning for daily use to highlight startup failures, resolution anomalies, and connection errors. Switch temporarily to info when you need to confirm route matching, reproduce the target request once, and save only the relevant time window. If the logs are too noisy, stop the connection, clear the current view, restart, and perform one test action. This links startup, DNS, routing, and connection records in time instead of forcing you to search through background requests.

Interpret error messages in context. timeout means no expected response arrived within the allotted time and may occur during DNS, TCP connection setup, or the protocol handshake; connection refused means the target explicitly rejected the port; name resolution failed points to the resolution layer; configuration parse errors usually identify a field path or type. When sharing logs, keep only the necessary lines before and after the error, and remove subscription URLs, node credentials, and unrelated access records.

Maintain system time, ports, and background state

Connections using TLS and REALITY depend on a reasonable system clock. A significantly incorrect device time can break certificate validity checks and handshakes, so enable automatic time synchronization. Locally, SOCKS, HTTP, and API listeners must not conflict with other programs; after changing a port, update in-app manual proxy settings as well. Starting the client repeatedly may create two interface instances while only one successfully owns the port. Use the process list and logs to confirm what is running.

Mobile devices require attention to background restrictions; desktop systems require attention to sleep and wake, network changes, and tray exits. When switching from wired to Wi-Fi or from a home network to a mobile hotspot, old connections and DNS caches may remain. Stop the current connection, wait for the old session to release, and reconnect. When using TUN long term, recheck virtual-interface permissions and shutdown recovery after every major operating-system update.

Build a simple, recoverable backup structure

Backups should include subscription groups, manual nodes, custom routes, DNS configuration, and client preferences at minimum. Use a date and purpose in filenames, such as “Desktop baseline rules” or “Stable TUN configuration,” but do not put subscription URLs or node identifiers in filenames. Verify that the backup can actually be imported or restored; copying one incomplete database file does not guarantee recovery. For cross-platform migration, prioritize standard subscriptions and routing concepts rather than assuming every interface configuration file is portable.

For complex failures, returning to a minimal configuration is usually faster than adding more patches: disable TUN, use the system proxy, temporarily use default DNS, choose one known configuration, enable Global mode, confirm the connection, then restore routing, DNS, and TUN in order. Retest the same target after each step. For DNS-specific issues, see Split DNS Resolution for Mainland China and Outside China; for Linux installation and autostart issues, see v2rayN Linux Installation Guide.

Turn a working configuration into a maintainable one

Set a minimal baseline first

The starting point for advanced configuration is not adding more rules, but saving a minimal baseline that can be reproduced reliably. It should include one working subscription group, one verified node, a system-proxy entry point, a simple direct rule for private addresses, an explicit default outbound, and observable logs. It does not need to cover every application, but it must answer where a request enters, how it is resolved, which rule it matches, and which outbound it uses.

Add features through small, reversible changes: start with GeoSite and GeoIP split routing, verify it, then add remote DNS, verify again, then TUN, and only afterward consider process rules, strict routing, or complex domain coverage. Keep a configuration snapshot and test targets at every step. The test set should cover an ordinary webpage, a LAN service, a domain requiring the proxy, a direct domain, and an application that ignores the system proxy, ensuring that a change did not solve only one scenario.

Understand generated configuration before customizing it

Clients such as v2rayN convert interface settings into core configuration. Advanced users should learn to inspect generated inbounds, outbounds, routing, dns, and log sections, but should not permanently edit temporary generated files outside the client because they may be regenerated when the client restarts or the node changes. Instead, edit the custom configuration, routing-rule, or preset entry provided by the client, then inspect the generated result to confirm that the change landed in the expected fields.

When reviewing configuration, trace tag relationships first: outboundTag in a routing rule must correspond to an actual outbound tag; a DNS server with a specified outbound must also have a matching tag; inbound tags can limit the scope of a rule. Correct field names with inconsistent tag spelling may cause the core to refuse startup or use an unexpected path. Array order also matters, especially for routing rules, DNS server selection, and domain-matching lists.

{
  "dns": {
    "servers": [
      {
        "address": "https://dns.example/dns-query",
        "domains": ["geosite:cn"],
        "skipFallback": true
      },
      {
        "address": "https://resolver.example/dns-query",
        "domains": ["geosite:geolocation-!cn"]
      }
    ],
    "queryStrategy": "UseIP"
  }
}

This snippet demonstrates the structure for selecting DNS servers by domain set; the example domains only illustrate the fields. In a real configuration, confirm that the current core supports the syntax and assign the resolver the correct outbound. skipFallback affects fallback behavior when a matching server fails and should not be enabled in bulk without understanding the result. After configuring DNS, still use routing checks to confirm that resolution requests and target connections follow a consistent path.

Set configuration boundaries for different networks

Home, office, public, and mobile-hotspot networks may differ in DNS, IPv6, LAN ranges, and port reachability. Do not cover every environment with one set of strong assumptions. If you switch networks often, prepare configurations such as “System proxy baseline,” “TUN interception,” and “LAN preserved,” with names that describe the interception scope rather than a location. After switching, check the current default route and DNS before starting the client to reduce problems from stale interfaces.

Office networks may use internal domains and private DNS; keep these requests on the local resolution path and send internal addresses direct. Storage, printers, and media devices on a home network likewise require private-range bypasses. Public networks may present a captive portal. Complete local authentication after connecting to the network, then start the proxy or TUN. If the portal does not open, temporarily disable the system proxy and TUN, authenticate, and restore the original settings.

Use a test matrix instead of subjective judgment

A maintainable configuration needs a fixed test matrix. After every change, test in order: can the client start; can the subscription update; can the known node connect; does the direct domain use direct; does the proxied domain use proxy; is the LAN address reachable; does DNS use the expected server; does the network recover when TUN is disabled? Record each result as “passed,” “failed,” or “not tested,” rather than simply writing “network normal.”

When a regression appears, return to the layer corresponding to the first failed item. Do not test webpages if the client cannot start; do not judge routing before DNS is confirmed; when LAN access fails, check private-address rules and interfaces; when the network does not recover after TUN is disabled, handle system networking first. A fixed test order lets you recheck client, core, or data-file upgrades with the same process instead of relying on memory.

Build a long-term learning path

After completing this guide, learn to read connection logs and generated configuration first, then go deeper into domain strategies, DNS outbounds, TUN routing, and protocol parameters. Study protocols through field relationships: the VLESS user ID and flow control, the REALITY server name and public key, and the transport service name and path should all be understood in the context of an actual node configuration. Do not begin by collecting large numbers of configuration snippets; without the client version, core capabilities, and server-side conditions, snippets are difficult to reuse directly.

Focus daily maintenance on explainability: know which group the current node came from, whether the system proxy or TUN is enabled, the main DNS path, the routing default outbound, and how to restore the baseline. The more complex the configuration, the more important it is to reduce hidden state. For a specific problem, return to the relevant section, then read related site articles and the FAQ on the Quick Start page, collecting logs and reproduction steps layer by layer.