客户端安装手册

V2Ray 安装配置大全

分平台查安装,分层查连接。涵盖安装包选择、订阅导入、系统代理和 TUN 模式。

第一次配置,建议先沿着快速上手教程完成导入、选择模式和连接验证。本页是查阅手册:安装包不确定时,直接跳到对应平台;节点已能连接但应用没有走代理时,从连接验证或常见问题开始。

01通用准备

安装前准备:客户端、安装包与订阅

区分客户端、内核和节点

客户端是日常操作的图形界面,负责保存订阅、选择节点和切换代理模式。内核在后台读取配置,建立连接并执行路由规则。节点是远端连接配置,通常包含服务器地址、端口、认证信息和传输参数。下载并打开客户端,不等于已经取得可用节点;成功导入节点,也不等于当前应用已经通过代理联网。

Project V 是理解这套工具的起点。V2Fly 延续了 V2Ray 的社区开发,Xray 是从相关生态发展出来的另一条内核分支。同名协议在不同内核上支持的传输或安全选项不一定完全相同。迁移时,先确认原配置使用的内核和传输组合,再看目标客户端能否识别。不要只凭节点名称相同,就认定两份配置等价。

先看系统类型,再选安装包

桌面端首推 v2rayN。Android 优先选使用 Xray 内核的 v2rayNG;已有配置明确要求 V2Fly 内核时,可看 v2flyNG。先在当前设备查看系统与处理器信息,再打开下载页。两台外观相近的电脑可能采用不同架构;即使架构相同,不同系统或发行版也可能使用不同的安装包格式。

四个平台的选包依据
平台入口客户端核对项
Windowsv2rayN系统架构;Desktop 或 WPF 界面
macOSv2rayNApple 芯片或 Intel 处理器
Linuxv2rayN发行版包格式;x64 或 arm64
Androidv2rayNG;v2flyNG 备选内核需求;arm64 或通用包

架构标签描述的是软件包可以在哪类系统环境中运行,不是速度等级。手机的处理器即使支持六十四位,系统也未必向应用提供对应的运行环境。桌面上还要区分安装器和便携压缩包:安装器通常负责准备应用目录与快捷方式,便携包则需要保留解压后的目录结构。换包前先看清原包类型,不要把旧目录里的可执行文件单独复制到新目录。

识别订阅地址和单节点链接

订阅地址通常是一个网页形式的地址,客户端用它请求节点列表。添加地址只是建立订阅分组,主动更新后才会取回节点。以 vless:// 或 vmess:// 开头的分享链接通常只描述一个节点,应使用从剪贴板导入节点的功能。网页地址也可能只是登录页或帮助页,拿到地址时先确认它的用途,不要按前缀以外的猜测把网页链接当订阅。

扫码时同样要先判断二维码里是单节点还是订阅。扫完看客户端打开的是添加订阅表单,还是节点预览。若列表原本已有同名条目,导入后可按分组和节点类型核对新条目,不必为了确认导入结果而清空列表。需要了解不同链接的更新行为,可查阅分享链接与订阅地址的区别。

保留可退回的初始状态

安装前记下系统代理是否启用、是否另有虚拟专用网络,以及工作环境是否要求固定代理。原有设置由工作单位管理时,不要擅自覆盖。已有客户端的用户,先用它提供的备份或导出功能保存配置。先保留订阅分组、手动添加的节点和自定义路由,再考虑跨客户端迁移。导出文件仍按敏感资料保存;共享电脑上避免把它长期留在公共下载目录。

首次使用建议走一条最短的验证路径:只导入一个节点或一份订阅,只选一个节点,只启用一种流量接管方式,最后访问事先选定的测试目标。先不要同时调整域名解析、分流规则和开机启动。验证通过后再补这些设置;若第一次就失败,已知变化少,可以分清问题究竟发生在安装、导入、内核启动还是应用接管。

02桌面配置

Windows:v2rayN 安装与系统代理

选择 Desktop 或 WPF 安装包

打开系统设置的「系统 → 关于」,查看系统类型。到Windows 下载区核对安装包标注。Desktop 使用跨平台界面,经典 WPF 版保留熟悉的 Windows 界面布局。选择依据是系统兼容性和使用习惯,不是节点协议。下载区的 x64 包对应 x64 环境;如果设备使用其他架构,先确认系统是否提供相应的兼容运行方式,不要把包名中的位数当作适配说明。

