V2Ray 全平台
安装配置指南

准备工作：系统、内核与连接资料

先区分客户端与内核

v2rayN、v2rayNG 和 v2flyNG 都是图形客户端，用于保存连接资料、管理订阅、组织路由并启动内核。真正解析协议、建立远端连接和处理流量的是内核。Project V 是相关技术生态的重要起点，V2Fly 与 Xray 是不同的内核发展分支；名称相近，不代表配置字段、协议扩展和资源文件可以任意互换。桌面端优先选择 v2rayN，Android 通常从使用 Xray 的 v2rayNG 开始，需要 V2Fly 配置兼容性时再评估 v2flyNG。

安装之前先确认操作系统、处理器架构和准备使用的包类型。系统名称只能解决第一层选择，架构决定程序能否运行，安装包形式则影响快捷方式、权限与更新方式。不能因为文件下载完成就认为适合本机。在桌面系统的“关于”页面查看处理器信息，在 Android 的设备信息中确认系统版本；若仍无法判断架构，优先参考设备厂商规格，而不是反复尝试不同安装包。

准备可解释的配置来源

客户端本身不附带可用服务器。需要事先取得有权使用的订阅链接、单节点分享链接，或与所选内核兼容的配置文件。三类资料的导入入口不同：订阅是可以再次请求的远端地址，分享链接通常描述单个连接，完整配置则可能还包含监听端口、出口和路由。先向资料提供方确认格式与支持的客户端，再选择导入方式，能避免把网页地址当成订阅、把完整 JSON 当作节点链接粘贴。

连接参数至少要能说明服务器地址、端口、协议及对应身份信息；使用 TLS 或其他安全层时，还要核对服务器名称、传输类型和相关参数。不同协议需要的字段并不相同，不应为了消除提示而随意补值。设备时间应保持自动同步，时间明显偏差可能影响证书有效期判断。网络也需要先能正常访问本地网关和普通站点，否则远端连接失败无法直接归因到客户端。

建立最小测试条件

首次验证只启动一个代理客户端，先关闭其他 VPN、代理软件和可能接管流量的浏览器扩展。记录原有系统代理设置，暂时不要同时启用复杂规则、自定义 DNS 和 TUN。先证明一个节点通过一种接管方式可以工作，再逐步增加设置。每次只改一个变量，并保留修改前的截图或文字记录；发生问题时能够退回上一状态，比一次开启全部选项更容易判断原因。

最后为排错预留基本信息：客户端名称、系统架构、当前内核、接管模式和报错出现的操作步骤。这里需要的是环境描述，不是完整配置。若之后更换设备，先在新设备重新导入必要资料并测试，确认正常后再清理旧设备。不要把“安装成功”“订阅更新成功”和“应用流量已经经过代理”合并成同一结论，它们分别对应程序运行、配置获取和实际流量路径三个不同环节。

Windows：v2rayN 安装与代理设置

桌面版与经典 WPF 版的选择

从Windows 客户端入口选择 v2rayN。桌面版使用跨平台界面，经典 WPF 版保留 Windows 的经典界面路径，两者管理连接的目标相同，但配置布局、运行环境和部分菜单位置可能不同。首次使用可以先选桌面版；已有经典界面工作流时，按实际需求选择 WPF 版。不要同时启动两个版本来比较连接效果，否则本地监听端口、系统代理和后台进程可能相互覆盖。

运行安装程序前确认系统满足该包的要求。按向导选择安装位置，首次启动若提示缺少运行环境，应根据提示补齐对应组件，再重新启动客户端，而不是下载名称相似的其他程序。用户配置目录应能正常写入；把程序放进受限位置，或由不同账户交替启动，可能造成设置无法保存。安全软件拦截时先阅读提示中的文件路径与操作原因，不要直接关闭整套系统防护。

导入订阅并确认活动服务器

打开订阅分组设置，为来源创建一个可识别的名称，再把完整订阅地址放入地址字段，保存后执行更新订阅。更新结束要检查服务器列表是否真的出现条目，而不只看通知是否消失。如果提供方给的是单节点分享链接，可使用从剪贴板导入的入口；它不会自动变成可持续更新的订阅。首次测试选择一个参数完整的服务器，设为活动项，再核对当前内核与该配置的兼容性。

