flutter_v2ray_client

flutter_v2ray_client

⚡ 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

Example app demonstrating flutter_v2ray_client features

📱 Supported Platforms

Platform	Status	Info
Android	Done ✅	Xray 25.9.11
iOS	Coming Soon	Support via Donations
Windows	Coming Soon	Support via Donations
Linux	Coming Soon	Support via Donations
macOS	Coming Soon	Support via Donations

Note: Support for iOS, Windows, Linux, and macOS can be accelerated through Donations. Please see the Donation section below to contribute and help prioritize platform development.

🚀 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: ^1.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,
);

🤖 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

💡 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.

💰 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!