先退出旧客户端,包括托盘区仍运行的实例,再运行安装程序。按安装向导完成后,从新的快捷方式启动。若程序提示缺少运行环境,先记下提示中的组件名称与架构,再按该包的说明处理。遇到应用执行限制时,先核对安装来源、系统提示和设备管理策略;不要关闭整套系统防护来尝试启动,也不要把系统目录当作配置保存位置。

导入订阅并选中当前节点

从订阅分组相关菜单新增分组,填写一个能辨认的备注和完整订阅地址,再执行更新。电脑此时还没有可用代理时,可以尝试不通过代理更新;该方式取决于当前网络能否直接访问订阅服务。若地址只能通过已有连接访问,应先让已有连接可用,再用通过代理更新的方式。不要仅凭“更新成功”的提示判断节点可用,还要切到对应分组确认条目确实出现。

如果手里只有一个分享链接,复制完整链接,再用从剪贴板导入节点的入口。导入后选中该条目,将它设为当前服务器或活动节点,具体名称按当前界面为准。列表中高亮的行不一定就是正在使用的条目。可以在客户端状态或本次连接的日志里核对实际选中的节点,而不是把多次导入得到的同名条目逐个试一遍。

浏览器先用系统代理,其他应用按需用 TUN

先在托盘菜单把系统代理切到「自动配置系统代理」或同等选项,再用读取系统代理的浏览器发起新请求。系统代理把本地代理地址告诉应用,并不直接接管所有进程。有独立网络设置的工具可能继续直连;浏览器也可能受已有扩展、管理策略或独立代理配置影响。只要目标应用允许手工指定代理,就可先单独验证它,无须立刻改变整台电脑的接管方式。

确实需要由虚拟网卡接管的应用,再单独测试 TUN。先记录旧模式,关闭测试应用的手工代理,按客户端当前界面的提示处理权限。启用后确认虚拟接口与相关路由已经建立,再分别测试普通访问、局域网访问和原本需要保留的工作连接。TUN 开关显示已开,并不表示路由一定安装成功;失败时先关闭该模式,再读取启动错误,而不是反复授权和重启。

识别托盘残留和端口占用

关闭主窗口后,v2rayN 可能仍常驻托盘。升级或切换 Desktop、WPF 时,先在旧实例里选退出,再打开新版本。若日志报本地端口无法绑定,先从设置读取报错对应的端口,并确认是否有旧客户端或其他本地服务监听。不要结束不认识的进程。若必须调整端口,也要一并更新浏览器或工具里保存的手工代理地址。

突然断网而客户端已退出时,先查看系统代理设置是否仍指向本机地址,再确认那个端口是否还有监听程序。这类故障表现得像整台电脑断网,实际可能只是应用还在尝试访问已经退出的本地代理。若仅某个程序恢复不了,重新打开该程序再测一次,它可能仍沿用旧连接。确认本地设置恢复后,再判断远端节点或网络是否另有问题。

03桌面配置

macOS:芯片选包、应用安装与代理

按「关于本机」选择磁盘映像

在苹果菜单打开「关于本机」。设备信息若显示 Apple 芯片,进入macOS 下载区选择 Apple Silicon 对应的 arm64 包;若显示 Intel 处理器,则选 x64 包。优先使用系统信息而不是模拟环境中的终端输出判断芯片。拿不准时也不要连续试装两个包,两份同名应用可能让后面的启动路径与代理状态更难分辨。

打开下载的磁盘映像,按窗口指示将应用拖入「应用程序」目录,从目标目录启动,再推出磁盘映像。不要长期从映像窗口里运行,也不要把两份同名应用分别放在下载目录和应用程序目录。替换旧应用前,要从菜单栏或应用菜单完整退出旧实例。若系统拒绝打开,先按提示区分架构不符、系统版本不符和管理限制,不要批量取消应用保护。

用分组管理订阅,确认本机权限范围

启动 v2rayN 后,在订阅功能中新增分组,把地址完整粘贴到地址栏,给分组起一个易辨认的名字,再手动更新。使用多个桌面空间或应用窗口时,先确认当前窗口显示的是新分组,不是全部节点视图。只有一条分享链接时,从剪贴板导入到明确的本地分组,便于以后区分哪些记录来自自动更新,哪些需要手工维护。

