全平台指南 · 安装与配置

V2Ray 全平台安装配置指南

第一次配置时,先用快速上手教程走完导入、连接和验证。本页是按平台查阅的手册:从对应章节开始,遇到跨平台的问题,再回查订阅、代理入口和故障排查。桌面端首选 v2rayN,安卓端首选 v2rayNG。

通用准备:包型、订阅与权限

本章设置速查
项目查看位置建议
系统与架构系统信息先确认架构,再选安装包
订阅地址提供方账户或文档整条复制,不公开分享
首次验证客户端日志和浏览器先验证单个节点,再调整接管方式

选包看实际架构,不看设备系列

在获取客户端页先选操作系统,再核对架构和包格式。x64 与 x86-64 指同一类架构,arm64 常在系统信息中显示为 AArch64。两者不能仅凭系统名称判断。桌面设备的处理器品牌也不等于发行包名称;例如 Linux 包写着 amd64 时,通常也适用于同架构的 Intel 处理器。下载页有时只列该平台的一部分架构。若没有匹配入口,先确认系统类型和发行说明,不要把另一个平台的安装包当作替代。旧设备还应确认系统版本和客户端最低要求是否匹配。

分清订阅、节点和代理入口

订阅地址用来取得节点列表;节点条目保存协议、目标地址、端口和传输参数;本地代理入口则供本机应用把流量交给客户端。这三者不是同一个地址。订阅更新成功只代表取到了可识别的数据,不代表每条节点都能建立连接。反过来,订阅站点暂时打不开时,已导入的节点也不一定立即失效。记录故障时,先写清失败的是更新、启动内核,还是访问目标,再决定要检查哪一层。

导入前确认拿到的是订阅地址还是单节点分享链接。前者添加到订阅分组并手动更新;后者走剪贴板或扫码导入。节点分享码和订阅地址都可能含访问凭据,不要把它们粘贴到在线解析器,也不要把包含二维码的截图发进公开讨论。用来源或用途为分组命名,便于区分手工节点与订阅节点。修改订阅前,先记下当前活动节点和分组;更新可能重建条目,手改订阅节点的参数也可能被覆盖。

先定测试基线,再改变设置

开始前记录系统代理原状态、有无其他正在运行的网络接管工具,以及客户端当前接管模式。单位代理、固定脚本和手工例外规则都可能有用途,不能把它们当作安装前应清除的残留。测试时选一个平时可访问的 HTTPS 页面作为固定目标。保持同一网络、同一节点和同一浏览器,先看关闭接管时的表现,再只改变一项设置。若浏览器安装了代理扩展或使用独立的代理配置,验证前先确认它是否覆盖系统设置。桌面端在系统代理验证通过之前,不需要急着启用 TUN;安卓端则用系统 VPN 授权建立接管。

首次连接不要同时启用自定义 DNS、手写路由和开机启动。能连通以后,逐项加入确实需要的设置,每改一项就重复同一个测试。观察时同时看客户端日志和实际页面:托盘图标变色只能证明界面状态发生变化,页面正常加载也可能来自缓存。重新请求页面并核对相同时间段的日志,才能确认请求确实进入预期入口。若需要向他人求助,提供平台、包类型、故障阶段和脱敏后的错误信息,不提供完整配置导出。

Windows:v2rayN 桌面版与 WPF 版

本章设置速查
设置项候选项建议
发行形态桌面版 / WPF 版新部署从桌面版开始;按需选 WPF
系统代理自动配置 / 清除先验证读取系统代理的应用
TUN开启 / 关闭确认权限与路由需求后再启用

选择界面版本与运行位置

进入Windows 下载入口,在 v2rayN 桌面版与经典 WPF 版之间选一个。桌面版采用跨平台界面,方便在不同桌面系统间沿用操作习惯;WPF 版适合熟悉经典 Windows 界面、依赖现有工作流程的用户。两者的区别首先是界面和运行环境,而不是订阅地址的种类。同一台机器切换两种发行形态时,先从托盘真正退出旧客户端,避免两个内核同时尝试占用本地端口,也避免两个进程轮流改写系统代理。

如果下载的是压缩包,先完整解压到当前账户可写的目录,再运行主程序,不要直接在压缩文件的预览窗口里启动。如果下载的是安装程序,按安装界面操作,随后从开始菜单或已建立的快捷方式打开。启动报缺少运行组件时,先记录报错中的运行时名称和架构,按该发行形态的说明补齐;不要从搜索结果单独下载同名库文件塞进应用目录。遇到组织安全策略阻止执行时,请向设备管理员确认许可,不要通过停用防护强行安装。

