Перейти к содержанию

Настройка среды разработки

Обзор

Это руководство предоставляет комплексные инструкции по настройке среды разработки для мобильного приложения CulicidaeLab Flutter. Проект поддерживает как контейнеризованную разработку с использованием VS Code Dev Containers, так и ручную локальную настройку.

Предварительные требования

Системные требования

  • Операционная система: Windows 10/11, macOS 10.14+ или Ubuntu 18.04+
  • ОЗУ: Минимум 8ГБ, рекомендуется 16ГБ
  • Хранилище: Не менее 10ГБ свободного места для инструментов разработки и зависимостей
  • Сеть: Стабильное интернет-соединение для загрузки зависимостей

Необходимые инструменты

  • Git: Система контроля версий
  • VS Code: Рекомендуемая IDE с расширениями Flutter
  • Docker: Для контейнеризованной разработки (опционально, но рекомендуется)

Вариант 1: Настройка Dev Container (Рекомендуется)

Самый простой способ начать — использовать предоставленную конфигурацию Dev Container, которая обеспечивает согласованную среду разработки на всех платформах.

Предварительные требования для Dev Container

  1. Установите Docker Desktop
  2. Windows: Загрузите с Docker Desktop для Windows
  3. macOS: Загрузите с Docker Desktop для Mac

  4. Linux: Следуйте руководству по установке Docker Engine

  5. Установите VS Code

  6. Загрузите с Visual Studio Code

  7. Установите расширение Dev Containers

  8. Откройте VS Code
  9. Перейдите в Расширения (Ctrl+Shift+X)
  10. Найдите "Dev Containers" от Microsoft
  11. Установите расширение

Настройка Dev Container

  1. Клонируйте репозиторий 

    git clone https://github.com/your-org/culicidaelab.git
cd culicidaelab

  2. Откройте в Dev Container

  3. Откройте VS Code
  4. Откройте папку проекта
  5. VS Code должен обнаружить конфигурацию .devcontainer

  6. Нажмите "Reopen in Container" при появлении запроса, или:

    • Нажмите Ctrl+Shift+P (Cmd+Shift+P на Mac)
    • Введите "Dev Containers: Reopen in Container"
    • Выберите команду

  7. Дождитесь сборки контейнера

  8. Первая сборка может занять 10-15 минут
  9. Последующие запуски будут намного быстрее

  10. Контейнер включает:

    • Flutter SDK 3.29.3
    • Android SDK с Platform 35
    • Android Build Tools 34.0.0
    • Android NDK 27.0.12077973
    • Java 17
    • Все необходимые инструменты разработки

  11. Проверьте установку 

    flutter doctor

  12. Это должно показать все галочки для разработки Android
  13. Разработка iOS будет показана как недоступная (ожидаемо в Linux контейнере)

Функции Dev Container

Dev container включает:

  • Предварительно настроенный Flutter SDK: Последняя стабильная версия с поддержкой Android
  • Инструменты разработки Android: Полный Android SDK, NDK и инструменты сборки
  • Расширения VS Code: Flutter, Dart и полезные расширения для разработки
  • Поддержка USB устройств: Возможности отладки физических устройств
  • Перенаправление портов: Автоматическое перенаправление портов для серверов разработки

Вариант 2: Ручная локальная настройка

Если вы предпочитаете настроить среду разработки вручную или не можете использовать Docker, следуйте этим платформо-специфическим инструкциям.

Настройка Windows

  1. Установите Git
  2. Загрузите с Git для Windows

  3. Используйте опции установки по умолчанию

  4. Установите Flutter SDK 

    # Загрузите Flutter SDK
Invoke-WebRequest -Uri "https://storage.googleapis.com/flutter_infra_release/releases/stable/windows/flutter_windows_3.29.3-stable.zip" -OutFile "flutter_sdk.zip"

# Извлеките в C:\flutter
Expand-Archive -Path "flutter_sdk.zip" -DestinationPath "C:\"

# Добавьте в PATH
$env:PATH += ";C:\flutter\bin"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, [EnvironmentVariableTarget]::User)

  5. Установите Android Studio

  6. Загрузите с Android Studio
  7. Установите с опциями по умолчанию
  8. Откройте Android Studio и завершите мастер настройки

  9. Установите Android SDK Platform 35 и Build Tools 34.0.0

  10. Настройте Android SDK 

    # Установите переменные окружения
