V2rayU Documentation

V2rayU,基于v2ray核心的mac版客户端,用于科学上网,使用swift编写,支持trojan,vmess,shadowsocks,socks5等服务协议,支持订阅, 支持二维码,剪贴板导入,手动配置,二维码分享等

20,174 stars Unknown 1 file · ~11,226 tokens #anytls#clash#mac#macos#native#v2ray#v2rayu#vless
RAW Doc

Technical Documentation: yanue/V2rayU

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md)

V2rayU

macOS 平台下的代理客户端，基于 Xray-core 与 sing-box，支持 VMess、VLESS、Trojan、Shadowsocks、SSR、SOCKS5、Hysteria、Hysteria2、Tuic、AnyTLS、Naive 等多种协议。SwiftUI 编写，支持 macOS 14+。

旧版(5.0以下)基于 V2Ray-core 的项目请查看 master 分支。

功能特性

  • 多协议支持 — VMess、VLESS、Trojan、Shadowsocks、SSR、SOCKS5、Hysteria、Hysteria2、Tuic、AnyTLS、Naive 等
  • 双核心引擎 — 智能选择 Xray-core 或 sing-box，根据协议/传输/安全配置自动匹配最兼容的核心
  • 运行模式 — PAC 模式、全局代理、手动代理、TUN 模式（虚拟网卡全局代理）
  • 订阅管理 — 支持 V2Ray、SS、SSR 订阅，可自动更新
  • 导入方式 — 二维码扫码、剪贴板粘贴、本地文件、URL 导入
  • 路由规则 — 内置常见路由规则组，支持自定义
  • 组合负载均衡 — 多服务器组合与负载均衡
  • 兼容性规则引擎 — 自动检测核心版本对各协议/传输方式的支持能力
  • 延迟测试 — 内置 Ping / HTTP 延迟测试
  • 诊断工具 — 内置网络诊断功能
  • 自动更新 — 支持应用与核心自动更新
  • 多语言 — 中文简体、中文繁體、English

下载安装

从 Releases 下载最新 DMG 安装包

功能预览

运行模式

模式 说明
Global 设置系统 HTTP/HTTPS/SOCKS 代理为本地代理端口
PAC 基于 PAC 规则的自动代理，自动判断直连或走代理
Manual 手动模式，需配合浏览器插件（如 SwitchyOmega）使用
TUN 虚拟网卡级全局代理，所有流量经 sing-box 转发

核心引擎

V2rayU 根据配置自动选择最佳核心：

  • Xray-core — 成熟的代理核心，协议/传输方式支持丰富
  • sing-box — 通用代理平台，支持 TUN 模式、Hysteria、Hysteria2、Tuic、AnyTLS、Naive 等协议

通过内置的兼容性规则引擎（CoreCapabilityRules），自动检测核心版本对每个协议、传输方式和安全配置的支持情况，在不兼容时给出警告提示。

相关路径

路径 说明
~/.V2rayU/V2rayU.log 应用程序日志
~/.V2rayU/core.log 核心引擎日志
~/.V2rayU/tun.log TUN 模式日志
~/.V2rayU/config.json 当前核心配置文件
~/.V2rayU/tun.json TUN 模式配置文件
~/.V2rayU/.V2rayU.db SQLite 数据库（GRDB）
~/Library/LaunchAgents/yanue.v2rayu.xray-core.plist Xray-core LaunchAgent
~/Library/LaunchAgents/yanue.v2rayu.sing-box.plist sing-box LaunchAgent
/Library/LaunchDaemons/yanue.v2rayu.tun-helper.plist TUN 辅助 LaunchDaemon
/usr/local/v2rayu/ 核心二进制及辅助工具目录

构建

bash
git clone https://github.com/yanue/V2rayU.git
cd V2rayU

# 构建通用二进制 + DMG
./Build/build.sh

构建要求：Xcode 15+，macOS 14+ SDK。

测试

bash
# 运行单元测试
xcodebuild test -project V2rayU.xcodeproj -scheme V2rayU -destination 'platform=macOS'

# 运行兼容性测试
./Build/tests/run-compatibility-test.sh --download

技术栈

  • 语言: Swift 5+
  • UI 框架: SwiftUI + AppKit (菜单栏)
  • 数据库: GRDB (SQLite)
  • 本地 PAC 服务器: FlyingFox (HTTP)
  • 包管理: Swift Package Manager
  • 分析统计: Firebase / AppCenter

贡献

欢迎提交 Issue 和 Pull Request。请阅读 AGENTS.md 了解项目结构和开发指南。

License

GPLv3

致谢

  • Logo 设计：@小文
  • 感谢 opencode