更新失败时先判断客户端是否收到配置内容。返回登录网页、权限错误或格式不支持，和节点连接超时是不同的问题。若订阅源在当前网络下无法直连，可以在已有可用连接的前提下尝试通过代理更新；没有可用连接时，反复切换更新方式不会凭空建立访问路径。具体检查顺序可参阅订阅更新失败与解析报错自查清单。

先用系统代理，再评估 TUN

初次连接建议启用“自动配置系统代理”，确认客户端内核启动后再打开遵循系统代理的应用。Windows 中的系统代理记录通常是本地回环地址和客户端监听端口，它不是远端服务器地址。浏览器能够访问只能证明这一路径有效，不代表所有桌面程序都采用系统代理。应用若有自己的代理设置，应明确选择系统设置或手动指向相应本地入口，避免系统层与应用层配置互相矛盾。

需要接管不遵循系统代理的程序时，再检查当前 v2rayN 是否提供可用的 TUN 设置。启用过程可能需要提升权限或创建虚拟网络接口，应阅读客户端的授权提示。TUN 启动后关注网卡、路由和 DNS 是否一并建立，不要仅凭开关点亮判断成功。远程桌面、办公 VPN 和虚拟机网络都可能受路由变化影响，测试时保留本地操作能力，发现普通网络中断就先关闭 TUN 恢复环境。

退出、更新与残留代理

结束使用时先在客户端清除系统代理，再通过正常退出菜单关闭程序。若进程异常退出，Windows 可能仍指向已停止的本地端口，表现为所有遵循系统代理的应用无法访问；到系统代理设置检查并恢复原值即可。更新前备份配置，退出旧进程，保留可回退的安装状态。开机启动失败时检查是否为相同用户、快捷方式是否仍有效，以及安全策略是否阻止启动，不要用重复添加多个启动任务来绕过问题。

macOS：芯片选择、授权与网络服务

根据芯片选择安装包

在系统“关于本机”中查看芯片信息。Apple Silicon 对应 arm64，Intel 对应 x64；按macOS 下载入口选择 v2rayN。不要把处理器架构与系统版本混为一谈，同一系统名称可能运行在不同芯片上。打开磁盘映像后，按包内提示把应用放入应用程序目录，再从该位置启动。长期从挂载的映像中运行，可能让更新、权限和快捷入口的行为与预期不同。

首次启动遇到系统安全提示，应核对下载来源、应用名称和系统提示的具体原因，再通过系统提供的隐私与安全设置处理。安全策略、组织管理限制和损坏的下载文件对应不同分支，不应统一使用终端命令移除所有限制。受管理的工作设备可能不允许创建网络接口或修改代理，这属于设备策略范围，应先确认授权条件，而不是反复安装客户端。

订阅导入与基础连接验证

在 v2rayN 中创建订阅分组并粘贴完整地址，保存后发起更新。首次使用先选一个服务器作为活动项，检查协议、服务器名称和传输类型是否与提供方说明一致。跨平台客户端的菜单组织可能随版本调整，找不到同名选项时可根据“订阅分组”“系统代理”“路由设置”等功能定位，不要把 Windows 的配置目录或快捷键直接照搬到 macOS。导入完成后先验证基础连接，再迁移其他自定义设置。

开启系统代理后，打开系统网络设置，查看当前正在使用的网络服务是否已经写入代理地址。Wi-Fi、有线网络或其他服务可能分别保存代理选项，网络切换后应重新确认。自动代理脚本与手动 HTTP、HTTPS、SOCKS 代理也不是同一字段；若此前使用过其他工具，先记录旧设置，避免一边保留脚本地址，一边又增加手动代理，导致应用选择了不同的路径。

TUN、权限与休眠恢复

macOS 上是否能够使用 TUN，取决于当前客户端构建、内核集成方式与系统授权。若界面提供该功能，按照实际提示完成辅助组件或权限配置，再观察日志中的接口创建结果。不要假定桌面端所有版本都具有相同权限流程。启用后分别测试普通网页、需要代理的目标和局域网服务；如果网页正常而打印机、共享目录不可达，应检查直连路由是否覆盖本地网段。