导入分组并设置系统代理

打开订阅分组设置,添加名称和完整订阅地址,保存后执行该分组的更新。界面中出现节点后,点选一个条目并设为活动服务器。先查看日志是否有内核启动失败或端口绑定错误,再从托盘选择「自动配置系统代理」。在 Windows 的网络设置中核对代理状态,用浏览器访问固定测试目标。若系统代理地址已写入而浏览器不走代理,检查浏览器代理扩展、应用自己的联网选项及受管理策略。关闭主窗口常常只是缩到托盘,不等于退出或恢复之前的系统设置。

处理 TUN、端口占用与退出残留

需要接管不读取系统代理的应用时,先记录当前配置,再根据界面提示授权 TUN 所需权限。初始化失败时,查看日志能否区分虚拟接口创建失败、路由变更失败和内核启动失败。先退出其他已接管网络的客户端做单独测试,不要长期让两个接管工具竞争相同的默认路径。启用后也要检查局域网资源和工作网络是否仍按原计划可达;若接管范围超出预期,先关闭 TUN 恢复基线,再单独调整路由。

以下命令在 PowerShell 中查看 TCP 监听。数字仅用于检查常见的本地 SOCKS 端口;如果客户端界面显示不同值,就用界面的实际值。输出中的 OwningProcess 可与任务管理器的进程 ID 对照。没有输出只代表未看到这个端口的 TCP 监听,不能据此判断远端服务器在线与否。

Get-NetTCPConnection -State Listen -LocalPort 10808 -ErrorAction SilentlyContinue

若端口已被占用,先认清进程是旧内核、另一个本地服务,还是本次客户端本身。需要更换监听端口时,要同步更新手工填写过地址的应用。若客户端退出后网页才开始失败,优先检查系统是否仍指向已停止的本地代理。原来使用组织代理的设备应还原原配置,而非一律清空。有关界面选择和安装分支,可补读Windows 桌面版与 WPF 版安装说明。

macOS:芯片选包与网络服务

本章设置速查
项目查看位置建议
芯片关于本机Apple Silicon 选 arm64,Intel 选 x64
系统代理当前网络服务的代理设置切换网络服务后复查
TUN客户端开关与日志单独验证权限及路由

安装到应用程序目录,再首次打开

在系统菜单选择「关于本机」,确认显示的是 Apple 芯片还是 Intel 处理器,再到macOS 下载入口选相应的 v2rayN 磁盘映像。不要仅根据电脑购买年份判断,也不必为原生包改装其他架构的运行环境。打开下载的映像后,按窗口提示把应用复制到「应用程序」,从复制后的副本启动,再推出映像。如果应用一直在映像卷中运行,后续替换和启动路径会难以判断;若有多个副本,先退出旧副本并确认打开的是刚复制的那一个。

遇到首次启动提示,先读清楚是架构不适配、系统版本过旧、来源未被识别,还是设备管理策略阻止。不同情况不能用同一种办法处理。确认来源及设备规则后,只使用系统允许的单应用授权流程;由组织管理的设备应联系管理员。不要全局更改系统的应用审查设置。应用窗口打开后如果内核无法启动,先看日志报告的是执行权限、运行组件还是配置解析问题,不要把窗口能打开当作安装已经完全成功。

导入订阅并核对当前服务

在 v2rayN 新建订阅分组,粘贴完整地址,保存并手动更新。选择活动节点后先看本地监听,再开启自动配置系统代理。进入系统设置中的「网络」,查看正在使用的 Wi-Fi 或有线服务,打开其详细信息中的「代理」。代理配置是按网络服务保存的:两项服务同时存在时,不要只核对列表中排在第一项的服务。系统版本或界面语言不同,菜单名称可能有差异,应以当前服务实际显示的设置为准。

如果在办公室通过有线网络配置,回家切到 Wi-Fi 后发现应用行为不一致,先重新核对 Wi-Fi 服务的代理状态,并确认客户端是否重新应用了设置。也要留意网络是否需要先完成网页认证:此时订阅更新失败不一定是节点故障。下面两条命令只读取网络状态,前者用于查看网络服务顺序及服务与设备的对应关系,后者用于查看当前系统代理摘要。看到代理开关已开启时,再与客户端显示的本地端口比对;摘要正常也不代表每个应用都会使用它。

networksetup -listnetworkserviceorder
scutil --proxy

验证 TUN 与睡眠唤醒后的状态