Docs CompatibilityTestSystem (`Docs/CompatibilityTestSystem.md`)

V2rayU 跨版本兼容性测试系统设计

1. 概述

本系统旨在解决 Xray-core 和 sing-box 的多个历史版本与用户配置的兼容性问题。通过自动化测试覆盖所有显著变更的版本，确保 V2rayU 生成的配置能在对应核心版本上正常运行。

解决的问题

  1. 版本碎片化：用户可能使用任意版本的核心二进制，兼容规则需要验证
  2. 配置生成一致性：同一个 profile 配置在不同核心版本上生成的 JSON 是否有效
  3. 功能差异追踪：不同版本之间协议、传输方式的支持变化
  4. 兼容规则验证：当前 CoreCapabilityRules 中的版本边界定义是否准确

2. 版本覆盖范围

Xray-core

从 v1.8.0 到 v26.5.6，包含所有稳定版（非 draft、非 prerelease）。

版本线分为两个阶段：

  • 旧语义版本：v1.8.0 ~ v1.8.24（major=1 系列）
  • 日历版本：v24.9.30 ~ v26.5.6（major>=24 系列）

sing-box

从 v1.12.0 到 v1.13.12，包含所有稳定版。

3. 系统架构

text
┌──────────────────────────────────────────────────────────┐
│                    download-cores.sh                      │
│  GitHub Releases API → 下载 → 解压 → 命名 → 存储         │
└──────────────┬───────────────────────────────────────────┘
               │
               ▼
         Build/tests/bin/
    ┌──────────┴──────────┐
    ▼                     ▼
 xray-core/           sing-box/
  v1.8.0/              v1.12.0/
  v1.8.1/              v1.12.1/
  ...                  ...
  v26.5.6/             v1.13.12/

               │
               ▼
┌──────────────────────────────────────────────────────────┐
│              run-compatibility-test.sh                    │
│  1. xcodebuild test (V2rayUTests 目标)                    │
│  2. 收集测试结果                                          │
│  3. 生成 HTML/JSON 报告                                   │
└──────────────┬───────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────┐
│        V2rayUCompatibilityTest (Swift Testing)            │
│                                                           │
│  对于每个 profile × (coreType, coreVersion) 组合:          │
│  1. 检查能力规则预测的结果                                  │
│  2. 使用测试版核心二进制生成配置并启动                       │
│  3. 测试真实连通性                                         │
│  4. 记录结果到 JSON 报告                                   │
└──────────────────────────────────────────────────────────┘

4. 核心组件设计

4.1 CoreDownloader — 核心下载器

位置：Build/tests/download-cores.sh

功能：

  • 通过 GitHub Releases API 获取指定 repo 的发布列表
  • 过滤出稳定版（!draft && !prerelease）
  • 匹配版本范围
  • 下载对应平台的二进制包（arm64 优先）
  • 解压并重命名为统一格式
  • 存储到 Build/tests/bin/{core}/{version_tag}/binary

版本过滤规则：

核心 最低版本 最高版本 版本格式
Xray-core v1.8.0 v26.5.6 v{major}.{minor}.{patch}
sing-box v1.12.0 v1.13.12 v{major}.{minor}.{patch}

下载目录结构：

text
Build/tests/bin/
├── xray-core/
│   ├── v1.8.0/
│   │   └── xray-arm64    # 解压后的可执行文件
│   ├── v1.8.1/
│   └── ...
└── sing-box/
    ├── v1.12.0/
    │   └── sing-box-arm64
    └── ...

4.2 CompatibilityTestRunner — 测试运行器

位置：V2rayUTests/CompatibilityTestRunner.swift

功能：

  • 从 Store 读取所有 profile 配置
  • 枚举待测的核心版本列表
  • 对每个 (profile, core_version) 组合：
    1. 能力检查：使用 XraySupportCatalog / SingboxFallbackResolver 预判是否兼容
    2. 配置生成：通过 CoreConfigHandler.toJSON() 生成 JSON 配置
    3. 核心启动：使用测试目录下的对应版本二进制启动
    4. 连通测试：通过代理端口或核心 API 测试延迟
    5. 结果记录：记录成功/失败/不兼容等信息

核心路径覆盖机制

测试时需要覆盖 getCoreFile(mode:) 返回的路径。通过环境的 V2RAYU_TEST_CORE_DIR 或参数来实现：

