更新记录

1.0.0（2026-06-06）

  • 首发 Android：系统隧道 / 本地 SOCKS、订阅与多方式导入、按应用分流
  • 示例 UI、权限引导（VPN / 通知 / 相机 / 文件）

平台兼容性

uni-app(4.18)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ 7.0 12 4.0.0
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × - × - - - -

其他

多语言 暗黑模式 宽屏模式
√ × ×

ly028-XRay

在 App 端（Android / iOS / HarmonyOS Next）提供系统级网络隧道、本地 SOCKS 代理、节点/订阅管理与配置导入能力，适用于企业内网接入、运维调试、跨境办公等合法业务场景。

📥 下载体验 APK
扫码体验
扫码下载体验

重要说明：本插件是技术组件，不提供任何节点、订阅或上网服务。集成方须自行准备服务器与配置，并独立承担合规责任。

快速开始

1. 导入插件

在 manifest.json → App 原生插件配置 → 勾选 ly028-XRay。

2. 引用并初始化

import {
  initApp,
  start,
  stop,
  onStatus,
  getStatus,
  buildProxyConfig,
  selectConfig
} from '@/uni_modules/ly028-XRay'

// App onLaunch 时初始化
initApp()

// 监听连接状态
onStatus((status) => {
  console.log('隧道状态:', status)
})

3. 启动隧道

const proxyConfig = buildProxyConfig(configJson)
start({
  mode: 'tun',              // 'tun' 系统隧道 | 'socks' 本地代理
  configJson: proxyConfig,
  disallowedApps: [],       // 不走 VPN 的应用包名
  proxyMode: 'bypass'       // 'bypass' 排除 | 'proxy' 仅代理
})

首次 TUN 模式会弹出系统 VPN 授权对话框；随后可能提示通知权限（可拒绝，不影响隧道运行）。

适用场景（示例）

  • 企业/团队授权的内网或专线接入客户端
  • 与自有后端配合的加密链路调试工具
  • 需要系统隧道能力的行业 App（在取得用户明示同意与合法资质前提下）

平台兼容性

平台 支持情况 最低版本
Android ✓ 7.0（API 24）
iOS ✓ 12.0
HarmonyOS Next ✓ 4.0.0
小程序 / H5 ✗ —

合规与法律风险提示

  1. 境内监管：在中华人民共和国境内，未经电信主管部门批准，不得擅自建立、使用非法定信道进行国际联网。集成本插件的应用若用于向公众提供 VPN/代理上网服务，可能违反相关法律法规。
  2. 插件定位：本插件是技术组件，不是上网服务。作者不对集成方的业务用途、用户行为及内容负责。
  3. 用户告知：您的 App 应向用户明确说明：为何申请 VPN、通知、相机、存储等权限；数据如何传输；是否记录日志等（隐私政策）。
  4. 资质要求：若业务属于增值电信、跨境专线等范畴，请自行办理相应许可或与持证主体合作。
  5. 禁止用途：不得用于攻击、扫描、传播违法信息、规避国家网络监管等。

核心功能

两种工作模式

  • TUN 模式（系统隧道）：创建系统 VPN 接口，全局流量自动经过隧道转发。首次使用需授予 VPN 权限。
  • SOCKS 模式（本地代理）：不创建 VPN 接口，仅在本地开启 SOCKS5 代理端口。需在浏览器或应用中手动配置代理地址 127.0.0.1:10808 使用。

节点管理

  • 支持多种协议配置，可添加、切换、删除
  • 支持订阅 URL 更新与批量导入
  • 支持剪贴板、扫码、本地文件三种导入方式
  • 支持链接分享、剪贴板导出、二维码图片生成

按应用分流

  • 排除模式：指定应用绕过隧道，其余走隧道
  • 仅代理模式：仅指定应用走隧道，其余直连

