flutter_v2ray_client #

Table of contents #

• flutter_v2ray_client
  • Table of contents
  • ⚡ Features
  • 📸 Screenshots
  • 📱 Supported Platforms
  • 🚀 Get started
    • 🔗 Add dependency
    • 💡 Examples
      • URL Parser
      • Edit Configuration
      • Making V2Ray connection
      • Exclude specific apps from VPN (blockedApps)
      • Bypass LAN Traffic
      • View and manage V2Ray logs (Android)
  • 🤖 Android configuration before publish to Google Play🚀
    • Android 16 KB Page Size Support
    • gradle.properties
    • build.gradle (app)
  • 🔮 Roadmap & Future Enhancements
    • 🚀 Performance Improvements
    • 🌟 Planned Features
    • 💡 Community Contributions
  • 📋 Attribution
  • 💰 Donation

⚡ Features #

• Run V2Ray Proxy & VPN Mode
• Get Server Delay (outbound and connected)
• Parsing V2Ray sharing links and making changes to them
• Built-in socket protection for Android VPN tunneling
• Live status updates: connection state, speeds, traffic, duration

📸 Screenshots #

Main Screen	Logs Screen

Example app demonstrating flutter_v2ray_client features

📱 Supported Platforms #

Note: Windows version will be released by November 13, 2025. Limited-time 30% discount for pre-orders. Contact us on Telegram for more details.

🚀 Get started #

🔗 Add dependency #

You can use the command to add flutter_v2ray_client as a dependency with the latest stable version:

$ flutter pub add flutter_v2ray_client

Or you can manually add flutter_v2ray_client into the dependencies section in your pubspec.yaml:

dependencies:
  flutter_v2ray_client: ^3.0.0

💡 Examples #

URL Parser

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

// v2ray share link like vmess://, vless://, ...
String link = "link_here";
V2RayURL parser = V2ray.parseFromURL(link);

// Remark of the v2ray
print(parser.remark);

// generate full v2ray configuration (json)
print(parser.getFullConfiguration());

Edit Configuration

// Change v2ray listening port
parser.inbound['port'] = 10890;
// Change v2ray listening host
parser.inbound['listen'] = '0.0.0.0';
// Change v2ray log level
parser.log['loglevel'] = 'info';
// Change v2ray dns
parser.dns = {
    "servers": ["1.1.1.1"]
};
// and ...

// generate configuration with new settings
parser.getFullConfiguration()

Making V2Ray connection

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

final V2ray v2ray = V2ray(
    onStatusChanged: (status) {
        // Handle status changes: connected, disconnected, etc.
        print('V2Ray status: ${status.state}');
    },
);

// You must initialize V2Ray before using it.
await v2ray.initialize(
    notificationIconResourceType: "mipmap",
    notificationIconResourceName: "ic_launcher",
);

// v2ray share link like vmess://, vless://, ...
String link = "link_here";
V2RayURL parser = V2ray.parseFromURL(link);

// Get Server Delay
print('${await v2ray.getServerDelay(config: parser.getFullConfiguration())}ms');

// Permission is not required if using proxy only
if (await v2ray.requestPermission()){
    v2ray.startV2Ray(
        remark: parser.remark,
        // The use of parser.getFullConfiguration() is not mandatory,
        // and you can enter the desired V2Ray configuration in JSON format
        config: parser.getFullConfiguration(),
        blockedApps: null,
        bypassSubnets: null,
        proxyOnly: false,
    );
}

// Disconnect
v2ray.stopV2Ray();

Exclude specific apps from VPN (blockedApps)

// Provide Android package names to exclude from VPN tunneling.
// Traffic from these apps will NOT go through the VPN tunnel.
final List<String> blockedApps = <String>[
  'com.whatsapp',
  'com.google.android.youtube',
  'com.instagram.android',
];

await v2ray.startV2Ray(
  remark: parser.remark,
  config: parser.getFullConfiguration(),
  blockedApps: blockedApps, // <— excluded from VPN
  bypassSubnets: null,
  proxyOnly: false,
);

Tips:

• Android package names are required (e.g., com.example.app).
• To find a package name, you can:
  • Use: adb shell pm list packages | grep <keyword>
  • Or check Play Store URL (e.g., id=com.whatsapp).
