更新记录

1.1.8（2026-05-31）

优化iOS内部VPN逻辑，防止OOM被系统杀死。

1.1.7（2026-05-29）

优化调整插件接口输出逻辑。

1.1.6（2026-05-27）

减少鸿蒙打包体积。

查看更多

平台兼容性

uni-app(4.75)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本
× × × × × × 5.0 1.0.0 15 1.0.3 6.0.0 1.1.5
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × - × ×

uni-app x(4.75)

Chrome Safari Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本 微信小程序
× × 5.0 1.0.0 15 1.0.3 6.0.0 1.1.5 ×

概述

XF-singBoxVPNUTS 是基于 sing-box/libbox 的 App 端 VPN 插件，支持 Android、iOS、Harmony 系统。插件提供配置写入、VPN 启停、连接状态监听、日志读取、SDK 版本读取，以及 Clash 模式、分组展开和 selector 出站切换等控制面接口。

插件的 Harmony 原生实现位于 uni_modules/XF-singBoxVPNUTS/utssdk/app-harmony。Harmony 的 VPN Extension 注册文件属于宿主工程配置，不在插件内部自动声明，接入时必须按下文配置 harmony-configs/entry/src/main/module.json5 和 harmony-configs/entry/src/main/ets/singbox/SingBoxVpnExtension.ets。

使用前提

Android

Android 端插件内部已声明 VPN Service、前台服务、网络状态和通知等权限及组件。首次调用 installVPN 时会触发系统 VPN 授权流程，用户授权后再调用 setConfig 和 startVPN。

iOS

iOS 端需要宿主 App 开通 Network Extension 能力，并配置 Packet Tunnel Extension 描述文件和 App Group。

manifest.json 中增加系统扩展权限说明：

"app-ios": {
  "distribute": {
    "privacyDescription": {
      "NSSystemExtensionUsageDescription": "权限申请描述信息"
    }
  }
}

扩展 ID 建议使用 appId.PacketTunnel 格式，App Group 建议使用 group.appId 格式。

在项目根目录创建 nativeResources/ios，放置 ios-extension.json 和 ios-PacketTunnelExt.mobileprovision。ios-extension.json 示例：

{
  "PacketTunnel.appex": {
    "identifier": "com.app.xiaofei.001.PacketTunnel",
    "profile": "ios-PacketTunnelExt.mobileprovision",
    "entitlements": {
      "com.apple.developer.networking.networkextension": ["packet-tunnel-provider"],
      "com.apple.security.application-groups": ["group.com.app.xiaofei.001"]
    }
  }
}

同时确认插件内部 utssdk/app-ios/UTS.entitlements 中的 Network Extension 和 App Group 与实际证书一致。

Harmony

以下两处属于宿主工程外部配置，需要放在项目的 harmony-configs 目录中，由 HBuilderX 生成 Harmony 工程时合并到最终工程。

harmony-configs/entry/src/main/module.json5

需要在 module.extensionAbilities 中注册 VPN Extension：

{
  "name": "SingBoxVpnExtension",
  "srcEntry": "./ets/singbox/SingBoxVpnExtension.ets",
  "icon": "$media:layered_image",
  "label": "$string:EntryAbility_label",
  "description": "$string:EntryAbility_desc",
  "type": "vpn",
  "exported": false
}

同时确保 requestPermissions 至少包含网络权限：

{
  "name": "ohos.permission.INTERNET"
}

srcEntry 固定指向宿主工程中的 ./ets/singbox/SingBoxVpnExtension.ets。这个文件不是插件主实现，只是 Harmony Ability 的入口桥接文件。

harmony-configs/entry/src/main/ets/singbox/SingBoxVpnExtension.ets

该文件属于宿主工程外部配置，作用是让 Harmony 的 srcEntry 模块自身默认导出一个 VPN Extension 类，并继承插件内部实现：

import PluginSingBoxVpnExtension from '@uni_modules/xf-singboxvpnuts/utssdk/app-harmony/SingBoxVpnExtension';

export default class SingBoxVpnExtension extends PluginSingBoxVpnExtension {
}