设备休眠、唤醒或从 Wi-Fi 切到有线连接后，旧连接可能已经失效，本地代理设置却仍保留。先确认物理网络恢复，再重新连接活动服务器；若 TUN 接口没有恢复，关闭后重新启用，并查看是否出现重复接口或权限错误。不要一开始就删除全部订阅。浏览器缓存连接、远端会话和系统网络服务分别存在状态，依次重启应用、客户端连接和相关接管模式，更容易定位真正失效的一层。

更新前保留可迁移资料

升级应用前正常停止连接，保存订阅分组、必要的本地节点与自定义规则。重新安装程序不等于删除所有用户配置，反过来，删除应用也不一定清除系统代理。卸载或停用后，应到当前网络服务确认代理已经恢复。迁移到另一台 Mac 时，优先迁移订阅和可读规则，再重新设置本地端口、启动行为及系统权限；这些内容与设备环境有关，不适合把旧机器的完整运行目录直接覆盖到新机器。

Linux：软件包、桌面代理与权限边界

匹配发行版软件包体系

Linux 使用 v2rayN 图形客户端时，先确认发行版采用 deb 还是 rpm，再确认处理器架构。Debian 系及其衍生发行版通常选择 deb，采用 RPM 软件包体系的发行版选择 rpm；x64 与 arm64 不能互换。本站的Linux 客户端入口分别列出这些包。包格式匹配仍不代表所有旧系统都满足依赖要求，安装器的依赖提示需要单独阅读，不能通过忽略依赖强行推断兼容。

优先使用发行版的软件安装器打开下载文件，使依赖解析、安装位置和卸载记录由系统包管理器负责。若终端提示缺少图形库，先核对系统支持范围，再通过发行版正常渠道补齐。不要为了让图形界面出现而把整个客户端长期以最高权限运行，这会改变配置文件归属，也扩大处理订阅和本地文件时的权限。普通用户保存的配置与提权启动后生成的配置可能不在同一路径。

桌面会话与应用代理不是一套机制

在图形界面导入订阅、更新列表并设定活动服务器后，先测试客户端本地监听是否正常。Linux 的桌面环境对系统代理的支持并不完全一致，有的应用读取桌面设置，有的读取环境变量，还有的只认应用自身配置。因此“已设置系统代理”只说明客户端尝试写入了某种桌面代理接口，不能据此推断终端、软件安装器和所有图形应用都会经过相同出口。

对需要单独设置的应用，先在客户端查明本地 HTTP 或 SOCKS 入口的地址、端口和支持类型，再填写到应用设置中。环境变量通常只影响之后启动的进程，已经运行的终端或应用不一定更新。不要把远端节点地址填到本地代理栏，也不要只根据端口数字猜协议。若同一端口是混合入口，应以客户端明确标注为准；使用独立入口时，HTTP 与 SOCKS 的协议字段必须分别对应。

# 查看当前桌面会话与内核架构
printf '%s\n' "$XDG_CURRENT_DESKTOP"
uname -m

# 查看本机正在监听的 TCP 端口
ss -ltn

TUN 的授权与 DNS 排查

创建 TUN 接口和修改路由通常需要额外权限，但具体授权方式由客户端构建与发行版环境决定。按当前客户端提供的流程操作，失败后查看明确的权限或接口错误；不要把复制来的高权限命令直接用于未知文件。防火墙、其他 VPN、容器网络和策略路由可能同时改变转发路径。首次测试先保持网络结构简单，再逐项恢复这些组件，记录是哪一步使连接行为发生变化。

DNS 还可能由桌面网络管理服务、本地解析服务或其他网络工具管理。TUN 接管成功但域名失败时，应比较按域名访问和对已知目标建立连接的结果，再检查日志中的解析请求与上游可达性。不要立刻覆盖系统解析配置文件，因为它可能由服务自动生成，手动修改不仅会被覆盖，还可能破坏其他网络。应从客户端 DNS 设置、当前网络服务和冲突程序三个层面确认实际控制者。

托盘、自动启动与配置保存

部分桌面环境没有默认显示传统托盘图标。窗口关闭后看不到图标，不代表进程一定退出；先检查进程和监听端口，再重新启动，避免产生多个实例争用端口。自动启动应在当前用户桌面会话正常之后执行，过早启动可能无法读取代理接口。更新前退出客户端并备份必要配置，安装后检查文件归属和可写权限。若只有提权启动才能保存设置，优先修正配置目录的归属问题，而不是把提权当作日常使用方式。