要迁移旧电脑上的订阅,优先使用原订阅地址重建分组,再导入少量确认需要保留的手工节点。避免直接替换整个应用的配置目录:旧系统中的本地路径、端口、权限和内核选项未必适合新设备。初次启动时若程序询问是否允许某项操作,应看清它涉及网络接管还是本地文件访问,只为当前所需功能授予权限,记录授权后出现的变化。

按网络服务检查系统代理

通过客户端启用系统代理后,可在「系统设置 → 网络」打开当前使用的网络服务,查看详细信息中的代理设置。切换无线网络和有线网络时,要注意对应服务可能不同,代理状态也不一定沿用。读到本机环回地址时,还要确认端口与客户端当前公布的本地监听一致;一个旧端口也能留在系统设置里,但无法替新进程接收请求。

若只有某个应用连接失败,先比较它是否读取系统代理,再决定是否使用 TUN。对当前构建已提供并支持的 TUN 功能,按界面流程启用,先停用可能冲突的本机代理实例,然后检测普通网页、内网访问和休眠唤醒后的状态。如果客户端显示权限或路由设置失败,先退回系统代理观察基础连接,不要用多次重开开关替代错误定位。

处理唤醒、网络切换和代理残留

电脑休眠时,旧连接可能已经被网络设备关闭;唤醒后,电脑也可能连上另一项网络服务。遇到页面长时间等待时,先确认当前网络能正常联网,再用客户端重建连接,并发起一个全新的请求。老标签页、长时间下载和后台同步进程可能继续尝试使用旧连接,不能代表新请求也失败。若重复出现,记录故障是否只在切换网络或唤醒后发生。

如果清除客户端系统代理后仍无法访问局域网,检查当前网络服务是否配置了代理脚本、手动代理或特殊排除项,并核对是否仍有其他网络工具在运行。公司或学校写入的设置应保留。只有本次安装新增的项目才按原记录撤回。恢复后先测试本地服务,再测试互联网;前者不能访问时,先排查本地网络路径,不要用更换远端节点尝试修复。

04桌面配置

Linux:软件包格式、桌面代理与 TUN

同时匹配发行版与架构

在Linux 下载区选择 v2rayN。通常 Debian 系发行版选择 deb,使用相应软件包体系的 Fedora 等发行版选择 rpm。格式相符只是第一步,还要看发行版版本、依赖和桌面环境。不要把两种格式只当成文件后缀,也不要为了强装而用转换工具改包。手边只有终端时,可用下列只读命令了解当前系统。

cat /etc/os-release
uname -m

/etc/os-release 提供发行版相关信息,uname -m 显示当前内核看到的机器架构。常见输出 x86_64 对应 x64,aarch64 对应 arm64。若在容器、虚拟机或混用架构的环境下操作,再核对实际安装目标的软件包管理器所使用的架构。例如在 Debian 系系统可看 dpkg --print-architecture,不要把宿主机结果当成客体系统结果。

从当前桌面会话启动,再导入订阅

用系统软件安装器打开匹配的本地包,查看依赖提示并完成安装。遇到安装失败,应先读出缺失的软件包名称、架构冲突或发行版版本限制。出现“安装已完成但找不到窗口”的情况时,从应用菜单尝试启动,并确认自己正处在可用的图形会话。通过远程终端调用图形应用,和在登录用户的桌面里启动,不一定得到同样的界面和代理设置。

正常启动后,在订阅菜单创建分组并更新,确认节点列表已出现;单条分享链接走剪贴板导入。用平常登录桌面的用户运行应用。仅为让界面打开而用管理员身份启动,可能把配置写到不同的用户目录,后来用普通账户打开就会像丢了数据。确需提升权限的网络功能,应按客户端支持的授权方式处理,不要给整个图形程序长期提升权限。

测试桌面代理与终端代理的区别

桌面环境里的系统代理是供应用读取的设置,并非所有桌面或程序都采用同一套接口。浏览器可能跟随桌面设置,终端中的命令却可能只认自己的参数或环境变量。先确认客户端的本地 HTTP 或混合代理已经监听,再用单次命令明确指定它,避免为了测一次连接就把代理写进终端启动文件。下例会提示输入客户端设置中显示的本地 HTTP 或混合代理端口。