对不读取系统代理的应用,若当前发行包提供 TUN,先关闭用于对照的系统代理,再从客户端启用 TUN,按提示完成授权。依次核对接口初始化、固定目标请求以及应保持直连的本地资源。设备上已有 VPN、代理配置或受管理的过滤组件时,不要擅自停用组织配置;可在允许的网络和设备上单独验证。既有连接在切换模式后不一定立刻重建,所以应退出测试应用或重新发起连接,而不是只观察之前已打开的页面。

休眠唤醒或换网后若出现间歇失败,先记录进入睡眠前使用的接口和唤醒后的实际接口,再看是否只有旧连接异常。如果新建连接也失败,检查客户端内核是否仍运行,网络服务代理是否仍指向有效监听,以及 TUN 是否已经重新建立。恢复时优先通过客户端关闭对应模式,再核实当前网络服务状态,不要重置所有网络偏好。能稳定重现问题后,再决定是否启用登录时启动;先配置自启会让残留设置和启动顺序问题更难区分。

Linux:deb、rpm 与桌面会话

本章设置速查
项目候选项建议
包格式deb / rpm按发行版包管理体系选择
环境代理桌面代理 / 进程变量区分图形应用与终端程序
虚拟接口TUN先确认接口支持及权限

按发行版和处理器架构安装

Debian、Ubuntu 通常选 deb;Fedora、openSUSE 使用 rpm,但同为 rpm 不意味着依赖完全相同。打开Linux 下载入口,先看发行说明适用的系统,再选 x64 或 arm64。可运行 uname -m 查看机器架构,并用 cat /etc/os-release 确认发行版。如果在容器或远程主机上运行这些命令,要注意观察到的是那个环境的信息,不一定是实际要运行图形客户端的桌面。不要为了安装某个包而把别的发行版的软件源直接混入系统。

优先用桌面软件安装器打开本地发行包。需要通过终端安装时,下面分别是 Debian 系、Fedora 和 openSUSE 的本地包安装写法,三条只选对应的一条。示例假定已把选中的真实安装包放在当前目录并重命名为对应的短文件名;也可以直接替换为实际路径,路径含空格时用引号包住。包管理器应能报告依赖缺失或冲突,不要用忽略依赖的方式跳过检查。

sudo apt install ./v2rayn.deb
sudo dnf install ./v2rayn.rpm
sudo zypper install ./v2rayn.rpm

在实际使用的桌面会话中导入和验证

安装完成后,从应用菜单以日常登录账户打开 v2rayN。安装时获得的管理权限不等于日常运行图形界面也要用管理员账户。用普通账户添加订阅分组,手动更新,选定活动节点,再核对日志中内核和监听是否就绪。若软件菜单中找不到入口,先看安装事务是否完成,再重新进入桌面会话确认菜单更新;不要用管理员身份从另一个用户的配置目录启动来掩盖路径或权限问题。

GNOME 与 KDE Plasma 的系统代理设置不一定由同一套配置接口管理,终端程序也可能只读取进程变量或自己的配置。有些应用在启动时读取代理,修改桌面代理后需要重新打开应用才能复测。浏览器能访问而包管理器不行时,先明确后者读取哪个代理来源;管理员进程未必继承普通用户的环境变量。下面只检查本机监听,不改变桌面或终端的代理设置。若界面中的端口不是这个值,按实际端口修改条件。

ss -ltn 'sport = :10808'

检查虚拟接口与登录自启

需要 TUN 时,先确认系统提供 /dev/net/tun,同时查看客户端请求的权限是否已按发行说明授予。设备路径存在并不代表当前进程一定能打开它,也不代表进程可以修改系统路由。在容器或受管会话中,接口和路由权限还受宿主环境控制。日志若提示创建接口失败,先分辨设备不可用和权限不足;若接口已经建立但某个目标仍失败,应检查路由与 DNS,而不是继续扩大应用权限。

手动连接稳定后再配置登录自启。桌面会话自启与开机启动系统服务不是一回事:前者能在正确的用户会话中使用图形设置,后者可能在登录前运行,既不读取同一份桌面代理设置,也未必使用同一个用户目录。验证自启时注销再登录,观察托盘、活动节点和日志,而不是看到后台进程就认定系统代理已生效。若仅在自启时失败,先检查网络就绪顺序和旧进程重复启动。另见Linux 包部署与自启动说明。

Android:订阅分组与 VPN 接管

本章设置速查
项目候选项建议
客户端v2rayNG / v2flyNG首选 v2rayNG;按协议需求选备选
APK 架构arm64 / 通用版确认系统支持 arm64 后再选专用包
接管方式Android VPN 服务首次启动时核对授权应用

选择客户端、架构与安装来源