设置选项

  • 自定义 DNS、SOCKS 端口、MTU、日志等级
  • 切换 TUN/SOCKS 模式
  • HevTun 转发开关（TUN 模式下可选）
  • 分应用代理列表管理

多语言

  • 支持中文 / English
  • 通过 setAppLocale() 动态切换，无需重启应用

支持的协议

协议 分享链接格式 说明
VMess vmess://
VLESS vless://
Shadowsocks ss://
Trojan trojan://
SOCKS socks://
HTTP http://
WireGuard wireguard://
Hysteria2 hysteria2://
Hysteria hysteria://
自定义 — 手动 JSON 配置
策略组 — 多节点策略路由
代理链 — 多级代理串联

权限说明（Android）

权限 用途
INTERNET 网络访问
ACCESS_NETWORK_STATE 网络状态
FOREGROUND_SERVICE / SPECIAL_USE 前台服务保持隧道运行
BIND_VPN_SERVICE 系统 VPN 隧道（TUN 模式需要）
POST_NOTIFICATIONS 连接状态通知（可选）
CAMERA 扫描二维码导入节点配置
READ_EXTERNAL_STORAGE（≤API 32） 读取本地配置文件
QUERY_ALL_PACKAGES 获取已安装应用列表（分应用分流）

集成时请在应用隐私政策与权限申请文案中向用户说明用途。

使用说明

  1. 导入插件（参见上方快速开始）
  2. 运行自定义调试基座后在真机体验

涉及 VPN 服务、前台服务、相机扫码等系统能力，标准基座无法完整验证，请务必使用自定义基座。

API 参考

引用方式

import * as xray from '@/uni_modules/ly028-XRay'

生命周期

API 说明
initApp() 应用启动时初始化（建议在 App.onLaunch 中调用）
start(config) 启动隧道，返回 boolean
stop() 停止隧道，返回 boolean

start 参数 ProxyConfig

字段 类型 说明
mode 'tun' \| 'socks' TUN 系统隧道 / SOCKS 本地代理
configJson string 代理核心 JSON 配置字符串
tun? TunConfig TUN 配置（TUN 模式可选）
disallowedApps? string[] 不走 VPN 的应用包名列表
proxyMode? string 'bypass' 排除 / 'proxy' 仅代理

TunConfig

字段 类型 说明
address string[] 虚拟网卡地址，如 ["172.16.0.2/24"]
route string[] 路由网段，如 ["0.0.0.0/0"] 表示所有流量
dns string[] DNS 服务器，如 ["8.8.8.8", "1.1.1.1"]
mtu? number MTU 值，默认 1500

状态与统计

API 返回类型 说明
getStatus() ProxyStatus 获取当前运行状态
getTrafficStats() TrafficStats \| null 获取流量统计
getVersion() string 获取核心版本号
testLatency() LatencyResult 延迟测试（同步阻塞）

ProxyStatus

字段 类型 说明
running boolean 是否运行中
mode string 当前运行模式
uptime number 已运行时长（秒）
version string 核心版本
error? string 错误信息

TrafficStats

字段 类型
uplink number
downlink number
totalUplink number
totalDownlink number

LatencyResult

字段 类型 说明
delay number 延迟值（ms）
success boolean 是否成功
error? string 错误信息

事件监听

API 说明
onStatus(callback) 监听连接状态 'starting' \| 'started' \| 'stopped' \| 'error:...'
onTraffic(callback) 监听流量更新，回调参数 TrafficStats
onLog(callback) 监听日志，回调参数 (level, message)
onVpnPermission(callback) 监听 VPN 授权结果，回调参数 (granted)
onNotificationPermission(callback) 监听通知权限结果，回调参数 (granted)
removeAllListeners() 移除所有监听

节点与配置管理

API 说明
getConfigs() 获取所有节点配置列表
getConfigsBySub(subId) 获取指定订阅下的节点列表
getSelectedConfig() 获取当前选中的节点
selectConfig(configId) 选中节点
deleteConfig(configId) 删除节点
deleteConfigsBySub(subId) 删除指定订阅下所有节点
buildProxyConfig(configStr) 构建代理核心配置 JSON 字符串