printf '本地 HTTP 或混合代理端口:'
read -r proxy_port
curl --noproxy '' --proxy "http://127.0.0.1:${proxy_port}" \
  --max-time 15 --head https://example.com/

这条命令适用于本地代理在环回地址提供 HTTP 接入的情况。若设置显示的是仅 SOCKS 监听,应为相应协议选择参数,而不是把端口直接代入这条命令。若显式代理请求成功、普通程序仍失败,先查普通程序的接管方式和自身代理设置。命令返回目标响应,只能证明这一次请求有可用路径;是否走了远端节点,还应与客户端日志中的分流决定对照。

用 TUN 前检查权限、接口和旧配置

准备启用 TUN 时,先确认运行环境提供虚拟网络接口支持,且当前构建支持该模式。容器和受管理的环境即使能打开客户端,也不一定允许创建接口或修改路由。客户端报告权限或接口错误时,先退回已验证的系统代理,再核对部署环境允许的权限。不要盲目复制修改系统能力的命令,也不要以关闭防火墙作为排查的第一步。

如果启用成功,但单个终端或服务仍表现异常,检查它是否保留了旧代理环境变量,或在自己的网络命名空间中运行。关闭 TUN 后,用一个新终端和一个新浏览器窗口分别复测。若新会话可用而旧会话不行,问题可能在进程继承的环境;若同一桌面上的应用整体失效,再查当前接口、路由和解析设置是否按预期恢复。

05移动配置

Android:v2rayNG 安装与 VPN 接管

按需求选择客户端与安装包

打开Android 下载区。常规使用优先选 v2rayNG,它使用 Xray 内核;明确需要 V2Fly 内核的配置再看 v2flyNG。支持 arm64 应用的设备选 arm64 包;无法确认系统支持的应用架构时,可考虑同一客户端的通用包。通用包能覆盖更多架构,但不会解除系统版本限制,也不能用来解决已有应用的签名冲突。

下载完成后从文件管理器或浏览器打开安装包,按系统提示仅为本次安装所用来源授予必要权限,之后可撤回。更新时优先用与现有应用同一发行来源的包。若系统拒绝覆盖,先区分签名不同、版本不允许覆盖、存储空间不足或设备管理策略。不要第一时间卸载旧应用;卸载可能同时清除订阅、手工节点和按应用设置,应先做好有需求的备份。

添加订阅或扫描单节点二维码

打开客户端,在订阅分组设置中新增条目,填写备注和地址,保存后回到节点列表,执行更新订阅。更新完成时确认查看的是目标分组,避免被其他分组的旧节点误导。首次导入先保留默认配置,只选一个节点建立测试基准。如果地址能够在桌面更新而手机不能,记录手机当前是无线网络还是移动数据,不要先删除桌面上已成功的订阅。

收到单节点链接时,复制后用剪贴板导入;收到二维码时,使用客户端中可用的扫码或图片导入入口。二维码与配置文本一样可能含有凭据,不适合留在共享相册中。若无法识别,先检查图片是否裁切、压缩或有反光,再确认码的用途。订阅分组更新与扫码导入是两件事,扫入一个节点不会自动为它建立订阅关系。

读懂系统 VPN 授权与应用范围

选中节点后启动连接,系统通常会弹出 VPN 连接确认。它授权客户端接管指定流量,与电脑上填写系统代理地址不同。确认后先观察客户端状态和系统 VPN 标识,再打开浏览器发出新请求。系统标识说明接管服务已建立,不说明远端一定可用,也不能证明每个应用都被接管。如果标识一闪即消失,先检查服务是否被其他 VPN 或系统策略替换。

客户端若提供按应用代理,将它当作接管范围,而不是节点选择。先看界面采用的是“只包含所选应用”还是“排除所选应用”,再做配置。浏览器在名单里不代表下载管理器或另起进程的应用也在名单里。排错时先回到明确的接管范围,只用一个浏览器验证;确认配置无误后,再加回原来的名单。永久 VPN 或禁止未通过 VPN 的连接可能影响退回测试,调整前先记录原设置。

区分切网、后台限制和设备策略