进入Android 下载入口,优先选择使用 Xray 内核的 v2rayNG;有明确的 V2Fly 内核需求时再考虑 v2flyNG。两款客户端可以读取的节点类型和选项不完全相同。换客户端之前先核对订阅协议和传输要求,不要仅凭能否导入来判断能否连接。多数较新的 Android 手机可先确认 arm64 安装条件;如果不清楚系统支持的应用架构,可选通用包。处理器支持六十四位并不保证系统允许安装对应架构的应用。

打开下载的 APK 后,系统可能要求授权当前安装来源,例如浏览器或文件管理器。只对实际打开安装包的来源按需授权,完成后可撤回临时授权。若设备由单位管理而禁止此类安装,先确认设备规则。安装失败时区分包不适配、存储不足和旧应用无法覆盖;不要在没有备份的情况下直接卸载,订阅、手工节点和分应用设置都可能随卸载清除。

添加订阅、更新列表与启动服务

在 v2rayNG 找到订阅分组管理入口,新增分组并填入完整订阅地址。返回列表后执行订阅更新,检查结果是否出现在该分组中,再点选一个节点。若提供的是二维码,确认它是单节点链接还是订阅入口,再用客户端提供的相应导入功能;不要使用会上传图片的识别服务。手工导入的节点与订阅分组建议分开管理,避免更新后误以为原来选中的节点已经丢失。

启动连接时,Android 会显示 VPN 连接请求。确认请求来自当前选定的客户端后再同意。这个授权让客户端通过系统提供的虚拟网络接口接收流量,不需要去改 Wi-Fi 的手工代理。状态栏的 VPN 指示只表示服务已建立,不能证明活动节点握手成功。先关闭可能覆盖连接路径的其他网络工具,用浏览器新开一个页面,再与客户端的同一时间段日志对照。需要区分 Wi-Fi 与移动数据时,每次只切换网络,保留同一个节点和同一测试应用。

分应用、始终开启与后台断连

需要分应用时,先读清界面当前是「只允许名单内应用」还是「排除名单内应用」。同一个浏览器出现在名单上,在两种模式下含义相反。先只用一个测试应用验证,再加入其他应用。若目标应用位于工作资料空间或由设备策略管理,普通个人空间中的客户端未必能接管它。不要为了排查一个应用而一开始就同时开启分应用、始终开启 VPN 和断开时阻止连接。

切到后台或熄屏后断连时,先看通知和客户端日志:是服务被停止、网络从 Wi-Fi 切到移动数据,还是节点仍已选中但新连接失败。仅当证据指向后台限制时,再按系统允许的方式检查该客户端的电池用量限制与后台运行设置。若所有应用都突然打不开,核对系统当前绑定的是哪一个 VPN 应用,以及是否打开了断开时阻止网络的选项;恢复前先确认这些设置是不是自己或管理员配置的。对比 v2rayNG 与 v2flyNG 时,一次只运行一个,避免误把系统切换 VPN 的结果当成节点掉线。

系统代理与 TUN:接管范围与验证

本章设置速查
入口适用范围建议
系统代理读取系统代理的应用桌面首次连接优先验证
本地 SOCKS支持手动指定 SOCKS 的应用诊断单个应用时使用
TUN进入虚拟接口的流量核对路由与 DNS 后再扩大范围

系统代理决定入口,路由决定出口

桌面客户端的系统代理开关通常用于把操作系统的代理设置指向本地监听。应用需要主动读取这项设置,才会把请求交给客户端。一个浏览器走了代理,并不意味着终端、后台更新器或局域网应用也采用相同入口。客户端的路由设置处理的是已经交给它的请求:它可以根据域名、地址或其他匹配条件选择代理、直连或阻止。把路由策略改为全局并不能要求忽略系统代理的应用主动送来流量;反过来,启用 TUN 也不等于每个目标都一定走远端节点。

用单次请求隔离本地代理测试

如果桌面系统已经安装 curl,可暂时绕开系统代理的选择过程,直接指定本机 SOCKS 地址测试。命令使用保留作示例的公开域名;实际排查可替换为已知可访问的 HTTPS 目标。先确认客户端提供的是 SOCKS 入口,端口与界面相符,不要把 HTTP 代理端口或远端节点端口填进去。在 Windows PowerShell 中可使用 curl.exe,以免调用同名别名。示例中的 socks5h 会把目标主机名交给 SOCKS 服务处理,而不是让 curl 先在本机解析;这不等于客户端后续必然采用某个指定的 DNS 服务。

curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/