swift
func testCoreBinaryPath(version: String, mode: CoreType) -> String {
    let base = ProcessInfo.processInfo.environment["V2RAYU_TEST_BIN_DIR"]
        ?? "\(projectRoot)/Build/tests/bin"
    let subDir = mode == .XrayCore ? "xray-core" : "sing-box"
    #if arch(arm64)
    let binary = mode == .XrayCore ? "xray-arm64" : "sing-box-arm64"
    #else
    let binary = mode == .XrayCore ? "xray-64" : "sing-box-64"
    #endif
    return "\(base)/\(subDir)/\(version)/\(binary)"
}

4.3 TestReport — 报告生成器

格式：JSON + HTML 摘要

JSON 报告结构：

json
{
  "schemaVersion": 1,
  "generatedAt": "2026-06-06T12:00:00Z",
  "environment": {
    "arch": "arm64",
    "osVersion": "macOS 15.x"
  },
  "coreVersions": {
    "xray": ["v1.8.0", "v1.8.1", ..., "v26.5.6"],
    "singbox": ["v1.12.0", ..., "v1.13.12"]
  },
  "profiles": [
    {
      "uuid": "...",
      "remark": "my-server",
      "protocol": "vmess",
      "network": "tcp",
      "security": "tls",
      "coreType": "auto"
    }
  ],
  "results": [
    {
      "profileUUID": "...",
      "coreType": "xray",
      "coreVersion": "v1.8.0",
      "rulePrediction": "supported",
      "configGenerated": true,
      "connectionTest": {
        "succeeded": true,
        "latencyMs": 123,
        "error": null
      },
      "ruleMatched": true
    }
  ],
  "summary": {
    "totalCombinations": 1000,
    "succeeded": 800,
    "failed": 100,
    "incompatible": 100,
    "ruleMismatches": [
      {
        "profileUUID": "...",
        "coreType": "xray",
        "coreVersion": "v1.8.0",
        "rulePredicted": "supported",
        "actualResult": "failed",
        "likelyRootCause": "protocol not supported in this version"
      }
    ]
  }
}

5. 测试流程

5.1 单次测试流程（per profile × version）

text
对于每个 profile:
  对于 xray 版本列表:
    1. 检查能力规则
       - 如果规则标记为 unsupported/removed → 跳过测试，记录兼容
       - 如果规则标记为 supported/legacy → 继续
    2. 设置核心路径为测试版本
    3. 生成 JSON 配置 (CoreConfigHandler.toJSON)
    4. 启动核心进程
    5. 等待端口就绪 (timeout: 5s)
    6. 测试连通性（通过 HTTP 代理端口 send GET → 检查 204）
    7. 记录延迟/错误
    8. 终止核心进程，清理临时文件
    9. 对比规则预测 vs 实际结果
    
  对于 sing-box 版本列表:
    类似流程，使用 SingBoxConfigHandler

5.2 完整运行流程

bash
# Phase 1: 下载所有核心版本
./Build/tests/download-cores.sh

# Phase 2: 运行兼容性测试
./Build/tests/run-compatibility-test.sh

# Phase 3: 查看报告
open Build/tests/reports/latest/summary.html

6. 文件清单

新增文件

文件 类型 说明
Build/tests/download-cores.sh Shell 下载所有需要测试的核心二进制
Build/tests/run-compatibility-test.sh Shell 运行完整测试套件
V2rayUTests/CompatibilityTestRunner.swift Swift 测试主逻辑
V2rayUTests/CompatibilityTestModels.swift Swift 测试数据模型和报告结构
Build/tests/reports/ 目录 报告输出目录 (gitignored)

修改文件

文件 变更说明
.gitignore 添加 Build/tests/bin/ 和 Build/tests/reports/

7. 实现计划

Phase 1: 下载脚本

  • download-cores.sh 实现
    • GitHub API 分页获取 release 列表
    • 版本过滤和范围匹配
    • 架构匹配下载
    • 解压和命名规范

Phase 2: 测试基础设施

  • CompatibilityTestModels.swift — 测试数据模型
  • CompatibilityTestRunner.swift — 测试执行器
    • Profile 遍历
    • 核心版本枚举
    • 能力规则预检查
    • 配置生成
    • 进程启动/管理
    • 连通性测试
    • 结果收集

Phase 3: 报告与分析

  • JSON 报告输出
  • 规则准确性对比分析
  • HTML 摘要报告

8. 注意事项

  1. 安全性：测试会启动真实核心进程，确保使用随机端口避免冲突
  2. 性能：大量版本 × 大量 profile 会产生大量组合，需要合理设置并发度
  3. 磁盘空间：多个核心版本会占用较多磁盘空间（每个 xray ~50MB）
  4. 网络依赖：GitHub API 有频率限制，下载需要稳定的网络连接
  5. DB 访问：测试工具需要只读访问用户数据库，不应修改生产数据
  6. 测试版核心：仅在测试时覆盖核心路径，不应影响生产环境的核心管理