只在息屏后断开时,先看再次亮屏后 VPN 服务是否仍在运行,再回忆是否启用了系统的后台限制或省电策略。只有反复出现且确实影响使用时,才按设备设置为该客户端调整相应权限。不必关闭整台设备的省电保护。若已连接但无法切换到移动数据,先关掉旧连接并重新建立一次,用一个新请求判断是连接恢复问题还是当前网络本身不可达。

在学校、单位或受管理的设备上,系统可能限制安装、后台启动或 VPN 使用。这些限制与订阅是否有效无关,应按设备管理要求处理。如果已切换无线网络和移动数据,但两者都只表现为某个应用失败,回头查按应用名单、应用自身的代理设置和路由规则;如果连 VPN 服务都不能建立,则先处理本机授权或竞争的 VPN,再查节点。

06配置验证

连接验证:从本地监听到路由命中

将一次联网拆成四个检查点

第一步是看内核能否启动。桌面端关注本地代理端口是否开始监听,移动端关注系统接管服务是否建立。第二步是看测试应用的请求是否进入客户端:发起新请求并观察日志,既不要只看界面上的连接按钮,也不要只看节点列表内的一次测试结果。客户端没有收到请求时,换远端节点通常不会改变结果,应先修正应用接管设置。

第三步是看请求匹配了哪条路由,实际采用代理、直连还是拦截。第四步才看目标能否响应。一个网页可能加载多个域名,主文档和图片、脚本或登录接口走的规则不一定相同。先用请求入口清楚、不会依赖一组第三方站点的目标做验证,再回到原来的应用。测试目标要与日常使用有可比性,但不必拿自己的账户页面或真实订阅地址做演示。

按证据缩小故障范围
检查层可观察的现象优先检查
启动内核退出或接口未建立配置错误、端口、授权
接管测试应用未留下请求记录日志级别、代理模式、应用范围
分流请求已进入但走错出口匹配条件、先后顺序、默认出口
出站出口符合预期但没有响应节点连通、解析、传输与安全设置

区分系统代理、全局路由和 TUN

「系统代理」描述的是应用如何找到本地代理;「全局」通常描述已进入客户端的流量采用何种出口。两者不是同一个开关。即使选择全局路由,不读取系统代理的进程也可能从未进入客户端。TUN 通过系统的虚拟网络接口接收符合路由条件的流量,覆盖范围通常更广,但仍可能受到排除规则、系统能力和其他网络服务的限制。

初次验证时不要把三者同时改动。先按系统代理设置步骤测一类明确会读取代理的应用。再根据真实需求决定是否换成 TUN。切换时先让前一种接管方式回到预期状态,避免应用在虚拟接口启用后还手工连着旧端口。对照时保留同一个节点、同一个目标和同一网络,只改变接管方式,才容易看出区别。

检查规则顺序、域名和地址

按界面提供的方式查看路由规则和默认出口。有顺序的规则列表通常先采用首个匹配项,范围较广的条件放在前面,可能提前截走本应交给后续精确规则的请求。某条规则选择直连还是代理,还取决于规则绑定的出口。排查时不要先把所有条目删除,先用一条清楚的测试请求核对命中条件,再调整那条真正影响它的规则。

域名规则适合按主机名组织流量,地址规则针对具体地址或网段。是否能拿到域名、是否先把域名解析成地址,都与应用提交的目标和内核策略有关。访问同一服务的域名与直接连接它的地址,未必命中同一规则。遇到只对部分站点生效的现象,先看实际请求的目标,不要只对照浏览器标签页的标题。改规则前可以先导出当前路由,以便恢复原顺序。

将数据库、解析与节点更新分开

GeoSite 属于域名分类数据,GeoIP 属于地址分类数据。使用这些分类时,规则依赖内核实际加载的数据库和现有条目。数据库更新与订阅更新互不替代:前者改变规则匹配用的数据,后者更新节点列表。规则仍在但分类条目找不到时,先核对是否正在使用正确的一组数据库,以及当前内核能否读取;不要把更新后的数据文件随意放进任意一个旧目录。

域名无法解析时,也不必立即更换所有解析设置。先判断失败的是订阅服务、节点服务器还是测试目标,再看失败发生在应用、系统还是内核这一侧。有些应用使用自己的解析方式,系统解析通畅不能证明该应用也正常。先记录现象,再只改一项并复测。对路由数据格式有疑问,可查阅GeoIP 与 GeoSite 数据库更新说明。

07故障排查