Android：VPN 授权、后台与分应用代理

v2rayNG 与 v2flyNG 的选择

Android 优先从 v2rayNG 开始，它使用 Xray 内核；需要 V2Fly 相关兼容性时，可考虑 v2flyNG。两款客户端不能仅凭名称相近就共用全部协议扩展。到Android 下载入口按架构选择安装包，多数较新的设备使用 arm64；无法确定或设备情况特殊时查看厂商资料，必要时选择通用版。通用版解决的是架构覆盖，不代表拥有不同的服务器或连接能力。

安装时由系统提示授予当前文件来源的安装权限，只在确实需要的来源上临时开启。安装结束后可恢复原来的权限设置。更新已有客户端时，应用身份和签名需要兼容；遇到不能覆盖安装的提示，先确认是否下载了同一款客户端，不要立即卸载。卸载可能删除本地节点、自定义配置和分应用清单，若确需重装，应先通过客户端可用的导出方式保存必要资料。

导入资料与首次 VPN 连接

在客户端订阅设置中添加分组名称和完整地址，保存后更新；单节点则使用对应的剪贴板或扫码入口。检查服务器条目是否出现，再选择活动项。开始连接时，Android 会显示 VPN 授权提示，这是 VpnService 建立本地虚拟接口所需的系统权限。确认应用名称正确后授权。拒绝授权、授权流程被其他窗口打断，或已有其他 VPN 占用，都可能使客户端无法接管设备流量。

Android 通常只允许当前用户空间中的一个 VPN 服务保持活动。另一款 VPN 或具备本地 VPN 功能的过滤工具启动后，可能取代当前连接。先关闭竞争服务，再观察系统 VPN 标识和客户端日志。系统出现 VPN 标识只说明虚拟接口已建立，不能证明远端服务器可用；还应打开实际应用验证目标访问，并确认日志中存在对应请求。网络正常但特定应用失败时，继续检查分应用规则而不是重复申请授权。

后台断连与网络切换

省电策略可能限制后台网络或结束客户端进程。若锁屏一段时间后断连，而亮屏重开即恢复，检查系统电池优化、后台活动限制及厂商的自启动管理。设置名称因设备不同而异，应针对客户端调整，不必修改整机所有应用。持续通知可能用于维持前台服务，是否可隐藏及其影响取决于系统版本；不要只为了清理通知而关闭与连接保活相关的权限和服务。

Wi-Fi 与移动数据之间切换会改变底层网络，原有连接可能需要重建。先确认新网络本身可用，再查看客户端是否重新建立隧道。系统的始终开启 VPN、阻止未经过 VPN 的连接等选项，会改变断开时的网络表现；启用前需要理解其后果。若客户端未启动时所有应用都无法访问，应检查这些系统设置，区分有意阻断与故障，不要直接把问题归为订阅失效。

分应用规则与备选客户端迁移

分应用代理通常提供“仅所选应用使用”或“所选应用绕过”等方向不同的模式。先确认模式含义，再选择应用；浏览器被排除时，节点正常也不会让该浏览器经过代理。工作资料、应用分身和不同用户空间可能使用独立的应用身份，原清单不一定覆盖。调整后按客户端要求重新连接，使 VPN 的应用集合重新生效。更多系统细节见VPN 权限、省电白名单与分应用代理。

从 v2rayNG 切换到 v2flyNG 时，先停止旧客户端的 VPN，再在新客户端重新导入订阅并核对协议支持。不要直接复制全部内部配置覆盖应用数据。分应用列表、通知权限与省电授权属于本机应用设置，需要重新检查。完成一条基础连接后，再恢复复杂规则；如果只有某种协议失败，应比较内核支持范围和提供方参数，而不是同时修改所有节点。

订阅与迁移：格式、分组和资料保护

订阅更新与节点导入的区别

订阅更新是客户端向地址请求内容，再将内容解析成服务器条目。成功至少包含三个条件：地址可以访问、返回内容确实是配置、格式能被当前客户端识别。网页能够打开同一域名，只能说明部分网络路径可用；订阅端点仍可能要求不同权限或返回错误页面。反过来，导入成功也不意味着所有节点都能连接，客户端通常无法在解析阶段验证每一个远端服务器的运行状态。