Docs CoreCapabilityRules (`Docs/CoreCapabilityRules.md`)

Xray 功能支持规则（Capability Rules）

本文件改为严格区分三类信息：

  1. 当前官方文档主列表里明确列出的功能
  2. 历史/兼容页面里仍可见，但已不在当前主列表中的功能
  3. V2rayU 自己额外做的兼容判断（只保留少量有明确依据或已有实现依赖的规则）

说明：此前文档里把很多功能写成 >= 1.0.0、Never、v25+ 移除，其中不少并不能从当前官方文档直接推出，且有的结论已经和当前官方文档冲突。

例如：当前官方文档（2026-05）里，WebSocket、gRPC、Hysteria inbound/outbound、WireGuard inbound/outbound 都明确仍在主列表中，因此不能继续写成“从未支持”或“已经下架”。

1. 取证来源

本功能支持规则目前以 XTLS 官方文档站为主：

  • 入站协议总览：https://xtls.github.io/config/inbounds/
  • 出站协议总览：https://xtls.github.io/config/outbounds/
  • 传输配置总览：https://xtls.github.io/config/transports/
  • RAW 页面（用户提供）：https://xtls.github.io/config/transports/raw.html
  • GitHub Releases API：https://api.github.com/repos/XTLS/Xray-core/releases

本次核对时可见的页面更新时间：

  • inbounds：2026-03-28
  • outbounds：2026-01-18
  • transports：2026-05-09
  • raw：2026-05-07

此外，仓库内已提供一份基于 releases API 自动生成的分析报告：

  • Docs/XrayReleaseFeatureAnalysis.md
  • 生成脚本：Tools/analyze_xray_releases.py

2. Releases API 分析：可作为版本演进线索

说明：release note 的“首次匹配版本”只代表在已抓取 release 正文中第一次出现相关关键词，不等于“官方精确首发版本”。
它更适合作为版本线索，不能单独替代官方 docs 总览页。

当前自动分析报告（抓取 114 个 release）得到的关键词线索如下：

Feature 首次匹配 release 最新匹配 release 解读
XHTTP v1.8.16 v26.3.27 早期匹配主要来自 SplitHTTP / XHTTP 相关演进线索
REALITY v1.7.5 v26.3.27 release note 中很早就开始出现 REALITY 相关内容
Hysteria v26.1.23 v26.3.27 当前抓到的 release 线索表明 Hysteria 功能是非常新的主线功能
WireGuard v1.5.6 v26.3.27 release note 中长期持续出现
gRPC v1.4.0 v26.3.27 至今仍在 release note 中出现，不能据此认定已下架
WebSocket v1.1.4 v26.3.27 至今仍在 release note 中出现，不能据此认定已下架
HTTPUpgrade v1.8.9 v26.3.27 属较新的 transport 功能
FinalMask v26.2.6 v26.3.27 非常新的附加配置功能
Sockopt v1.4.0 v26.1.23 长期存在的附加配置功能

当前可以据此做出的保守结论

  1. WebSocket、gRPC 到最新 release 仍有提及，不能再写成 v25+ 移除。
  2. Hysteria 在当前抓取结果里首次显著出现于 v26.1.23，因此：
    • 它绝对不能再写成 Never；
    • 若后续要在 V2rayU 里做 Hysteria 硬版本门槛，v26.1.23 可以作为一个候选起点线索，但仍需再结合 docs / PR / 具体页面确认。
  3. WireGuard、REALITY、gRPC、WebSocket 都具有明显的持续维护迹象。
  4. XHTTP 的 release 线索可追溯到 v1.8.16（通过 SplitHTTP/XHTTP 关键词链路），但因为命名与功能边界经历过演化，V2rayU 当前仍保留较保守的版本阈值，不直接把首次匹配版本当作硬门槛。

3. 当前官方文档主列表：Inbound Protocols

以下功能是当前官方入站协议总览页面明确列出的：

功能 当前状态 来源
Tunnel（dokodemo-door） inbound 当前主列表支持 /config/inbounds/tunnel.html
HTTP inbound 当前主列表支持 /config/inbounds/http.html
Shadowsocks inbound 当前主列表支持 /config/inbounds/shadowsocks.html
SOCKS inbound 当前主列表支持 /config/inbounds/socks.html
Trojan inbound 当前主列表支持 /config/inbounds/trojan.html
VLESS inbound 当前主列表支持 /config/inbounds/vless.html
VMess inbound 当前主列表支持 /config/inbounds/vmess.html
WireGuard inbound 当前主列表支持 /config/inbounds/wireguard.html
Hysteria inbound 当前主列表支持 /config/inbounds/hysteria.html
TUN inbound 当前主列表支持 /config/inbounds/tun.html

