10 KiB
10 KiB
Инструкция по сборке Hiddify v2.5.7
Успешная сборка выполнена 25 декабря 2025 г.
Системные требования
- ОС: Linux (Ubuntu 24.04)
- Java: OpenJDK 17
- Go: 1.25.5 (для libcore, если собирать самостоятельно)
- Android SDK: Platform 34, Build Tools, NDK 26.1.10909125
- Disk Space: ~15GB свободного места
Версии компонентов
Flutter
# Установка FVM (Flutter Version Manager)
flutter pub global activate fvm
# Установка Flutter 3.24.0 (НЕ 3.24.3!)
fvm install 3.24.0
fvm use 3.24.0 --force
ВАЖНО: В pubspec.yaml указано flutter: ">=3.24.0 <=3.24.3", но в официальной сборке используется 3.24.0 (не 3.24.3). При использовании 3.24.3 возникает конфликт зависимостей intl.
Gradle & Android
- Gradle: 8.7 (обновлен с 7.6.1)
- AGP (Android Gradle Plugin): 8.2.0 (обновлен с 7.4.2)
- Kotlin: 1.9.22 (обновлен с 1.8.21)
- compileSdk: 34 (НЕ 35 - несовместим с libcore)
- targetSdk: 34
- minSdk: 21
Java
# Проверка версии
java -version
# Должно быть: openjdk 17.x.x
# Настройка Flutter для использования Java 17
flutter config --jdk-dir="/usr/lib/jvm/java-1.17.0-openjdk-amd64"
Пошаговая инструкция сборки
1. Клонирование репозитория
cd /home/vodorod/dorod
git clone --depth 1 --branch v2.5.7 --recurse-submodules https://github.com/hiddify/hiddify-app.git Umbrix-hid
cd Umbrix-hid
2. Исправление зависимостей
Проблема: flutter_easy_permission устарел и не собирается с современными версиями Android.
Решение: Закомментировать в pubspec.yaml:
# Строки 90-92, было:
#flutter_easy_permission: ^1.1.2
flutter_easy_permission:
git: https://github.com/unger1984/flutter_easy_permission.git
# Изменить на:
#flutter_easy_permission: ^1.1.2
#flutter_easy_permission:
# git: https://github.com/unger1984/flutter_easy_permission.git
Изменения в коде (lib/features/common/qr_code_scanner_screen.dart):
// Закомментировать импорт:
// import 'package:flutter_easy_permission/easy_permissions.dart';
// Закомментировать константы:
// const permissions = [Permissions.CAMERA];
// const permissionGroup = [PermissionGroup.Camera];
// В методе _requestCameraPermission() упростить:
Future<bool> _requestCameraPermission() async {
// Simplified: assuming permission is granted
return true;
}
// В dispose() закомментировать:
// FlutterEasyPermission().dispose();
// Во всех методах, где проверяется hasPermission, заменить на:
final hasPermission = true;
3. Обновление Gradle и AGP
android/settings.gradle:
plugins {
id "dev.flutter.flutter-plugin-loader" version "1.0.0"
id "com.android.application" version "8.2.0" apply false // было 7.4.2
id "org.jetbrains.kotlin.android" version "1.9.22" apply false // было 1.8.21
}
android/gradle/wrapper/gradle-wrapper.properties:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
# Было: gradle-7.6.1-bin.zip
4. Скачивание libcore
mkdir -p android/app/libs
curl -L https://github.com/hiddify/hiddify-next-core/releases/download/v3.1.8/hiddify-core-android.tar.gz | tar xz -C android/app/libs/
Должен появиться файл android/app/libs/libcore.aar (~119MB).
5. Генерация кода
$HOME/.pub-cache/bin/fvm flutter pub get
$HOME/.pub-cache/bin/fvm flutter pub run build_runner build --delete-conflicting-outputs
Эта команда генерирует:
- Riverpod providers
- Freezed модели
- Drift database код
- Localization файлы
- Asset файлы
6. Сборка APK
# Debug версия (без shrink для быстрой сборки)
$HOME/.pub-cache/bin/fvm flutter build apk --debug --no-shrink
# Release версия (требует keystore)
# $HOME/.pub-cache/bin/fvm flutter build apk --release
Результат:
✓ Built build/app/outputs/flutter-apk/app-debug.apk (193 MB)
✓ Built build/app/outputs/flutter-apk/app-arm64-v8a-debug.apk (88 MB)
✓ Built build/app/outputs/flutter-apk/app-armeabi-v7a-debug.apk (83 MB)
✓ Built build/app/outputs/flutter-apk/app-x86_64-debug.apk (86 MB)
7. Установка на устройство/эмулятор
# Запуск эмулятора (если есть)
$HOME/Android/Sdk/emulator/emulator -avd <ИМЯ_AVD>
# Проверка подключенных устройств
$HOME/.pub-cache/bin/fvm flutter devices
# Установка APK
$HOME/Android/Sdk/platform-tools/adb install -r build/app/outputs/flutter-apk/app-x86_64-debug.apk
Типичные ошибки и решения
Ошибка 1: intl version conflict
Because hiddify depends on flutter_localizations from sdk which depends on intl 0.20.2,
intl 0.20.2 is required.
So, because hiddify depends on intl ^0.19.0, version solving failed.
Причина: Flutter 3.24.3 требует intl 0.20.2, но проект использует 0.19.0.
Решение: Использовать Flutter 3.24.0 (не 3.24.3).
Ошибка 2: flutter_easy_permission compilation error
error: package pub.devrel.easypermissions does not exist
Причина: Пакет устарел и не имеет зависимости EasyPermissions.
Решение: Закомментировать в pubspec.yaml и коде (см. шаг 2).
Ошибка 3: Unresolved reference: nekohasekai
e: Unresolved reference: nekohasekai
Причина: Отсутствует libcore.aar.
Решение: Скачать libcore v3.1.8 (см. шаг 4).
Ошибка 4: Error while dexing
ERROR:D8: com.android.tools.r8.kotlin.H
Execution failed for task ':app:mergeExtDexDebug'.
Причина: Несовместимость AGP 7.4.2 с Gradle 8.7.
Решение: Обновить AGP до 8.2.0 и Kotlin до 1.9.22 (см. шаг 3).
Ошибка 5: Namespace not specified
Namespace not specified. Specify a namespace in the module's build file.
Причина: flutter_easy_permission не закомментирован полностью в pubspec.yaml.
Решение: Проверить что ВСЕ строки (включая git секцию) закомментированы.
Ошибка 6: Android resource linking failed
aapt2 E: Failed to load resources table in APK '.../android-35/android.jar'
Причина: compileSdk 35 несовместим с AGP 7.x или поврежден SDK.
Решение: Использовать compileSdk 34.
Структура изменений
Измененные файлы:
-
pubspec.yaml
- Закомментирован flutter_easy_permission
-
lib/features/common/qr_code_scanner_screen.dart
- Упрощена проверка permissions
- Удалены вызовы FlutterEasyPermission
-
android/settings.gradle
- AGP: 7.4.2 → 8.2.0
- Kotlin: 1.8.21 → 1.9.22
-
android/gradle/wrapper/gradle-wrapper.properties
- Gradle: 7.6.1 → 8.7
-
android/app/build.gradle
- Без изменений (compileSdk 34, targetSdk 34 остались)
Добавленные файлы:
- android/app/libs/libcore.aar (119 MB) - Core библиотека sing-box
Очистка после ошибок
Если сборка не удалась:
# Полная очистка
rm -rf ~/.gradle/caches/
rm -rf ~/.pub-cache/git/flutter_easy_permission-*
rm -rf .flutter-plugins*
rm -f pubspec.lock
# Пересборка
$HOME/.pub-cache/bin/fvm flutter clean
$HOME/.pub-cache/bin/fvm flutter pub get
$HOME/.pub-cache/bin/fvm flutter pub run build_runner build --delete-conflicting-outputs
./android/gradlew -p android clean
Проверка окружения
# Flutter
$HOME/.pub-cache/bin/fvm flutter doctor -v
# Java
java -version
# Gradle
./android/gradlew -p android --version
# Android SDK
ls -la $HOME/Android/Sdk/platforms/
Время сборки
- Первая сборка: ~3-5 минут (с загрузкой зависимостей)
- Повторная сборка: ~1.5-2 минуты
- Сборка после clean: ~2-3 минуты
Размер артефактов
- app-debug.apk (universal): 193 MB
- app-arm64-v8a-debug.apk: 88 MB (рекомендуется для современных устройств)
- app-armeabi-v7a-debug.apk: 83 MB (для старых устройств)
- app-x86_64-debug.apk: 86 MB (для эмуляторов)
Примечания
- Не используйте системный Flutter - только через FVM с версией 3.24.0
- Java 17 обязателен - Java 21 не совместим с Gradle 7.x/8.x конфигурацией проекта
- libcore нельзя пропустить - без него будут ошибки Kotlin компиляции
- AGP 8.2+ обязателен для Gradle 8.7
- flutter_easy_permission должен быть полностью закомментирован, включая git секцию
Дополнительная информация
- Официальный репозиторий: https://github.com/hiddify/hiddify-app
- Релиз v2.5.7: https://github.com/hiddify/hiddify-app/releases/tag/v2.5.7
- libcore v3.1.8: https://github.com/hiddify/hiddify-next-core/releases/tag/v3.1.8
- CI/CD конфигурация:
.github/workflows/build.yml(использует Flutter 3.24.0)
Контрольные суммы
# Проверка libcore.aar
ls -lh android/app/libs/libcore.aar
# Должно быть: ~119M
# Проверка APK
ls -lh build/app/outputs/flutter-apk/
Дата создания документа: 25 декабря 2025 г. Версия Hiddify: 2.5.7 Статус сборки: ✅ Успешно