Harmony 端推荐调用流程：

  1. 调用 installVPN 初始化插件状态。
  2. 调用 addStatusCallback 注册状态回调。
  3. 调用 setConfig 写入 sing-box JSON 配置。
  4. 调用 startVPN 启动 VPN Extension。
  5. 使用 setClashMode、setGroupExpand、selectOutbound 控制运行中的配置。
  6. 调用 stopVPN 停止服务。

统一输出结构

通用失败对象：

类型 字段
VPNFailResult errMsg: string，可选 code、status

常用成功对象：

接口 success 类型
installVPN、stopVPN、setConfig、setClashMode、setGroupExpand、selectOutbound VPNEmptyResult
startVPN StartVPNResult
isConnected IsConnectedResult
getConfig GetConfigResult
getLog GetLogResult
getSdkVersion GetSdkVersionResult
addStatusCallback VPNStatusEvent

回调事件说明

addStatusCallback 通过 success 和 complete 返回 VPNStatusEvent 事件对象，常见 evenType 如下：

evenType 说明
onServiceStatusChanged 服务状态变化，包含 status 字段。
onConnected VPN 已连接。
onDisconnected VPN 已断开。
updateStatus 实时状态和流量，三端均返回对象类型 data: VPNStatusData，包含 memory、goroutines、trafficAvailable、connectionsIn、connectionsOut、uplink、downlink、uplinkTotal、downlinkTotal 等字段。
updateGroups 分组或 selector 信息更新，包含 newGroups 字段。
initializeClashMode Clash 模式初始化，包含 modeList 和 currentMode 字段。
updateClashMode Clash 模式变化，包含 newMode 字段。

VPNStatusData 的 uplink、downlink 表示实时速率字节数，uplinkTotal、downlinkTotal 表示累计流量字节数。iOS、Android、Harmony 的 updateStatus.data 均为对象，不需要再解析 JSON 字符串。

插件接口

installVPN

安装或初始化 VPN 能力。Android 会触发系统 VPN 授权，iOS 会安装或准备 Network Extension 配置，Harmony 会初始化 libbox 并重置状态。

uni-app项目中（nvue）调用示例：

import { installVPN } from "@/uni_modules/XF-singBoxVPNUTS"