修正点

此前文档中以下结论是错误的：

  • Hysteria inbound = Never ❌
  • Hysteria2 inbound = Never ❌（当前官方主列表至少明确有 Hysteria，但并没有单独叫 Hysteria2 的页面）
  • TUIC inbound = Never 这个说法不能从当前 Xray 官方主列表推出；当前官方主列表也没有 TUIC 页面，因此不能再写成“官方明确 Never”，只能写成“当前主列表未列出”。

4. 当前官方文档主列表：Outbound Protocols

以下功能是当前官方出站协议总览页面明确列出的：

功能 当前状态 来源
Blackhole outbound 当前主列表支持 /config/outbounds/blackhole.html
DNS outbound 当前主列表支持 /config/outbounds/dns.html
Freedom outbound 当前主列表支持 /config/outbounds/freedom.html
HTTP outbound 当前主列表支持 /config/outbounds/http.html
Loopback outbound 当前主列表支持 /config/outbounds/loopback.html
Shadowsocks outbound 当前主列表支持 /config/outbounds/shadowsocks.html
SOCKS outbound 当前主列表支持 /config/outbounds/socks.html
Trojan outbound 当前主列表支持 /config/outbounds/trojan.html
VLESS outbound 当前主列表支持 /config/outbounds/vless.html
VMess outbound 当前主列表支持 /config/outbounds/vmess.html
WireGuard outbound 当前主列表支持 /config/outbounds/wireguard.html
Hysteria outbound 当前主列表支持 /config/outbounds/hysteria.html

修正点

此前文档中以下结论是错误的：

  • Hysteria outbound = Never ❌
  • Hysteria2 outbound = Never ❌（当前官方主列表并未单独叫 Hysteria2，不能直接据此写 Never）
  • TUIC outbound = Never ❌（当前官方主列表未列出 TUIC，但这不等于可以直接写“Never”）

更准确的表述应当是：

  • 当前主列表列出的功能：可视为当前官方支持面
  • 当前主列表未列出的功能：只能写“当前主列表未列出 / 未单列”，不能直接写“Never”

5. 当前官方文档主列表：Transport / Security / Additional

5.1 Transport Methods

以下功能是当前官方 transport 总览页面明确列出的：

功能 当前状态 来源
RAW 当前主列表支持 /config/transports/raw.html
XHTTP 当前主列表支持 /config/transports/xhttp.html
mKCP 当前主列表支持 /config/transports/mkcp.html
gRPC 当前主列表支持 /config/transports/grpc.html
WebSocket 当前主列表支持 /config/transports/websocket.html
HTTPUpgrade 当前主列表支持 /config/transports/httpupgrade.html
Hysteria transport 当前主列表支持 /config/transports/hysteria.html

5.2 Transport Security

功能 当前状态 来源
REALITY 当前主列表支持 /config/transports/reality.html
TLS 当前主列表支持 /config/transports/tls.html

5.3 Additional Config

功能 当前状态 来源
FinalMask 当前主列表支持 /config/transports/finalmask.html
Sockopt 当前主列表支持 /config/transports/sockopt.html

修正点

此前文档中以下结论与当前官方文档冲突：

  • WebSocket = v25+ 移除 ❌（当前官方 transport 主列表仍明确列出）
  • gRPC = v25+ 移除 ❌（当前官方 transport 主列表仍明确列出）

因此，V2rayU 不能再继续把 ws/grpc 默认视为“新版本 Xray 已不支持”。

6. 历史/兼容功能：不在当前主列表，但站点仍保留页面或兼容痕迹

当前官方主列表没有列出以下 transport，但站点仍能看到历史页面或兼容内容：

功能 当前主列表 处理建议
HTTP/2 (h2) 不在当前主列表 按历史/兼容功能处理，不直接写“Never”
QUIC 不在当前主列表 按历史/兼容功能处理，不直接写“Never”
旧 tcp transport 名称 已被 RAW 取代 在客户端模型中应映射为 RAW
domainsocket 当前主列表未单列 作为现有模型兼容项处理

也就是说：

  • 不在当前主列表 ≠ 官方明确从未支持
  • 不在当前主列表 ≠ 一定已经从所有版本完全移除

对这类功能，更合理的写法是：

  • 历史页面仍存在
  • 当前主列表未列出
  • V2rayU 按 legacy / compatibility 处理

7. V2rayU 当前模型与官方 docs 的映射

7.1 `ProfileEntity.network` 映射