[Environment]::SetEnvironmentVariable("ANDROID_SDK_ROOT", "$env:LOCALAPPDATA\Android\Sdk", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\Android\Sdk", [EnvironmentVariableTarget]::User)

  11. Установите VS Code и расширения

  12. Загрузите VS Code с code.visualstudio.com
  13. Установите расширения Flutter и Dart

Настройка macOS

  1. Установите Homebrew (если еще не установлен) 

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Установите Git 

    brew install git

  3. Установите Flutter SDK 

    # Загрузите и извлеките Flutter
cd ~/development
curl -O https://storage.googleapis.com/flutter_infra_release/releases/stable/macos/flutter_macos_3.29.3-stable.zip
unzip flutter_macos_3.29.3-stable.zip

# Добавьте в PATH
echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

  4. Установите Android Studio

  5. Загрузите с Android Studio
  6. Установите и завершите мастер настройки

  7. Установите необходимые компоненты SDK

  8. Установите Xcode (для разработки iOS) 

    # Установите Xcode из App Store
# Установите инструменты командной строки Xcode
sudo xcode-select --install

  9. Настройте окружение 

    # Добавьте Android SDK в PATH
echo 'export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk' >> ~/.zshrc
echo 'export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools' >> ~/.zshrc
source ~/.zshrc

Настройка Linux (Ubuntu)

  1. Обновите систему 

    sudo apt update && sudo apt upgrade -y

  2. Установите зависимости 

    sudo apt install -y curl git unzip xz-utils zip libglu1-mesa openjdk-17-jdk

  3. Установите Flutter SDK 

    # Загрузите Flutter
cd ~/development
wget https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.29.3-stable.tar.xz
tar xf flutter_linux_3.29.3-stable.tar.xz

# Добавьте в PATH
echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.bashrc
source ~/.bashrc

  4. Установите Android Studio 

    # Загрузите Android Studio
wget https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2023.1.1.28/android-studio-2023.1.1.28-linux.tar.gz
tar -xzf android-studio-*-linux.tar.gz -C ~/development/

# Запустите Android Studio
~/development/android-studio/bin/studio.sh

  5. Настройте окружение 

    # Установите переменные окружения
echo 'export ANDROID_SDK_ROOT=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools' >> ~/.bashrc
source ~/.bashrc

Настройка проекта

Клонирование и инициализация

  1. Клонируйте репозиторий 

    git clone https://github.com/your-org/culicidaelab.git
cd culicidaelab

  2. Установите зависимости 

    flutter pub get

  3. Проверьте настройку 

    flutter doctor

  4. Решите любые проблемы, показанные flutter doctor
  5. Убедитесь, что Android toolchain показывает зеленую галочку

Конфигурация IDE

Настройка VS Code

  1. Установите расширения
  2. Flutter (Dart-Code.flutter)
  3. Dart (Dart-Code.dart-code)
  4. EditorConfig (EditorConfig.EditorConfig)

  5. VSCode Icons (vscode-icons-team.vscode-icons)

  6. Настройте параметры Создайте .vscode/settings.json: 

    {
  "dart.flutterSdkPath": "/path/to/flutter",
  "dart.lineLength": 120,
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.detectIndentation": false,
  "dart.previewFlutterUiGuides": true,
  "dart.previewFlutterUiGuidesCustomTracking": true,
  "dart.debugExternalLibraries": false,
  "dart.debugSdkLibraries": false,
  "files.autoSave": "afterDelay"
}

Настройка Android Studio

  1. Установите плагин Flutter
  2. Перейдите в File → Settings → Plugins
  3. Найдите "Flutter" и установите

  4. Перезапустите Android Studio

  5. Настройте пути SDK

  6. Перейдите в File → Project Structure
  7. Проверьте путь Android SDK
  8. Установите путь Flutter SDK

Настройка устройства

Настройка устройства Android

Физическое устройство

  1. Включите параметры разработчика
  2. Перейдите в Настройки → О телефоне
  3. Нажмите "Номер сборки" 7 раз

  4. Вернитесь в Настройки → Параметры разработчика

  5. Включите отладку по USB

  6. В параметрах разработчика включите "Отладка по USB"
  7. Подключите устройство через USB

  8. Примите авторизацию отладки на устройстве

  9. Проверьте соединение 

    flutter devices

Эмулятор Android

  1. Создайте AVD
  2. Откройте Android Studio
  3. Перейдите в Tools → AVD Manager
  4. Создайте виртуальное устройство
  5. Выберите Pixel 4 или аналогичный
  6. Выберите API Level 35 (Android 14)

  7. Завершите настройку

  8. Запустите эмулятор 

    flutter emulators --launch <emulator_id>

Настройка устройства iOS (только macOS)

Физическое устройство

  1. Установите сертификат разработки iOS
  2. Откройте Xcode
  3. Перейдите в Preferences → Accounts
  4. Добавьте Apple ID

  5. Загрузите сертификаты разработки

  6. Настройте устройство

  7. Подключите iOS устройство
  8. Доверьтесь компьютеру на устройстве
  9. Включите режим разработчика в настройках

Симулятор iOS

  1. Установите симулятор 

    sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
open -a Simulator

  2. Проверьте настройку 

    flutter devices

Запуск приложения

Режим разработки

  1. Запустите приложение 

    # Запуск на подключенном устройстве/эмуляторе
flutter run

# Запуск на конкретном устройстве
flutter run -d <device_id>

# Запуск с горячей перезагрузкой
flutter run --hot

  2. Функции режима отладки

  3. Горячая перезагрузка: Нажмите r в терминале или сохраните файлы
  4. Горячий перезапуск: Нажмите R в терминале
  5. Инспектор отладки: Нажмите w в терминале

Режимы сборки

  1. Отладочная сборка 

    flutter build apk --debug

  2. Релизная сборка 

    flutter build apk --release

  3. Профильная сборка 

    flutter build apk --profile

Устранение неполадок

Распространенные проблемы

Проблемы Flutter Doctor

  1. Проблемы с лицензиями Android 

    flutter doctor --android-licenses
    Примите все лицензии при запросе.

  2. Android SDK не найден

  3. Проверьте переменную окружения ANDROID_SDK_ROOT

  4. Убедитесь, что Android SDK установлен в правильном месте

  5. Проблемы Flutter SDK 

    flutter channel stable
flutter upgrade
flutter doctor

Проблемы сборки

  1. Ошибки сборки Gradle 

    cd android
./gradlew clean
cd ..
flutter clean
flutter pub get

  2. Конфликты зависимостей 

    flutter pub deps
flutter pub upgrade

Проблемы подключения устройства

  1. Проблемы ADB 

    adb kill-server
adb start-server
flutter devices

  2. Отладка по USB не работает

  3. Попробуйте другой USB кабель
  4. Включите режим "Передача файлов" на устройстве
  5. Отзовите авторизации отладки по USB и переподключитесь

Проблемы производительности

  1. Медленное время сборки
  2. Увеличьте память Gradle: Добавьте org.gradle.jvmargs=-Xmx4g в android/gradle.properties
  3. Используйте флаг --no-sound-null-safety если нужно

  4. Очистите кэш сборки: flutter clean

  5. Горячая перезагрузка не работает

  6. Убедитесь, что вы в режиме отладки
  7. Проверьте синтаксические ошибки
  8. Перезапустите сессию отладки

Рабочий процесс разработки

Рекомендуемый рабочий процесс

  1. Начните сессию разработки 

    # Откройте проект в VS Code
code .

# Запустите устройство/эмулятор
flutter devices
flutter run

  2. Цикл разработки

  3. Внесите изменения в код
  4. Сохраните файлы (автоматическая горячая перезагрузка)
  5. Протестируйте изменения на устройстве

  6. Зафиксируйте изменения с осмысленными сообщениями

  7. Тестирование 

    # Запустите модульные тесты
flutter test

# Запустите интеграционные тесты
flutter test integration_test/

# Запустите конкретный тестовый файл
flutter test test/unit/services/classification_service_test.dart

  8. Качество кода 

    # Форматируйте код
flutter format .

# Анализируйте код
flutter analyze

# Проверьте устаревшие зависимости
flutter pub outdated

Следующие шаги

После завершения настройки среды разработки:

  1. Прочитайте документацию по архитектуре: Поймите структуру и паттерны приложения
  2. Просмотрите руководство по структуре проекта: Изучите организацию директорий и соглашения
  3. Проверьте руководящие принципы участия: Поймите рабочий процесс разработки и стандарты
  4. Запустите набор тестов: Убедитесь, что все работает правильно
  5. Начните с небольших изменений: Внесите незначительное изменение, чтобы ознакомиться с кодовой базой

Получение помощи

Если вы столкнулись с проблемами во время настройки:

  1. Проверьте Flutter Doctor: Запустите flutter doctor -v для подробной диагностики
  2. Просмотрите логи: Проверьте вывод консоли на предмет конкретных сообщений об ошибках
  3. Поищите в документации: Документация Flutter и Android часто содержит решения
  4. Попросите помощи: Создайте задачу в репозитории проекта с:
  5. Вашей операционной системой и версией
  6. Выводом flutter doctor
  7. Полными сообщениями об ошибках
  8. Шагами, которые вы уже попробовали

Дополнительные ресурсы