Управление переменными окружения в Flutter Web

Эта статья переведена специально для канала FlutterPulse. В этом канале вы найдёте много интересных вещей, связанных с Flutter. Не забывайте подписываться! 🚀

Введение

Введение

Управление переменными окружения в Flutter Web требует другого подхода по сравнению с мобильными приложениями. Поскольку Flutter Web не может читать .env файлы с сервера, нам нужна гибридная стратегия:

✅ Используйте flutter_dotenv для локальной разработки (загружает .env файлы).
✅ Используйте dart-define для развертывания (поскольку .env нельзя использовать на серверах продакшена).
✅ Настройте VS Code для удобного переключения окружений.

Это руководство проведет вас через лучший способ управления переменными окружения в Flutter Web. 🚀

1. Установка зависимостей

Выполните следующую команду для добавления поддержки dotenv:

flutter pub add flutter_dotenv

2. Создание файлов окружения

В корне проекта Flutter создайте три .env файла:

.env.dev

API_URL=https://api.dev.local

.env.uat

API_URL=https://api.uat.local

.env.prod

API_URL=https://api.prod.local

Игнорирование .env файлов в Git

Измените .gitignore чтобы предотвратить коммит файлов окружения:

.env*

Также зарегистрируйте .env файлы в вашем pubspec.yaml в разделе assets:

flutter:
  assets:
    - .env.dev
    - .env.uat
    - .env.prod

3. Создание отдельного файла env_config.dart

Вместо управления переменными окружения в main.dart, создайте отдельный файл для поддержания чистоты кода.

lib/core/env_config.dart

import 'package:flutter_dotenv/flutter_dotenv.dart';

class EnvConfig {
  /// Проверяет, запущено ли приложение на Web
  static final bool isWeb = const bool.fromEnvironment('IS_WEB', defaultValue: false);

  /// Читает тип окружения (dev, uat, prod) из `dart-define`. По умолчанию 'dev'.
  static final String env = const String.fromEnvironment('ENV', defaultValue: 'dev');

  /// Загружает правильный файл окружения для локальной разработки.
  static Future<void> loadEnv() async {
    if (!isWeb) {
      String envFile = '.env.$env';
      try {
        await dotenv.load(fileName: envFile);
      } catch (e) {
        throw Exception('Не удалось загрузить файл окружения: $envFile. Убедитесь, что он существует.');
      }
    }
  }

  /// Получает URL API из `dart-define` или файла `.env`.
  static String get apiUrl {
    return const String.fromEnvironment('API_URL', defaultValue: '')
        .isNotEmpty
        ? const String.fromEnvironment('API_URL')
        : dotenv.env['API_URL'] ?? 'https://api.default.com';
  }
}

Почему такой подход?

✅ Обеспечивает динамическую загрузку правильного файла .env
✅ Поддерживает как локальную разработку (dotenv) и развертывание (dart-define)
✅ Предотвращает ошибки отсутствия файла окружения

4. Обновление main.dart

Измените main.dart, чтобы правильно загружать переменные окружения.

main.dart

import 'package:flutter/material.dart';
import 'core/env_config.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EnvConfig.loadEnv();

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Web Env',
      home: Scaffold(
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text('API_URL: ${EnvConfig.apiUrl}'),
            ],
          ),
        ),
      ),
    );
  }
}

5. Запуск и развертывание приложения

Для локальной разработки (Используя .env)

Запустите приложение с соответствующим файлом окружения:

flutter run --dart-define=ENV=dev

Это загружает .env.dev. Аналогично для UAT и Prod:

flutter run --dart-define=ENV=uat
flutter run --dart-define=ENV=prod

Для веб-развертывания (Используя dart-define)

Поскольку файлы .env нельзя читать в продакшене, мы передаем значения с помощью dart-define.

Для Production:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=prod --dart-define=API_URL=https://api.prod.com

Для UAT:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=uat --dart-define=API_URL=https://api.uat.com

Для Dev:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=dev --dart-define=API_URL=https://api.dev.com

6. Настройка VS Code для быстрого переключения сред

Чтобы упростить переключение сред, настройте файл .vscode/launch.json.

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter Web (Dev)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=dev"],
      "envFile": "${workspaceFolder}/.env.dev"
    },
    {
      "name": "Flutter Web (UAT)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=uat"],
      "envFile": "${workspaceFolder}/.env.uat"
    },
    {
      "name": "Flutter Web (Prod)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=prod"],
      "envFile": "${workspaceFolder}/.env.prod"
    }
  ]
}

Заключение

✅ Локальная разработка → Использует файлы .env
✅ Развёртывание в продакшн → Использует dart-define
✅ Настройки VS Code → Легко переключаться между средами

Такой подход обеспечивает чистое, масштабируемое и готовое к продакшн решение для управления переменными окружения в Flutter Web. 🚀

💬 Если кто-то знает способ управления одной средой для локальной разработки и развёртывания, сообщите в комментариях!