V2rayU 模型值 对应官方概念 当前处理
tcp RAW 作为 RAW 别名 处理
ws WebSocket 视为当前官方主列表支持
grpc gRPC 视为当前官方主列表支持
xhttp XHTTP 视为当前官方主列表支持
kcp mKCP 视为当前官方主列表支持
h2 HTTP/2 视为历史/兼容 transport
quic QUIC 视为历史/兼容 transport
domainsocket Domain Socket 视为现有模型兼容项

7.2 `ProfileEntity.security` 映射

V2rayU 模型值 对应官方概念 当前处理
none 无额外 transport security 隐含默认功能
tls TLS 当前官方主列表支持
reality REALITY 当前官方主列表支持
xtls 当前工程内暂按 TLS 兼容处理 不再在本文件里臆造版本范围

7.3 `flow`

当前 xtls-rprx-vision* 属于 VLESS / XTLS / REALITY 细分配置，不在官方 transport 总览页单列，所以本文件不再直接写死“>= 某版本”的结论；若后续要对 flow 做严格版本校验，应引用更具体的官方页面或 release note。

8. V2rayU 当前启动前校验：实际执行规则

8.1 当前会检查的内容

当前启动前仍会检查：

  • outbound protocol
  • transport
  • stream security
  • flow

8.2 当前**真正执行**的硬校验

目前只保留少量明确规则：

功能 当前校验策略
XHTTP 保留现有 V2rayU 兼容阈值：旧语义版本 >= 1.8.24，日期版本 >= 24.9.30；不满足则回退 Sing-Box
ws / grpc 不再因为“文档误判为已下架”而自动回退 Sing-Box
h2 作为历史/兼容 transport，只做提示，不再直接依据错误文档强制判死

8.3 当前只做提示、不强制切核心的内容

当前功能支持规则中的 rule.type 按状态分为：

  • supported：当前主线支持功能；如已知起始版本 / 移除版本，直接写在同一条规则里
  • legacy：历史兼容项，不再属于当前主线支持面，但仍保留兼容说明；也可以附带版本边界
  • compatibility：别名 / 默认项 / 映射兼容项，用于表达客户端兼容语义；必要时也可附带版本边界
  • removed：已明确移除的功能；若知道移除版本，应写入 removedAt
  • pendingReview：证据还不完整，暂不把它归入 supported / legacy / removed 中任一类

也就是说，版本边界不是一种状态：

  • 起始版本由 legacyMin / calendarMin 表达

  • 移除版本由 removedAt 表达

  • rule.type 只表达“它现在属于哪种状态”

  • h2

  • quic

  • legacy / compatibility 类型功能

这些项会提示“当前官方主列表未列出 / 作为历史兼容或客户端兼容处理”，但不会仅凭这一点就自动切 core。

9. 当前文档结论

可以明确写“当前官方支持”的

以当前官方 docs 主列表为准，可明确写支持的包括：

  • Inbound：Tunnel、HTTP、Shadowsocks、SOCKS、Trojan、VLESS、VMess、WireGuard、Hysteria、TUN
  • Outbound：Blackhole、DNS、Freedom、HTTP、Loopback、Shadowsocks、SOCKS、Trojan、VLESS、VMess、WireGuard、Hysteria
  • Transport：RAW、XHTTP、mKCP、gRPC、WebSocket、HTTPUpgrade、Hysteria
  • Security：REALITY、TLS
  • Additional：FinalMask、Sockopt

不能再直接写死的

以下说法不应再直接写入功能支持规则：

  • Hysteria = Never
  • WireGuard = 不支持
  • WebSocket = v25+ 移除
  • gRPC = v25+ 移除
  • 任何没有来源支撑的 >= 1.0.0
  • 任何仅凭“当前 sidebar 没出现”就写成 Never

10. 维护原则

后续维护必须遵守：

  1. 支持面优先以当前官方 docs 总览页为准
  2. 版本边界只有在有明确来源时才写死
    • 官方 release note
    • 官方 docs 明示
    • 工程内已有可靠兼容规则且能说明来源
  3. 对于 legacy / compatibility / removed / pendingReview 项：
    • 必须明确说明它为什么不是当前主线 supported
    • legacy / compatibility 只能写“历史兼容 / 客户端兼容”，不要冒充当前主线支持
    • 若写“已移除”，必须尽量给出 removedAt 或对应 evidence
    • 若写 pendingReview，必须说明当前缺的证据是什么
    • 不要直接写没有来源支撑的 “Never” / “已彻底移除”
  4. 若 V2rayU 新增 Hysteria / WireGuard / TUIC 等节点模型，需同步更新：
    • Core/Utilities/CoreCapabilityRules.swift
    • 本文档
    • Docs/XrayReleaseFeatureAnalysis.md
    • 运行时 resolveCoreCompatibility() 的映射规则