单节点分享链接一般只保存当时的参数，提供方之后更换地址或端口时，它不会自动同步。完整自定义配置又包含更大的作用范围，可能自己定义入口、出口、路由与 DNS，因而绕过图形界面的部分设置。导入前应确认入口名称与资料类型匹配。不要把完整配置拆成看似相似的字段手动拼入节点编辑框，也不要把浏览器收藏的订阅管理页面当成实际订阅地址。

https://subscription.example.net/client?token=xxxx

分组、更新覆盖与本地修改

多个订阅来源最好使用独立分组，名称写成能够识别来源和用途的短语。先在单个分组执行更新，确认返回内容正常后，再考虑批量更新。节点别名是显示信息，不一定是稳定标识；提供方重命名、合并节点或调整顺序，可能使原来的活动项失效。更新后连接异常，应检查活动服务器是否仍然存在，以及它的真实参数是否改变，而不是仅凭旧别名判断选中了相同连接。

订阅管理的条目可能在下一次更新时被覆盖。若确有必要修改某个节点，先查看客户端是否支持复制为独立本地条目，明确它之后不再自动跟随来源。自定义规则、订阅节点和临时测试节点应分开管理，避免清理分组时误删手工配置。批量过滤和测速也应限定作用范围；一口气对全部来源发起大量测试，会制造额外请求，还可能让结果受到本地带宽和连接数量限制。

订阅转换的适用边界

配置格式不同不一定能通过转换解决。转换器可以重排字段或生成另一种客户端格式，但无法让目标内核获得原本不支持的协议能力，也无法可靠补出缺失的认证信息。若确需转换，应先确认输入、输出格式和目标内核支持情况。把含访问凭据的订阅交给不熟悉的在线服务，意味着这些内容可能被服务读取；优先使用来源方提供的适配格式，减少不必要的数据流转。

更新时报编码或解析错误时，先保留简短错误信息，再检查链接是否多了空格、换行或聊天软件附加字符。不要在浏览器中随意重写查询参数，也不要公开完整响应内容。若问题只出现在某个分组，其他分组正常，重点检查该来源的权限、返回格式与协议兼容性。多来源的管理方式可进一步参考订阅分组与服务器过滤实践。

跨平台迁移不等于自动同步

多平台迁移主要是重新导入订阅、导出必要的本地连接和搬运兼容规则，并不代表客户端之间存在内置云同步。桌面的监听地址、窗口设置、权限组件和系统代理状态不适合原样迁移到 Android。备份前正常退出客户端，避免复制到尚未写完的文件；恢复后先验证基本节点，再逐项恢复路由。旧设备停用时清理不再需要的资料，若怀疑订阅已经外泄，应在来源端撤销或更换访问凭据，仅删除本地记录不能使旧链接失效。

代理与路由：入口、出口和 DNS

先判断流量有没有进入内核

一次访问可以拆成应用产生请求、本地入口接收、路由选择出口、内核建立远端连接几个阶段。系统代理与 TUN 解决的是流量如何进入客户端，路由规则解决的是进入之后如何处理。若应用根本没有读取系统代理，修改远端路由不会改变它的访问路径。排查时先看日志是否出现该应用对应的请求，再判断它被分配到直连还是代理；这比反复切换所有模式更有解释力。

系统代理适合遵循系统设置的应用，本地 HTTP 或 SOCKS 入口还可以供具备独立代理设置的程序使用。监听地址通常优先保持回环地址，只允许本机访问；改为对外监听可能让局域网其他设备接入，还涉及认证与防火墙，不应作为普通连接失败的修复手段。端口数值并没有固定的“更快”含义，重要的是未被占用、协议匹配，以及系统和应用填写的端口与实际监听一致。

规则顺序与出口名称

内核通常按规则顺序匹配，较早命中的规则决定处理结果。一个覆盖范围很大的规则放在前面，可能让后面的精细规则永远无法生效。直连、代理、阻断等出口必须在配置中真实存在，规则引用的标签也要完全一致。客户端内置的“绕过大陆”等预设依赖当前规则实现与资源文件，不是一个能概括所有场景的保证；局域网、工作网络和特定域名仍需要按实际环境验证。

