适合第一次配置 v2rayN 7.x 的 Windows 与 macOS 用户。按顺序完成架构选择、运行环境检查、核心设置、订阅导入、系统代理和开机启动，并通过本地端口与日志判断连接究竟卡在哪一步。
一、下载前先确认系统架构与运行方式
v2rayN 是桌面端图形客户端，负责管理订阅、节点、路由规则和系统代理，实际协议连接由 Xray 或 v2fly 等核心进程完成。首次安装时，客户端界面能够打开，不等于核心已经正常运行；后续必须同时检查主程序、核心文件和本地监听端口。
下载前先查看设备架构。Windows 可打开「设置」→「系统」→「系统信息」，在“系统类型”中确认 x64 或 ARM64；macOS 可打开左上角系统菜单中的“关于本机”，确认设备使用 Apple 芯片还是 Intel 处理器。架构选错时，常见结果是程序无法启动、核心立即退出，或者系统提示应用不兼容。
-
确认架构
Windows 查看“系统类型”，macOS 查看处理器信息；x64、ARM64 安装包不能随意混用。
-
获取客户端
进入本站下载中心，按当前桌面系统选择 v2rayN 7.x 对应版本，不要使用安卓客户端包替代桌面程序。
-
完整解压
压缩包必须全部解压到独立目录。Windows 可放在用户目录下，避免直接放入需要持续提权写入的位置。
-
检查运行库
若选择依赖运行环境的版本，按启动提示安装匹配的 .NET 8 Desktop Runtime；自包含版本通常无需单独安装。
-
首次启动
Windows 运行主程序；macOS 将应用放入“应用程序”后启动，并根据系统提示确认打开权限。
-
保留原目录
启动后不要移动单个可执行文件。核心、配置、日志与主程序应保持在完整目录结构中。
Windows 出现“缺少运行环境”时，应先区分下载的是依赖运行库版本还是自包含版本。反复以管理员身份启动不能补齐缺失组件。macOS 首次阻止打开时，可进入「系统设置」→「隐私与安全性」，核对被拦截应用名称后使用系统提供的“仍要打开”操作；不要通过删除安全属性来绕过来源确认。
二、首次启动先选核心，再调整基础参数
进入主界面后，先打开「设置」→「参数设置」→「Core 类型」。如果订阅包含 VLESS、Reality、XTLS Vision 等配置，应优先选择 Xray 内核；只使用传统 VMess 配置时，v2fly 内核也能完成基础连接。核心类型必须与节点协议及传输参数兼容，否则节点能够导入，却会在启动阶段报“不支持的字段”或直接退出。
Xray 内核
推荐覆盖 VMess、VLESS、Reality、WebSocket、gRPC 等常见配置，适合作为 v2rayN 7.x 的日常默认核心。
适合:新订阅、VLESS 节点、Reality 节点
v2fly 内核
适合以 VMess、TCP、WebSocket、TLS 为主的既有配置，遇到 Xray 专属字段时不能直接替代。
适合:传统 VMess 节点、既有 v2fly 配置
基础参数不需要一次改完。建议先保留默认日志级别，确认本地 SOCKS 端口和 HTTP 端口，再决定是否开启开机启动。常见配置以 10808 作为 SOCKS 端口、10809 作为 HTTP 端口，但实际值必须以「设置」→「参数设置」中显示的本地监听设置为准。
- Core 类型：常规新配置选择 Xray，只有明确需要兼容既有 v2fly 配置时再切换。
- 本地地址：只供本机使用时保持
127.0.0.1，不要为了排查问题直接改为全网卡监听。 - SOCKS 端口：示例为
10808，供支持 SOCKS5 的应用单独填写。 - HTTP 端口：示例为
10809，可供浏览器、命令行工具或系统代理使用。 - 日志级别：首次配置保留 info；定位失败时短暂切到 debug，排查完成后恢复，避免日志快速增长。
三、导入订阅并检查节点字段
准备好完整订阅链接后，在主界面进入「订阅分组」→「订阅分组设置」→「添加」。填写分组备注并粘贴链接，保存后执行“更新全部订阅”。不同 7.x 小版本的按钮位置可能略有调整，但操作顺序始终是先创建订阅分组，再触发更新，而不是把订阅地址当作单个节点链接直接导入。
更新成功的最低判断标准不是弹出“完成”，而是主列表出现节点，并且协议、地址、端口、传输方式等列存在有效值。若列表为空，先检查链接首尾是否夹带空格、复制内容是否被聊天工具截断，以及订阅服务是否要求先通过已有代理更新。
VLESS + Reality
- 核心
- Xray
- 传输
- TCP
- Flow
- xtls-rprx-vision
- 指纹
- chrome
公钥、短 ID、Server Name 通常由订阅自动写入，缺少任一关键字段都可能握手失败。
VMess + WS + TLS
- 核心
- Xray 或 v2fly
- 传输
- WebSocket
- 路径
- 以订阅值为准
- TLS
- 开启
Host、路径和端口必须与服务端一致，不要根据其他节点的写法手工猜测。
本地 SOCKS
- 地址
- 127.0.0.1
- 端口
- 10808
- 协议
- SOCKS5
- 范围
- 仅本机
适合在支持 SOCKS5 的应用中单独填写，端口以客户端当前设置为准。
本地 HTTP
- 地址
- 127.0.0.1
- 端口
- 10809
- 协议
- HTTP Proxy
- 范围
- 仅本机
适合系统代理与命令行测试，不要误填成远端节点端口。
节点导入后，选择一个节点并设为活动服务器，再观察底部状态与核心日志。连接过程通常会经历生成配置、启动核心、本地端口监听三个阶段。若日志在生成配置前终止，优先检查节点字段；若提示地址已被使用，则是本地端口冲突；若核心正常监听但连接超时，再检查节点可用性、网络路径和系统代理。
四、系统代理与开机启动要分开设置
v2rayN 核心启动后，只是让本机出现了可用的代理端口，并不会自动保证所有软件都经过该端口。需要让遵循系统网络设置的浏览器和应用使用代理，还要在 v2rayN 托盘菜单或系统代理功能中选择“自动配置系统代理”。退出客户端前应恢复系统代理，避免系统继续指向已经停止监听的 127.0.0.1:10809。
推荐方案:先手动验证，再启用开机启动
Windows
- 先启动核心并切换系统代理
- 在「设置」→「参数设置」中启用开机启动
- 重启后检查托盘图标与 10808、10809 端口
- 系统提示防火墙权限时核对程序名称与网络范围
macOS
- 先允许应用修改系统代理配置
- 启用登录启动后检查系统登录项
- 重新登录并确认菜单栏状态
- 退出前恢复系统网络代理设置
只有手动启动、节点连接和系统代理都验证通过后，才开启自动启动；这样能把启动项问题与节点问题分开定位。
Windows 的“以管理员身份运行”和“开机自动启动”不是同一件事。普通本机代理通常不要求每次提权；只有防火墙规则、受保护目录写入或特定系统设置需要授权时，系统才会提示。长期把程序放在受保护目录，可能使配置保存与自动更新反复触发权限问题，因此更适合放在当前用户可读写的固定目录。
macOS 开启登录启动后，还应进入「系统设置」中的登录项页面核对 v2rayN 是否获准后台启动。若登录后程序已运行但代理未生效，要分别查看核心是否启动、活动节点是否保留、系统代理是否切换，不能只凭菜单栏图标判断连接状态。
| 检查项目 | Windows | macOS |
|---|---|---|
| 程序启动 | 查看任务栏托盘与进程 | 查看菜单栏与活动监视器 |
| 核心监听 | 确认 127.0.0.1:10808 或 10809 | 确认 127.0.0.1:10808 或 10809 |
| 系统代理 | 核对系统网络代理状态 | 核对当前网络服务的代理状态 |
| 自动启动 | 重启后检查托盘程序 | 重新登录后检查登录项 |
五、用端口、命令与日志完成首次验收
首次配置完成后，建议做两轮测试。第一轮绕过系统代理，直接把请求发送到 v2rayN 的 HTTP 端口，用于确认核心与节点是否工作；第二轮再开启系统代理，用浏览器访问站点，确认系统设置已经正确指向本地端口。这样可以避免把节点故障、端口冲突和系统代理错误混成一个问题。
Windows 查看 10809 端口:
netstat -ano | findstr 10809
macOS 查看 10809 端口:
lsof -nP -iTCP:10809 -sTCP:LISTEN
通过本地 HTTP 代理测试:
curl --proxy http://127.0.0.1:10809 https://v2raymap.com/若端口命令没有任何输出，说明核心没有监听该端口，先回到 v2rayN 检查核心日志和本地端口设置。若端口存在，但 curl 返回连接被拒绝，检查输入的是 HTTP 端口还是 SOCKS 端口；使用 SOCKS5 测试时，应将参数改为对应的 SOCKS5 代理形式，并使用实际端口。
订阅更新一直提示超时？
先确认订阅链接能够完整读取。若更新通道需要代理，先连接一个已知可用节点，再在订阅分组设置中启用通过代理更新并重试。
节点启动了但网页打不开？
先执行端口测试。若 10809 正常监听，再检查系统代理是否指向 127.0.0.1:10809，以及浏览器是否使用系统网络设置。
日志提示地址已被占用？
关闭占用 10808 或 10809 的旧进程，或者在「设置」→「参数设置」中换成未占用端口，例如 11808 与 11809，并同步修改系统代理。
重启电脑后代理失效？
分别确认 v2rayN 已自动启动、核心已运行、活动节点仍被选中、系统代理已切换。四项中任何一项缺失都会表现为重启后无法访问。
切换核心后节点报错？
检查节点协议是否依赖 Xray 字段。VLESS、Reality 或 xtls-rprx-vision 配置应切回 Xray，并重新启动核心后读取最新日志。
日志排查应从第一条明确错误开始，而不是只看最后一行。端口占用通常包含“address already in use”，节点字段不兼容会指出具体配置项，域名解析或远端连接失败则常见 timeout、connection refused 等信息。记录错误发生时间，再对照刚执行的操作，定位速度会比连续切换节点更快。
六、Windows 与 macOS 最常见的安装坑
双平台的共同问题主要集中在目录不完整、架构不匹配、运行环境缺失和端口设置不一致。Windows 还容易受到受保护目录写入、防火墙授权和旧进程残留影响；macOS 则更常见首次打开许可、登录项未批准和系统代理退出后未恢复。
| 现象 | 可能原因 | 处理顺序 |
|---|---|---|
| 双击后没有主窗口 | 架构选错、运行库缺失、程序仍在后台 | 核对 x64 或 ARM64，再检查进程与 .NET 8 运行环境 |
| 核心启动后立即退出 | 核心文件缺失、协议字段不兼容 | 重新完整解压，再查看第一条核心错误并核对 Core 类型 |
| 更新订阅后列表为空 | 链接截断、分组未保存、返回内容异常 | 重新复制完整链接，保存分组后执行更新全部订阅 |
| 退出后所有网页都打不开 | 系统代理仍指向已关闭的本地端口 | 恢复系统代理，确认 127.0.0.1:10809 不再被强制使用 |
| 开机后图标存在但不能连接 | 核心未启动、节点未选中、代理未切换 | 按主程序、核心、活动节点、系统代理四层逐项检查 |
完成安装后，建议保留一组可复现的基线：Core 类型为 Xray，本地地址为 127.0.0.1，SOCKS 与 HTTP 端口分别记录为实际值，至少一个节点能够通过命令行测试，系统代理可以手动开启和恢复。只有这组基线稳定后，再添加路由分流、局域网共享或更复杂的规则。
- 更新客户端前备份订阅分组、路由规则和自定义设置。
- 更换端口后，同步修改系统代理与所有手工填写代理的应用。
- 节点不可用时先换同订阅中的另一个节点，不要立即重装客户端。
- 订阅更新失败与节点连接失败是两条不同链路，应分别查看错误。
- 退出程序前恢复系统代理，避免留下指向本地空端口的网络设置。