Docs XrayReleaseFeatureAnalysis (`Docs/XrayReleaseFeatureAnalysis.md`)

Xray Release Feature Analysis

  • Generated at: 2026-05-18 13:45:27Z
  • Data source: https://api.github.com/repos/XTLS/Xray-core/releases
  • Pages fetched: up to 5 pages × 100 items
  • Releases analyzed: 114

说明：本报告只分析 GitHub Releases API 中的 release 标题与正文提及情况。
它可以作为版本线索与功能演进证据，但不应单独视为“官方完整支持列表”或“精确首发版本”的唯一依据。
更稳妥的做法是：官方 docs 主列表确定当前支持面，releases API 辅助判断版本演进。

Summary

Feature Match count First matched release Last matched release Note
XHTTP 22 v1.8.16 v26.3.27 重点用于分析新 transport 的引入/演进。
REALITY 28 v1.7.5 v26.3.27 用于观察 REALITY 相关 release 线索。
Hysteria 3 v26.1.23 v26.3.27 用于观察 Hysteria inbound/outbound/transport 的 release 线索。
WireGuard 22 v1.5.6 v26.3.27 用于观察 WireGuard inbound/outbound 的 release 线索。
gRPC 18 v1.4.0 v26.3.27 用于观察 gRPC transport 的 release 线索。
WebSocket 15 v1.1.4 v26.3.27 用于观察 WebSocket transport 的 release 线索。
HTTPUpgrade 6 v1.8.9 v26.3.27 用于观察 HTTPUpgrade transport 的 release 线索。
FinalMask 2 v26.2.6 v26.3.27 用于观察附加配置 FinalMask 的 release 线索。
Sockopt 19 v1.4.0 v26.1.23 用于观察 Sockopt 的 release 线索。

Details

XHTTP

  • Note: 重点用于分析新 transport 的引入/演进。
  • Match count: 22
  • First matched release in fetched dataset: v1.8.16
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

REALITY

  • Note: 用于观察 REALITY 相关 release 线索。
  • Match count: 28
  • First matched release in fetched dataset: v1.7.5
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

Hysteria

  • Note: 用于观察 Hysteria inbound/outbound/transport 的 release 线索。
  • Match count: 3
  • First matched release in fetched dataset: v26.1.23
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

  • v26.3.27 · 2026-03-27 · Xray-core v26.3.27

    • Finalmask, mKCP, Hysteria, XHTTP, REALITY, TLS ECH, WireGuard, VLESS Reverse Proxy, Global HTTP headers' browser masquerading, API, Others

    • Hysteria https://github.com/XTLS/Xray-core/pull/5679 https://github.com/XTLS/Xray-core/pull/5782 https://github.com/XTLS/Xray-core/pull/5772

      • 新增 Hysteria 2 入站与传输层，至此 Xray 支持了完整的 Hysteria 2，甚至 Finalmask 不只有 Salamander
  • v26.2.6 · 2026-02-06 · Xray-core v26.2.6
  • v26.1.23 · 2026-01-23 · Xray-core v26.1.23

    • Proxy: Add TUN inbound for Windows & Linux, including Android https://github.com/XTLS/Xray-core/pull/5464 https://github.com/XTLS/Xray-core/pull/5509 & Proxy: Add Hysteria outbound & transport (version 2, udphop) and Salamander udpmask https://github.com/XTLS/Xray-core/pull/5508

      1. 新增 Hysteria 2 出站、Hysteria 2 传输层（支持端口跳跃）、Salamander 伪装层，完整配置示例详见 https://github.com/XTLS/Xray-core/pull/5508

WireGuard

  • Note: 用于观察 WireGuard inbound/outbound 的 release 线索。
  • Match count: 22
  • First matched release in fetched dataset: v1.5.6
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