installVPN({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { installVPN } from "@/uni_modules/XF-singBoxVPNUTS";
import { InstallVPNOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as InstallVPNOptions;
installVPN(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

setConfig

写入 sing-box JSON 配置。rules 可用于将配置中的规则集占位符替换为实际资源文件名。

uni-app项目中（nvue）调用示例：

import { setConfig } from "@/uni_modules/XF-singBoxVPNUTS"

setConfig({
  conf: "{}",
  rules: [
    { key: "__geoip-cn.srs__", value: "geoip-cn.srs" }
  ],
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { setConfig } from "@/uni_modules/XF-singBoxVPNUTS";
import { ConfigOptions, RulesOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let rules = [
  { key: "__geoip-cn.srs__", value: "geoip-cn.srs" }
] as Array<RulesOptions>;
let options = {
  conf: "{}",
  rules: rules,
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as ConfigOptions;
setConfig(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

startVPN

启动 VPN 服务。调用前应先完成 installVPN、setConfig，并建议先注册 addStatusCallback。

uni-app项目中（nvue）调用示例：

import { startVPN } from "@/uni_modules/XF-singBoxVPNUTS"

startVPN({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { startVPN } from "@/uni_modules/XF-singBoxVPNUTS";
import { StartVPNOptions, StartVPNResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : StartVPNResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as StartVPNOptions;
startVPN(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

stopVPN

停止 VPN 服务并释放原生运行时资源。

uni-app项目中（nvue）调用示例：

import { stopVPN } from "@/uni_modules/XF-singBoxVPNUTS"

stopVPN({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { stopVPN } from "@/uni_modules/XF-singBoxVPNUTS";
import { StopVPNOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as StopVPNOptions;
stopVPN(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

addStatusCallback

注册 VPN 状态和控制面事件监听。Android、iOS、Harmony 都按被动回调模式返回状态变化；Harmony 端实时流量通过 updateStatus 持续返回。

uni-app项目中（nvue）调用示例：

import { addStatusCallback } from "@/uni_modules/XF-singBoxVPNUTS"

addStatusCallback({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { addStatusCallback } from "@/uni_modules/XF-singBoxVPNUTS";
import { AddStatusCallbackOptions, VPNFailResult, VPNStatusEvent } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : VPNStatusEvent) => {
    if (res.evenType == "updateStatus" && res.data != null) {
      console.log(res.data!.uplink, res.data!.downlink)
    }
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as AddStatusCallbackOptions;
addStatusCallback(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

isConnected

查询当前 VPN 是否处于连接状态。

uni-app项目中（nvue）调用示例：

import { isConnected } from "@/uni_modules/XF-singBoxVPNUTS"

isConnected({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { isConnected } from "@/uni_modules/XF-singBoxVPNUTS";
import { IsConnectedOptions, IsConnectedResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : IsConnectedResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as IsConnectedOptions;
isConnected(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

getConfig

读取插件当前保存的 sing-box JSON 配置。

uni-app项目中（nvue）调用示例：

import { getConfig } from "@/uni_modules/XF-singBoxVPNUTS"

getConfig({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { getConfig } from "@/uni_modules/XF-singBoxVPNUTS";
import { GetConfigOptions, GetConfigResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : GetConfigResult) => {
    console.log(res.config)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as GetConfigOptions;
getConfig(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

getLog

读取插件原生日志。Harmony 端返回 stderr 和 trace 组合日志，便于定位 VPN Extension 和 libbox 启动链路。

uni-app项目中（nvue）调用示例：

import { getLog } from "@/uni_modules/XF-singBoxVPNUTS"

getLog({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { getLog } from "@/uni_modules/XF-singBoxVPNUTS";
import { GetLogOptions, GetLogResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : GetLogResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as GetLogOptions;
getLog(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

getSdkVersion

读取当前集成的 libbox/sing-box SDK 版本。

uni-app项目中（nvue）调用示例：

import { getSdkVersion } from "@/uni_modules/XF-singBoxVPNUTS"

getSdkVersion({
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { getSdkVersion } from "@/uni_modules/XF-singBoxVPNUTS";
import { GetSdkVersionOptions, GetSdkVersionResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  success: (res : GetSdkVersionResult) => {
    console.log(res.version)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as GetSdkVersionOptions;
getSdkVersion(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

setClashMode

切换 Clash 模式。常用值由配置的 Clash API 模式决定，例如 rule、global、direct。

uni-app项目中（nvue）调用示例：

import { setClashMode } from "@/uni_modules/XF-singBoxVPNUTS"

setClashMode({
  mode: "global",
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { setClashMode } from "@/uni_modules/XF-singBoxVPNUTS";
import { SetClashModeOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  mode: "global",
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as SetClashModeOptions;
setClashMode(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

setGroupExpand

设置代理分组在控制面中的展开状态。tag 为分组 tag，isExpand 表示是否展开。

uni-app项目中（nvue）调用示例：

import { setGroupExpand } from "@/uni_modules/XF-singBoxVPNUTS"

setGroupExpand({
  tag: "urltest",
  isExpand: true,
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { setGroupExpand } from "@/uni_modules/XF-singBoxVPNUTS";
import { SetGroupExpandOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  tag: "urltest",
  isExpand: true,
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as SetGroupExpandOptions;
setGroupExpand(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

selectOutbound

在 selector 分组中选择出站节点。groupTag 为 selector 分组 tag，outboundTag 为目标出站 tag。

uni-app项目中（nvue）调用示例：

import { selectOutbound } from "@/uni_modules/XF-singBoxVPNUTS"

selectOutbound({
  groupTag: "urltest",
  outboundTag: "proxy-01",
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { selectOutbound } from "@/uni_modules/XF-singBoxVPNUTS";
import { SelectOutboundOptions, VPNEmptyResult, VPNFailResult } from "@/uni_modules/XF-singBoxVPNUTS/utssdk/interface.uts";

let options = {
  groupTag: "urltest",
  outboundTag: "proxy-01",
  success: (res : VPNEmptyResult) => {
    console.log(res)
  },
  fail: (res : VPNFailResult) => {
    console.log(res.errMsg)
  }
} as SelectOutboundOptions;
selectOutbound(options);

可用性

iOS、Android、Harmony系统

可提供的1.1.6及更高版本

隐私、权限声明

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

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SYSTEM_EXEMPTED" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

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

无

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

无

评论列表 撰写评论 向官方投诉

暂无用户评论。