• If you want to make this user-selectable, let users pick apps then store their package names and pass them as blockedApps.
• This mirrors how the app code uses blockedApps in lib/services/v2ray_service.dart when starting V2Ray.

Bypass LAN Traffic

final List<String> subnets = [
    "0.0.0.0/5",
    "8.0.0.0/7",
    "11.0.0.0/8",
    "12.0.0.0/6",
    "16.0.0.0/4",
    "32.0.0.0/3",
    "64.0.0.0/2",
    "128.0.0.0/3",
    "160.0.0.0/5",
    "168.0.0.0/6",
    "172.0.0.0/12",
    "172.32.0.0/11",
    "172.64.0.0/10",
    "172.128.0.0/9",
    "173.0.0.0/8",
    "174.0.0.0/7",
    "176.0.0.0/4",
    "192.0.0.0/9",
    "192.128.0.0/11",
    "192.160.0.0/13",
    "192.169.0.0/16",
    "192.170.0.0/15",
    "192.172.0.0/14",
    "192.176.0.0/12",
    "192.192.0.0/10",
    "193.0.0.0/8",
    "194.0.0.0/7",
    "196.0.0.0/6",
    "200.0.0.0/5",
    "208.0.0.0/4",
    "240.0.0.0/4",
];

v2ray.startV2Ray(
    remark: parser.remark,
    config: parser.getFullConfiguration(),
    blockedApps: null,
    bypassSubnets: subnets,
    proxyOnly: false,
);

View and manage V2Ray logs (Android)

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

final v2ray = V2ray(onStatusChanged: (_) {});

// Fetch logs from Android logcat (oldest -> newest)
final List<String> logs = await v2ray.getLogs();

// Clear logcat buffer (Android only)
final bool cleared = await v2ray.clearLogs();

Notes:

• Android only. Other platforms return empty results / true on clear.
• Logs are returned in chronological order (oldest → newest).
• Internally, the plugin keeps a small in-memory buffer capped at ~500 lines for low memory usage.
• The example app includes a "View Logs" page with:
  • Search/filter text box
  • Copy button that copies currently filtered logs and prefixes type: [ERROR], [WARN], [INFO]
  • Refresh to re-fetch from logcat
  • Clear to clear logcat
  • Automatic scroll to bottom on refresh and search
  • Bottom-only safe area padding so content stays above navigation gestures

🤖 Android configuration before publish to Google Play🚀 #

Android 16 KB Page Size Support #

This package fully supports Android's 16 KB page size, ensuring compatibility with the latest Android devices and requirements for Google Play Store publishing. The plugin is built with modern Android development practices that handle both 4 KB and 16 KB page sizes seamlessly.

gradle.properties #

• add this line

android.bundle.enableUncompressedNativeLibs = false

build.gradle (app) #

• Find the buildTypes block:

buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
               signingConfig signingConfigs.release
        }
    }

• And replace it with the following configuration info:

splits {
        abi {
            enable true
            reset()
            //noinspection ChromeOsAbiSupport
            include "x86_64", "armeabi-v7a", "arm64-v8a"

            universalApk true
        }
    }

   buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
               signingConfig signingConfigs.release
               ndk {
                //noinspection ChromeOsAbiSupport
                abiFilters "x86_64", "armeabi-v7a", "arm64-v8a"
                debugSymbolLevel 'FULL'
            }
        }
    }

🔮 Roadmap & Future Enhancements #

🚀 Performance Improvements #

• hev-socks5-tunnel Integration: Implement hev-socks5-tunnel for significantly better performance in terms of speed and resource usage
• High-performance SOCKS5 tunneling with lower CPU and memory consumption
• Enhanced connection stability and throughput

🌟 Planned Features #

• Enhanced multi-platform support (iOS, Windows, Linux, macOS)
• Advanced traffic routing and filtering options
• Improved user interface components
• Extended protocol support
• Widgets for mobile devices

💡 Community Contributions #

We welcome contributions from the community! If you're interested in helping implement any of these features, please check our contribution guidelines and feel free to open issues or pull requests.

📋 Attribution #

This project uses third-party libraries and resources. See 📋 ATTRIBUTION.md for details.

All rights reserved.

💰 Donation #

If you liked this package and want to accelerate the development of iOS and desktop platform support, consider supporting the project with a donation below. Your contributions will directly help bring flutter_v2ray_client to more platforms faster!