如果明确报本地连接被拒绝,先查监听端口和进程状态。若已进入本地服务但等待目标响应超时,再看日志中的路由和远端连接。若收到目标的 HTTP 响应,说明这次请求已取得应用层回应,但不能据此判断其他目标、其他应用或 UDP 流量是否正常。若目标不接受 HEAD 请求,仍可用一个正常 GET 请求复测。做完诊断不要顺手把本地监听改为允许局域网连接;同机测试只需要回环地址,开放给其他设备会改变访问范围。

启用 TUN 后验证路由和 DNS

TUN 以虚拟网络接口承接被操作系统路由引入的流量。先在系统代理关闭的对照状态下使用同一测试应用,再单独启用 TUN。验证三个对象:需要接管的应用、应保持直连的本地服务、按域名访问的测试目标。若局域网资源只在 TUN 开启时失败,优先检查局域网网段和接口选择;若目标域名失败但网络本身可达,再看 DNS 请求的处理路径。不要用裸 IP 替代 HTTPS 域名作最终验证,因为证书、虚拟主机与路由规则可能依赖域名。

在受支持的内核和配置中,FakeDNS 可为域名返回虚拟地址,并在连接进入客户端后借助映射找回原域名。这个机制要求查询和连接的处理路径能配合;若应用自行解析、缓存跨越模式切换,或虚拟地址没有进入预期接口,结果可能和预想不同。普通安装无需主动打开该功能。只有确定需要按域名处理特定流量时,才有理由评估它;先记录关闭时的表现,再改变这一项。原理参见FakeDNS 虚拟地址映射说明,术语参见术语表。

配置常见问题:按失败阶段排查

本章设置速查
症状先查下一步
列表为空订阅更新结果核对分组和返回内容类型
本地连接被拒绝客户端监听查端口、进程和启动错误
仅个别应用失败应用是否进入客户端比较系统代理、TUN 和分应用设置

先取证:记录一轮可复现的测试

先把问题压缩成一句可验证的话,例如「同一个浏览器在关闭系统代理时能打开测试页,开启后本地监听报错」,而不是只写无法连接。记录检查时的网络、代理模式、活动分组与测试目标,并截取覆盖这次请求的少量日志。日志里如果有订阅查询参数、账号标记或节点地址,发给他人前应遮去。复测时不要同时换网络、换节点和切换内核,否则即使恢复,也很难知道该保留哪项改动。

优先看第一条和故障相关的错误,而不是只看日志最后一行。配置解析失败、端口绑定失败和远端握手失败发生在不同阶段;如果前一阶段已经失败,后面的超时可能只是结果。单次延迟测试也不等于实际访问:测试可能只覆盖到服务器端口,或者使用不同的请求目标。应把延迟结果与测试类型、日志时间和真实应用表现一起判断。完整的由近到远顺序可参见节点超时与无法连接排查。

常见症状与下一步

订阅已添加,为什么没有节点?

保存分组只是保存地址,不代表已拉取内容。手动更新对应分组,先看日志是否报连接失败、拒绝访问或格式错误。若返回的是登录提示或普通网页,客户端可能无法解析出节点;应从提供方账户重新取得客户端可识别的订阅地址。更新成功而列表为空时,先确认当前筛选的分组就是刚更新的分组,并检查是否仍在搜索过滤状态。若旧列表尚可使用,不要在确认新订阅能导入之前删除旧分组。

列表有节点,但所有目标都连不上?

先检查系统时间和时区是否已同步,然后确认活动节点已选中、内核已启动、本地代理端口正在监听。发出一次固定目标请求:日志若完全没有对应记录,优先查应用代理入口;若已进入客户端,再区分目标解析、远端连接和传输握手。只在拿到提供方参数时才修正传输类型、服务名称或 TLS 设置。不要为消除证书错误而关闭验证;应回头核对时间、目标名称与节点原始配置。

切换节点或升级之后,问题才出现?

先用同一个旧节点做对照。如果只有更新过的条目失败,检查活动分组是否变更,提供方是否已调整端口或传输,以及客户端使用的内核是否支持该配置。若升级后所有节点都失败,优先确认是否打开了不同的程序副本、是否读取了原数据目录、是否有旧进程仍持有端口。恢复备份时先退出客户端,在确认格式兼容后再恢复对应数据;不要直接把不同发行形态的全部配置文件混在一起。

关闭窗口后无法上网,如何恢复?

先看客户端是否仍在托盘运行,区分关闭窗口、停止内核和真正退出。能打开客户端时,先用界面关闭启用过的接管模式,再查看系统代理是否仍指向本地端口。若客户端异常退出,可按准备阶段记录的状态恢复原来的代理、自动配置脚本或 VPN 设置。对已有单位代理的设备,不要把所有代理项一律删掉。恢复后用同一测试目标重新发出请求,再确认局域网资源也恢复正常。