订阅管理

API 说明
getSubscriptions() 获取所有订阅列表
addSubscription(url) 添加订阅
removeSubscription(subId) 删除订阅
updateSubscriptionMeta(subId, meta) 更新订阅元信息
refreshSubscription(subId) 刷新订阅（同步）
refreshSubscriptionAsync(subId) 刷新订阅（异步）
fetchSubscription(url) 拉取订阅内容（同步）
fetchSubscriptionAsync(url) 拉取订阅内容（异步）

导入与导出

API 说明
resolveLink(text) 解析链接（支持多种格式）
resolveSubscriptionText(text) 解析订阅文本
resolveJsonConfig(text) 解析 JSON 配置
importBatchConfig(text) 批量导入配置，返回 { ok, count?, subCount?, msg? }
importFromClipboard() 从剪贴板导入
exportConfigLink(configId) 导出为链接，返回 { ok, link?, msg? }
exportConfigToClipboard(configId) 导出到剪贴板
exportConfigQRBase64(configId) 导出为二维码图片 Base64，返回 { ok, base64?, msg? }
exportAllConfigsToClipboard() 导出所有配置到剪贴板

扫码与文件

API 说明
launchQRScanner() 启动扫码界面
pickQRFromImage() 从相册选图识别二维码，返回 { ok, text? }
decodeQRFromImage(path) 解码图片中的二维码，返回 { ok, text? }
pickConfigFile() 选择本地配置文件

设置存储

API 说明
getSettingsString(key, def?) 读取字符串设置
setSettingsString(key, value) 写入字符串设置
getSettingsBool(key, def?) 读取布尔设置
setSettingsBool(key, value) 写入布尔设置
getSettingsInt(key, def?) 读取整数设置
setSettingsInt(key, value) 写入整数设置

其他工具

API 说明
setAppLocale(locale) 设置应用语言
requestVpnPermission() 请求 VPN 权限
checkVpnPermission() 检查 VPN 权限是否已授予
checkNotificationPermission() 检查通知权限
requestNotificationPermission() 请求通知权限
openAppSettings() 打开系统应用设置页
getInstalledAppsJson() 获取已安装应用列表（JSON 字符串）

常见问题

Q：TUN 模式下一直「连接中」？
A：确认 VPN 权限已授权，通知权限已授予（部分 Android 版本限制前台服务无通知无法持续运行）。

Q：SOCKS 模式连接后无法上网？
A：SOCKS 模式仅开启本地代理端口，系统不会自动转发流量。需在浏览器或 App 中手动设置 SOCKS5 代理为 127.0.0.1:10808。

Q：扫码/选文件无反应？
A：需授予相机或存储/文件访问权限；插件会弹窗引导，拒绝则无法使用该导入方式。

Q：能否用于 iOS？
A：支持。iOS 使用 NEPacketTunnelProvider 实现系统 VPN 隧道，已在 iOS 12.0+ 验证。

更新日志

1.0.0

  • 首发：Android / iOS / HarmonyOS Next 三端 TUN/SOCKS、订阅与导入、按应用代理、示例页面

隐私、权限声明

1. 本插件需要申请的系统权限列表：

Android: INTERNET, VPN, FOREGROUND_SERVICE, 通知, 相机(扫码), 存储/文件(导入), 查询已安装应用(分应用分流，可选)；鸿蒙: INTERNET, 网络信息(GET_NETWORK_INFO/SET_NETWORK_INFO), 通知控制(NOTIFICATION_CONTROLLER), MANAGE_VPN, 相机(扫码), 媒体读写(READ_MEDIA/WRITE_MEDIA), 后台保活(KEEP_BACKGROUND_RUNNING)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉
加载更多...