下面是用于说明结构的 Xray 路由片段，不是独立运行配置。它假定已有标签为 direct 的出口，并可读取所引用的规则资源；先把私有地址流量交给直连，其他流量继续交由后续规则和默认出口处理。图形客户端可能在启动时重新生成配置，直接编辑生成文件的修改可能不会保留，应优先使用客户端支持的规则编辑入口。

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

DNS 与路由需要一起理解

DNS 负责把域名解析为地址，路由则决定请求使用哪个出口，两者会相互影响。应用如果先在系统侧解析，内核可能只看到目标地址；如果请求携带域名，内核才可能直接应用域名规则。不同入口、嗅探设置和解析策略会改变可见信息，因此同一个目标在不同应用中的路径可能不同。不能仅凭“域名规则已经添加”就断言所有访问一定命中，必须结合入口类型与日志判断。

当域名失败而其他连接正常时，检查实际使用的解析器、上游是否可达，以及 DNS 请求本身是否被路由到能够工作的出口。不要同时更换多个解析器、启用嗅探并修改全部规则；每次只变更一项，再观察报错从解析失败变为连接超时还是恢复正常。启用 TUN 后还应检查 DNS 是否按客户端设计被接管，系统保留的解析配置可能与新路径不一致。办公网络中的内部域名尤其需要保留对应解析和直连条件。

TUN 与真实可达性的验证

TUN 接管范围更广，但仍受系统权限、路由排除、DNS 和内核能力限制，也不意味着所有 UDP 场景一定可用。测试应分别覆盖需要代理的目标、应当直连的局域网资源及常用应用，确认没有连接环路。节点列表中的低延迟结果只代表某一种测试路径，不等同于实际下载速度或应用体验。相关差异可阅读Ping、真连接延迟与测速结果的区别，避免依据一个数字修改整套网络策略。

配置常见问题：从症状回到故障层

按固定顺序收集证据

遇到无法连接，先明确现象发生在哪一步：程序打不开、订阅无法更新、内核无法启动，还是应用访问失败。四类问题的处理入口不同。先确认普通网络能够工作，再确认客户端活动项与接管方式，随后查看日志中首次出现的错误。不要只截取重试后的最后一行，因为它可能只是前一处失败引起的连锁结果。记录操作时间、目标类型和修改内容，有助于把对应请求与日志关联起来。

若程序能启动但内核退出，重点检查配置语法、字段兼容性、本地端口占用和资源读取错误。若内核运行正常而应用没有请求记录，检查系统代理、应用自身设置与分应用清单。若已经有请求但远端超时，继续比较服务器地址、端口、网络路径与服务端状态。完整的分层顺序见节点超时与无法连接排查；先缩小范围，再决定需要修改哪一层。

证书、端口和权限错误分别处理

证书相关错误先检查设备时间、服务器名称与配置中的安全层要求，再确认订阅是否已经更新。不要通过永久跳过证书验证来掩盖不匹配，这会改变连接的安全边界。端口占用错误则在本机处理：退出其他客户端或重复进程，确认监听者，再按需要调整入口端口，并同步更新使用该端口的应用。权限错误通常关联配置目录、接口创建或系统策略，应该定位具体对象，而不是一律以更高权限启动。

最小化复现与更新回退

为复杂故障建立最小化复现：保留一个已知配置来源、一个活动节点、一种接管方式和一个测试应用。暂时移除自定义规则影响，但先保存备份。若最小环境正常，再逐项恢复 DNS、规则和其他应用设置，确定引入异常的步骤。更新前后行为不同，应核对配置迁移、内核选择与规则资源是否变化；保留旧配置并记录现象，避免用反复覆盖安装破坏回退条件。

需要他人协助时，提供系统、客户端、内核、接管模式及已遮盖敏感内容的错误摘要即可。不要公开订阅全文、节点身份信息或完整配置目录，也不要把单次测试结果解释成普遍结论。恢复连接后保留简短处理记录，并撤销为了排查临时放宽的监听地址、权限和安全设置。首次上手仍可回到快速上手主线逐步重建；需要更换平台或包类型时，再到客户端页面选择对应入口。