gRPC

  • Note: 用于观察 gRPC transport 的 release 线索。
  • Match count: 18
  • First matched release in fetched dataset: v1.4.0
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

  • v26.3.27 · 2026-03-27 · Xray-core v26.3.27
      • XHTTP、WS、HU、gRPC 传输层可设置 headers User-Agent 来指定 "firefox"/"edge"/"golang"
  • v24.11.21 · 2024-11-21 · Xray-core v24.11.21

    • XHTTP client: Add gRPC header to "stream-up" mode by default #4042

    • 这个版本为 stream-up 模式的上行 POST 请求默认加上了 gRPC 标头，经测试 CF H2 支持它，详见 #4042
  • v24.11.11 · 2024-11-11 · Xray-core v24.11.11
    • XHTTP stream-up 模式旨在取代现有的 H2 / gRPC over REALITY，XHTTP 有 header padding、XMUX，表现会更好
    • 总之，现在正式建议现有的 H2、gRPC 均迁移至 XHTTP，并玩一玩上下行分离，尤其是 H2，它仍有可能被移除
  • v24.10.31 · 2024-10-31 · Xray-core v24.10.31
  • v1.8.16 · 2024-06-21 · Xray-core v1.8.16
    • SplitHTTP 使用 HTTP GET 长连接传输下行流量，使用多个 HTTP POST 请求传输上行流量，可以通过不支持 WebSocket、gRPC 的 CDN，实现与 Meek 相同的目标，但 SplitHTTP 是从零开始设计的全新传输方式，并非基于 Meek 修改而来，且 SplitHTTP 比 Meek 更简单、效率更高，详见文档 英文（原生文档） 中文（内容略有不同）
  • v1.8.10 · 2024-03-30 · Xray-core v1.8.10
      • gRPC API 现支持增删路由规则 #3189 @hossinasaadi
  • v1.8.9 · 2024-03-11 · Xray-core v1.8.9
      • #716 gRPC 新增 authority #3076，修订 serviceName 必须使用 encodeURIComponent 转义 #1815
      • gRPC 传输方式支持设置 authority（类似 Host） #3076 @RPRX
  • v1.8.4 · 2023-08-29 · Xray-core v1.8.4
      • 修复 gRPC 使用 dialerProxy 代理链 d92002ad127f64bc1e740cb350eafd693ffadd6d @RPRX

WebSocket

  • Note: 用于观察 WebSocket transport 的 release 线索。
  • Match count: 15
  • First matched release in fetched dataset: v1.1.4
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

HTTPUpgrade

  • Note: 用于观察 HTTPUpgrade transport 的 release 线索。
  • Match count: 6
  • First matched release in fetched dataset: v1.8.9
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

FinalMask

  • Note: 用于观察附加配置 FinalMask 的 release 线索。
  • Match count: 2
  • First matched release in fetched dataset: v26.2.6
  • Last matched release in fetched dataset: v26.3.27

Sample matched releases:

  • v26.3.27 · 2026-03-27 · Xray-core v26.3.27

    • Finalmask, mKCP, Hysteria, XHTTP, REALITY, TLS ECH, WireGuard, VLESS Reverse Proxy, Global HTTP headers' browser masquerading, API, Others

    • Finalmask https://github.com/XTLS/Xray-core/pull/5657 https://github.com/XTLS/Xray-core/pull/5685 https://github.com/XTLS/Xray-core/pull/5812 https://github.com/XTLS/Xray-core/pull/5850

      • 新增 header-custom (TCP & UDP)、Sudoku (TCP & UDP)，移植了 Direct/Freedom 出站的 fragment (TCP)、noise (UDP)，最终的自定义流量外观拥有了更多可能，且均支持通过 fm 参数分享，基于 Xray-core 的 GUI 应尽快更新 Finalmask（类似 XHTTP extra）
  • v26.2.6 · 2026-02-06 · Xray-core v26.2.6

    • XHTTP transport: New options for bypassing CDN's potential detection https://github.com/XTLS/Xray-core/pull/5414 & Finalmask: Add [XICMP](https://github.com/XTLS/Xray-core/pull/5633), [XDNS](https://github.com/XTLS/Xray-core/pull/5560) (relies on mKCP, like DNSTT), header-\*, mkcp-\*

      1. Finalmask UDP 新增了 XICMP、XDNS、header-*、mkcp-*，分享链接标准 https://github.com/XTLS/Xray-core/discussions/716 已更新 fm、pcs、vcn
      1. Finalmask UDP 支持了 WireGuard、SS AEAD/2022 等代理层协议产生的 UDP 流量，详见 https://github.com/XTLS/Xray-core/pull/5643

Sockopt

  • Note: 用于观察 Sockopt 的 release 线索。
  • Match count: 19
  • First matched release in fetched dataset: v1.4.0
  • Last matched release in fetched dataset: v26.1.23

Sample matched releases:

Suggested usage in V2rayU

  1. 用官方 docs 主列表判断 当前是否支持。
  2. 用本报告判断 某功能从哪些 release 开始频繁出现。
  3. 只有当 release note 与 docs/源码/兼容经验三者都能互相印证时，才把规则提升为启动前的硬版本门槛。

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#anytls Browse anytls catalog → #clash Browse clash catalog → #mac Browse mac catalog → #macos Browse macos catalog → #native Browse native catalog → #v2ray Browse v2ray catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →