更新记录

1.0.3（2026-07-30） 下载此版本

更新

平台兼容性

目录结构

uniplugin_singbox/
├── package.json          # 配置文件
├── android/              # Android 原生代码
│   ├── build.gradle      # Gradle 配置
│   ├── libbox.aar        # Sing-box 核心库
│   └── libs/
│       └── libbox.aar    # 依赖库

项目配置

package.json 配置

{
    "name": "uniplugin_singbox",
    "id": "uniplugin_singbox",
    "version": "1.0.0",
    "description": "Singbox VPN Connection Plugin",
    "_dp_type": "nativeplugin",
    "_dp_nativeplugin": {
        "android": {
            "plugins": [
                {
                    "type": "module",
                    "name": "uniplugin_singbox",
                    "class": "io.dcloud.uniplugin.singbox.SingboxPlugin"
                }
            ],
            "integrateType": "aar",
            "minSdkVersion": 24
        },
        "ios": {}
    }
}

manifest.json 配置

在项目的 manifest.json 中声明使用该uniplugin_singbox：

{
    "nativePlugins": {
        "uniplugin_singbox": {}
    }
}

全局 API

应用启动时会在 global.$singbox 挂载封装好的 VPN 方法，支持跨页面调用：

方法列表

服务器对象结构

{
    id: 1,
    name: '服务器名称',
    address: '服务器地址',
    port: 13124,
    type: 'vmess',
    uuid: '30406f69-f382-401c-8a24-1e807fc873d7',
    security: 'auto',
    alterId: 0,
    enabled: true,
    config: {} // 可选：完整 Sing-box 配置
}

使用示例

// 连接 VPN
global.$singbox.connectVPN(server, function(result) {
    if (result.status === 'success') {
        console.log('VPN 连接成功')
    }
})

// 断开 VPN
global.$singbox.disconnectVPN(function(result) {
    console.log('断开结果:', result)
})

// 获取状态
global.$singbox.getVPNStatus(function(status) {
    console.log('连接状态:', status.connected)
})

// 获取流量统计
global.$singbox.getTrafficStats(function(stats) {
    console.log('上传:', stats.upload)
    console.log('下载:', stats.download) 
})

调用方法

通过 uni.requireNativePlugin('uniplugin_singbox') 获取实例后调用：

方法列表

connect 方法参数

// 简单参数模式
{
    server: '服务器地址',
    port: 13124,
    type: 'vmess',
    uuid: 'uuid值',
    security: 'auto'
}

// 完整配置模式
{
    config: { /* Sing-box 完整配置对象 */ }
}

getVPNStatus 返回格式

{
    connected: true/false,
    server: '服务器名称',
    address: '服务器地址',
    port: 13124,
    type: 'vmess',
    simulated: false
}

getTrafficStats 返回格式

{
    upload: '125.67',    // 上传流量
    download: '512.34',  // 下载流量
    simulated: false
}

## 连接流程

用户选择服务器 ↓ 检查平台（仅 Android 支持原生 VPN） ↓ 检查是否加载 ↓ 请求 VPN 权限（首次连接） ↓ 调用 connect 方法 ↓ 启动状态检查定时器（每 3 秒检查一次） ↓ 连接成功/失败回调

## 注意事项

1. **平台限制**：当前仅支持 Android 平台，iOS 平台使用模拟连接
2. **权限要求**：需要 VPN 权限和通知权限
3. **Android 版本**：最低支持 Android 7.0 (API 24)
4. **非 Android 平台**：会自动使用模拟连接，仅用于 UI 测试
5. **状态检查**：连接成功后会自动启动每 3 秒一次的状态检查
6. **配置兼容**：支持简单参数模式和完整配置模式两种连接方式

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | - | 初始版本 |

## 调试命令

```javascript
// 显示调试信息
global.$singbox.showDebugInfo()

输出示例：

========== 调试信息 ==========
平台: Android
连接状态: 已连接
当前服务器: test-ur7m2l65
服务器数量: 3
方法: ["connect", "disconnect", "forceDisconnect", "getStatus", ...]
==============================