配置常见问题与恢复方法

先确认最近一次变更

从最后一次正常使用开始回溯:是否升级了客户端、替换过内核、修改过订阅、切过无线网络,或调整了系统代理。把最后一次改动与首次失败的时间分开记录。能够恢复时,优先撤回最近一项改动,再用原节点和原测试目标复测。若同时卸载、改解析和重设路由,即使偶然恢复,也难以判断下次遇到同类问题该如何处理。

按症状选择检查入口

订阅更新失败,应该先查地址还是节点?

先查订阅地址与拉取路径。对比原始地址是否完整,尤其注意复制时混入的空格、换行或末尾标点。登录页、错误页和空响应都可能下载成功,却无法解析成配置。根据客户端能提供的错误区分请求未送达、服务器拒绝访问和内容格式不匹配,再考虑切换更新路径。

如果旧分组还有节点,先保留它。旧节点能连接,不代表订阅仍可更新;订阅更新失败,也不说明所有旧节点已经失效。只有当前网络能直接访问订阅服务时,不通过代理更新才有意义。需要借助已有连接时,先用保留的可用节点恢复代理,再尝试更新。若两种路径都返回拒绝,确认地址有效期和访问条件,不要反复粘贴或公开地址求助。

节点已导入,为什么仍然无法连接?

先确认它已设为当前节点,且客户端已经启动连接。若内核启动即退出,用报错定位配置字段、文件路径或本地端口;若只在发起请求时出现超时,则进一步看是节点地址解析、远端端口连通还是握手失败。列表测试和实际应用请求可能走的是不同路径,不宜把测试图标当作最终判断。

只对某个节点报握手错误时,核对来源配置声明的协议、传输方式、安全设置与服务器名称,确认系统时间准确。单靠修改端口或开启忽略证书错误,既无法确认原因,也可能让问题更难定位。如果同一订阅里另一个节点能在同一网络和模式下工作,先保留这个对照,再回到单个节点检查,不必重装客户端。

为什么浏览器能访问,其他应用却不能?

先看失败应用是否跟随系统代理,或是否配置了自己的代理。桌面软件可以使用独立网络设置,终端也可能持有上一会话写入的环境变量。移动端还要确认应用没有被排除在接管名单之外。完全退出该应用后重新发出请求,同时观察客户端是否收到了对应请求。

若日志里能看到请求,继续查命中的路由和目标响应;若没有记录,先确认日志级别,再判断接管范围。能给应用单独设置代理时,先用本地地址做一个可撤回的测试。确有需要才切换 TUN,并留下可随时恢复的旧设置。单个应用的失败不等于系统代理配置错误,也不必把正常应用一并切到另一种模式。

升级或换设备后,怎样恢复分组和路由?

先打开备份并区分三类内容:可由订阅重新拉取的节点、单独保存的手工链接、与本机有关的入站及路由设置。新设备先用最少的配置完成连接验证,再逐段迁移。订阅分组可用原地址重建;手工节点逐条导入;涉及本地端口、虚拟接口或特定内核的路由则应参照当前设备重新设置。

不要把整个旧配置直接覆盖到另一套客户端上。即使两端都能识别部分节点,也可能对默认出口、按应用名单和数据文件路径有不同预期。多个订阅共存时,可先按来源整理,再用订阅分组与节点过滤指南清理重复项。验证完成后保留一份可正常启动的备份,再移除旧配置。

退出后断网时,恢复本机设置

客户端已经退出、所有浏览器仍无法访问时,先查看代理是否还指向本机端口。仅撤回本次写入的代理设置,恢复原来的手动代理、自动配置脚本或直连状态。用过 TUN 的设备,再看虚拟接口是否仍由旧进程占用。手机上检查系统 VPN 是否仍显示已连接,是否启用了禁止非 VPN 连接,以及这些选项是否由设备管理员控制。

恢复后用两个独立的目标测试:一个平时能打开的本地服务,再加一个稳定的互联网目标。先确认网络层恢复,再考虑重新打开客户端。如果不同平台都在同一个网络中失败,但改用另一条正常网络后能工作,就记录网络切换前后的结果,不要先怀疑每台设备的安装包。要求协助时,提供平台和架构、客户端与界面类型、接管方式、错误类别及已做过的对照,避免张贴完整日志。

下载客户端