Flutter 完全指南：跨平台应用开发教程（Flutter 3.x）

全面的 Flutter 指南，涵盖 Dart 基础、Widget、StatelessWidget、StatefulWidget、状态管理（Provider、Riverpod、Bloc、GetX）、Navigator 2.0、go_router、HTTP 与 Dio 集成、表单、JSON 序列化以及部署到 iOS、Android、Web 和桌面端——附真实 Dart 代码示例。

Flutter 是 Google 的跨平台 UI 框架，2017 年首次发布，2018 年 12 月达到 1.0 稳定里程碑。自 Flutter 2.0（2021 年 3 月）起，框架支持 iOS、Android 和 Web 的稳定构建。Flutter 3.0（2022 年 5 月）将稳定支持扩展到 macOS、Linux 和 Windows，成为首个开箱即用支持多平台稳定版的框架。同为 Google 出品的 Dart 语言，以强类型、空安全、async/await 和预编译为 Flutter 提供底层支持。截至 Flutter 3.x（2023–2025），阿里巴巴、宝马、eBay 和 Google Pay 等公司相继加速采用。本指南涵盖从零到生产所需的一切内容。

1. What is Flutter? Dart, Skia/Impeller, and the Cross-Platform Promise

Flutter is a UI toolkit — not just a framework. It bundles an entire rendering engine (Skia on older versions, Impeller on Flutter 3.10+), the Dart runtime, a rich widget library (Material Design and Cupertino), and platform embedders for each target OS. When you write a Flutter app, you write in Dart; the Flutter engine handles painting pixels on screen using the GPU, entirely bypassing native UI components like UIKit (iOS) or Android View. This is fundamentally different from React Native, Xamarin, or Ionic, which all rely on native components in some form.

Dart is a statically typed, garbage-collected language with a syntax familiar to Java and JavaScript developers. It supports AOT (ahead-of-time) compilation for production builds (resulting in fast native code with no JIT overhead) and JIT compilation during development (enabling hot reload). Dart 3.x added records, pattern matching, sealed classes, and class modifiers, making the language significantly more expressive.

Skia was the original 2D graphics engine, used in Chrome and Android. It works well but suffered from shader compilation jank — first-frame stutters when new shaders are compiled at runtime. Impeller (Flutter 3.10+ on iOS, 3.13+ on Android) solves this by pre-compiling all shaders at build time, delivering consistently smooth 60/120fps animations. Impeller is the future of Flutter rendering.

Platform support as of Flutter 3.x: iOS, Android, Web (CanvasKit and HTML renderers), macOS, Windows, and Linux. A single flutter pub get + flutter build targets any of these platforms.

# Install Flutter SDK (macOS example via git)
git clone https://github.com/flutter/flutter.git -b stable
export PATH="$PATH:`pwd`/flutter/bin"

# Verify installation
flutter doctor

# Create a new Flutter project
flutter create my_app
cd my_app

# Run on connected device or emulator
flutter run

# Run on Chrome (web)
flutter run -d chrome

# Build release APK for Android
flutter build apk --release

# Build release IPA for iOS
flutter build ipa

2. Flutter Basics: Widgets, BuildContext, and Hot Reload

The defining principle of Flutter is: everything is a widget. A widget is an immutable description of part of the user interface. Widgets form a tree — the widget tree. Flutter compares the current tree to the previous tree (reconciliation) and only rebuilds what changed. This is similar to React's virtual DOM model.

There are two fundamental widget types: StatelessWidget (immutable, built once, rebuilt only when its parent rebuilds with new parameters) and StatefulWidget (paired with a State object that persists across rebuilds and can call setState() to trigger a rebuild).

BuildContext is a handle to the location of a widget in the widget tree. It is used to look up inherited widgets (Theme, MediaQuery, Navigator) and to access the widget tree above the current widget. Never store a BuildContext across async gaps — it may become stale. Always check context.mounted (Flutter 3.7+) before using context after an await.

import 'package:flutter/material.dart';

// Entry point
void main() => runApp(const MyApp());

// Root widget — StatelessWidget
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const CounterPage(),
    );
  }
}

// StatefulWidget — mutable state
class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int _count = 0;

  void _increment() {
    setState(() {
      _count++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter')),
      body: Center(
        child: Text(
          'Count: $_count',
          style: Theme.of(context).textTheme.headlineMedium,
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _increment,
        child: const Icon(Icons.add),
      ),
    );
  }
}

Hot reload (press r in the terminal or save in VS Code/Android Studio) injects updated source code into the running Dart VM and triggers a widget rebuild — all within under a second, preserving app state. Hot restart (R) restarts the app from scratch, resetting state. Use hot reload for UI tweaks; hot restart for logic changes that require a fresh state.

3. Layout Widgets: Column, Row, Stack, Expanded, Container, and SizedBox

Flutter's layout system is built entirely from widgets. There are no separate CSS layout rules — positioning, sizing, and alignment are all expressed as widget properties. Understanding the core layout widgets is essential for building any non-trivial UI.

• Column — arranges children vertically. Use mainAxisAlignment (vertical) and crossAxisAlignment (horizontal) to control child placement.
• Row — arranges children horizontally. Same axis properties as Column but mirrored.
• Stack — overlays children on top of each other (like CSS position: absolute). Use Positioned children to control exact placement.
• Expanded — fills available space inside a Row or Column, like CSS flex: 1. Use flex property for proportional sizing.
• Flexible — like Expanded but allows the child to be smaller than the available space.
• Container — a convenience widget combining decoration (color, border, border-radius, shadow), padding, margin, and size constraints. Do not nest Containers unnecessarily — prefer specific widgets for each concern.
• SizedBox — forces a specific width and height. Also useful as SizedBox.shrink() (zero-size invisible widget) and SizedBox.expand() (fill parent).
• Padding — adds padding around a single child. Prefer over Container when you only need padding.
• Wrap — like Row/Column but wraps to the next line when children overflow, similar to CSS flexbox with flex-wrap.
• ListView / GridView — scrollable lists and grids. Use ListView.builder for long lists (lazy rendering).

// Typical layout combining Row, Column, Expanded
Widget build(BuildContext context) {
  return Scaffold(
    body: Padding(
      padding: const EdgeInsets.all(16.0),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          // Header row
          Row(
            mainAxisAlignment: MainAxisAlignment.spaceBetween,
            children: [
              Text('Dashboard', style: Theme.of(context).textTheme.headlineSmall),
              IconButton(icon: const Icon(Icons.notifications), onPressed: () {}),
            ],
          ),
          const SizedBox(height: 16),

          // Two equal-width cards using Expanded
          Row(
            children: [
              Expanded(child: _StatCard(title: 'Users', value: '1,204')),
              const SizedBox(width: 12),
              Expanded(child: _StatCard(title: 'Revenue', value: '$8,432')),
            ],
          ),
          const SizedBox(height: 16),

          // Fills remaining vertical space
          Expanded(
            child: ListView.builder(
              itemCount: 20,
              itemBuilder: (context, index) => ListTile(
                leading: CircleAvatar(child: Text('${index + 1}')),
                title: Text('Item ${index + 1}'),
                subtitle: const Text('Subtitle text'),
                trailing: const Icon(Icons.chevron_right),
              ),
            ),
          ),
        ],
      ),
    ),
  );
}

// Stack example: badge over icon
Stack(
  children: [
    const Icon(Icons.shopping_cart, size: 32),
    Positioned(
      top: 0,
      right: 0,
      child: Container(
        padding: const EdgeInsets.all(4),
        decoration: const BoxDecoration(
          color: Colors.red,
          shape: BoxShape.circle,
        ),
        child: const Text('3', style: TextStyle(color: Colors.white, fontSize: 10)),
      ),
    ),
  ],
)

4. State Management: setState, Provider, Riverpod, Bloc/Cubit, GetX

State management is the most debated topic in Flutter. The right choice depends on your app's complexity, team size, and testing requirements. Here is a practical breakdown:

setState — Local, Simple State

setState() is the built-in mechanism for updating state inside a StatefulWidget. It schedules a rebuild of the widget subtree. Use it for purely local UI state (toggle, counter, form field values) that does not need to be shared across widgets. Avoid setState for business logic — keep it in the widget's State class minimal.

Provider — InheritedWidget Made Simple

Provider (by Remi Rousselet) is a wrapper around Flutter's InheritedWidget that makes sharing state down the widget tree ergonomic. Combine ChangeNotifier + ChangeNotifierProvider + Consumer or context.watch() for reactive UI updates. It is stable, well-documented, and sufficient for many production apps.

// pubspec.yaml
// dependencies:
//   provider: ^6.1.0

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

// 1. Define a ChangeNotifier model
class CartModel extends ChangeNotifier {
  final List<String> _items = [];

  List<String> get items => List.unmodifiable(_items);
  int get count => _items.length;

  void addItem(String item) {
    _items.add(item);
    notifyListeners(); // Triggers Consumer rebuilds
  }

  void removeItem(String item) {
    _items.remove(item);
    notifyListeners();
  }
}

// 2. Provide at the app level
void main() => runApp(
  ChangeNotifierProvider(
    create: (_) => CartModel(),
    child: const MyApp(),
  ),
);

// 3. Consume in any descendant widget
class CartIcon extends StatelessWidget {
  const CartIcon({super.key});

  @override
  Widget build(BuildContext context) {
    // context.watch triggers rebuild on every change
    final cart = context.watch<CartModel>();
    return Badge(
      label: Text('${cart.count}'),
      child: const Icon(Icons.shopping_cart),
    );
  }
}

class ProductTile extends StatelessWidget {
  final String product;
  const ProductTile({required this.product, super.key});

  @override
  Widget build(BuildContext context) {
    return ListTile(
      title: Text(product),
      trailing: ElevatedButton(
        // context.read — one-time action, no rebuild
        onPressed: () => context.read<CartModel>().addItem(product),
        child: const Text('Add to Cart'),
      ),
    );
  }
}

Riverpod — Compile-Time Safe, Context-Free State

Riverpod 2.x with code generation (riverpod_annotation) is the recommended approach for new projects. Providers are global constants — no BuildContext required to read them, no possibility of accessing the wrong provider, and testable without a Flutter widget tree.

// pubspec.yaml
// dependencies:
//   flutter_riverpod: ^2.5.0
//   riverpod_annotation: ^2.3.0
// dev_dependencies:
//   riverpod_generator: ^2.4.0
//   build_runner: ^2.4.0

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'counter.g.dart'; // generated file

// Simple state provider (code-gen syntax)
@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0; // initial state

  void increment() => state++;
  void decrement() => state--;
}

// Async provider — fetches data from API
@riverpod
Future<List<String>> fetchUsers(FetchUsersRef ref) async {
  final response = await http.get(Uri.parse('https://api.example.com/users'));
  // ... parse and return
  return [];
}

// Widget: use ConsumerWidget instead of StatelessWidget
class CounterWidget extends ConsumerWidget {
  const CounterWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);

    return Column(
      children: [
        Text('Count: $count'),
        ElevatedButton(
          onPressed: () => ref.read(counterProvider.notifier).increment(),
          child: const Text('Increment'),
        ),
      ],
    );
  }
}

// Async provider with loading/error states
class UserList extends ConsumerWidget {
  const UserList({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final usersAsync = ref.watch(fetchUsersProvider);

    return usersAsync.when(
      data: (users) => ListView(children: users.map(Text.new).toList()),
      loading: () => const CircularProgressIndicator(),
      error: (e, st) => Text('Error: $e'),
    );
  }
}

Bloc / Cubit — Event-Driven, Highly Testable

Bloc (Business Logic Component) enforces strict separation: UI dispatches Events, Bloc processes them and emits States. Cubit is a simplified Bloc that uses method calls instead of events (no event classes needed). Bloc is ideal for large teams and complex flows where auditability and testability are critical. The flutter_bloc package provides BlocBuilder, BlocListener, and BlocConsumer for clean widget integration.

// Cubit — simpler Bloc without explicit events
import 'package:flutter_bloc/flutter_bloc.dart';

// State
class CounterState {
  final int count;
  const CounterState(this.count);
}

// Cubit
class CounterCubit extends Cubit<CounterState> {
  CounterCubit() : super(const CounterState(0));

  void increment() => emit(CounterState(state.count + 1));
  void decrement() => emit(CounterState(state.count - 1));
  void reset() => emit(const CounterState(0));
}

// Widget
class CounterView extends StatelessWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => CounterCubit(),
      child: BlocBuilder<CounterCubit, CounterState>(
        builder: (context, state) {
          return Column(
            children: [
              Text('Count: ${state.count}'),
              Row(
                children: [
                  IconButton(
                    onPressed: () => context.read<CounterCubit>().decrement(),
                    icon: const Icon(Icons.remove),
                  ),
                  IconButton(
                    onPressed: () => context.read<CounterCubit>().increment(),
                    icon: const Icon(Icons.add),
                  ),
                ],
              ),
            ],
          );
        },
      ),
    );
  }
}

5. Navigation: Navigator 2.0, go_router, and Route Guards

Flutter's original Navigator 1.0 (imperative: Navigator.push / Navigator.pop) is simple but does not handle deep links or web URL synchronization. Navigator 2.0 introduced a declarative API, but it is complex. go_router (the officially recommended package from the Flutter team) wraps Navigator 2.0 with a clean, URL-based declarative routing API.

// pubspec.yaml: go_router: ^14.0.0

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

// 1. Define the router
final _router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/products',
      builder: (context, state) => const ProductListScreen(),
      routes: [
        // Nested route with path parameter
        GoRoute(
          path: ':id',
          builder: (context, state) {
            final id = state.pathParameters['id']!;
            return ProductDetailScreen(productId: id);
          },
        ),
      ],
    ),
    GoRoute(
      path: '/profile',
      // Route guard: redirect if not authenticated
      redirect: (context, state) {
        final isLoggedIn = AuthService.isLoggedIn;
        return isLoggedIn ? null : '/login';
      },
      builder: (context, state) => const ProfileScreen(),
    ),
    GoRoute(
      path: '/login',
      builder: (context, state) => const LoginScreen(),
    ),
  ],
  // Global error page
  errorBuilder: (context, state) => const NotFoundScreen(),
);

// 2. Pass to MaterialApp
void main() => runApp(MaterialApp.router(routerConfig: _router));

// 3. Navigate from anywhere
// Push
context.push('/products/42');

// Replace current route (no back button)
context.go('/login');

// Go with query params
context.go('/products?sort=price');

// Named route
context.goNamed('profile');

// Access path params and query params in the builder:
final id = state.pathParameters['id'];
final sort = state.uri.queryParameters['sort'];

For typed routes (compile-time safe navigation), use the go_router_builder package which generates type-safe route classes from annotations. This eliminates typos in route paths and ensures all required parameters are provided at compile time.

6. Flutter vs React Native vs Ionic vs Kotlin Multiplatform

Choosing a cross-platform framework is a significant architectural decision. Here is an honest comparison across the dimensions that matter most for production apps.

7. HTTP and API Integration: Dio, http Package, and JSON Serialization

Flutter apps interact with REST APIs using either the built-in http package (simpler, fewer features) or Dio (interceptors, cancellation tokens, multipart uploads, retry logic). For JSON serialization, use json_serializable + build_runner (code generation) or freezed (immutable data classes with union types).

// pubspec.yaml
// dependencies:
//   dio: ^5.4.0
//   json_annotation: ^4.9.0
// dev_dependencies:
//   json_serializable: ^6.8.0
//   build_runner: ^2.4.8

import 'package:dio/dio.dart';

// ── 1. JSON Model with code generation ──
import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart'; // run: flutter pub run build_runner build

@JsonSerializable()
class User {
  final int id;
  final String name;
  final String email;
  @JsonKey(name: 'created_at')
  final DateTime createdAt;

  const User({
    required this.id,
    required this.name,
    required this.email,
    required this.createdAt,
  });

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

// ── 2. API Service using Dio ──
class ApiService {
  late final Dio _dio;
  static const _baseUrl = 'https://api.example.com';

  ApiService() {
    _dio = Dio(BaseOptions(
      baseUrl: _baseUrl,
      connectTimeout: const Duration(seconds: 10),
      receiveTimeout: const Duration(seconds: 15),
      headers: {'Content-Type': 'application/json'},
    ));

    // Auth interceptor
    _dio.interceptors.add(InterceptorsWrapper(
      onRequest: (options, handler) async {
        final token = await SecureStorage.getToken();
        if (token != null) {
          options.headers['Authorization'] = 'Bearer $token';
        }
        handler.next(options);
      },
      onError: (error, handler) async {
        if (error.response?.statusCode == 401) {
          // Token expired — refresh and retry
          await AuthService.refreshToken();
          handler.next(error); // or retry the request
        } else {
          handler.next(error);
        }
      },
    ));
  }

  // GET with typed response
  Future<List<User>> getUsers({int page = 1}) async {
    try {
      final response = await _dio.get(
        '/users',
        queryParameters: {'page': page, 'per_page': 20},
      );
      final data = response.data as List<dynamic>;
      return data.map((json) => User.fromJson(json as Map<String, dynamic>)).toList();
    } on DioException catch (e) {
      throw _handleDioError(e);
    }
  }

  // POST with body
  Future<User> createUser(String name, String email) async {
    try {
      final response = await _dio.post(
        '/users',
        data: {'name': name, 'email': email},
      );
      return User.fromJson(response.data as Map<String, dynamic>);
    } on DioException catch (e) {
      throw _handleDioError(e);
    }
  }

  Exception _handleDioError(DioException e) {
    if (e.type == DioExceptionType.connectionTimeout) {
      return Exception('Connection timed out. Check your internet connection.');
    }
    if (e.response?.statusCode == 404) {
      return Exception('Resource not found.');
    }
    if (e.response?.statusCode == 422) {
      final errors = e.response?.data['errors'];
      return Exception('Validation error: $errors');
    }
    return Exception('An unexpected error occurred: ${e.message}');
  }
}

For complex data models, consider freezed — it generates immutable classes with copyWith, ==, hashCode, toString, and union types in a single annotation. This is especially valuable when modelling API responses that have multiple states (success, error, loading).

8. Forms and Validation: TextFormField, GlobalKey<FormState>, Custom Validators

Flutter's Form widget wraps multiple TextFormField inputs and provides a unified validation mechanism. A GlobalKey<FormState> gives you a handle to the form's state to call validate(), save(), and reset() programmatically.

class RegistrationForm extends StatefulWidget {
  const RegistrationForm({super.key});

  @override
  State<RegistrationForm> createState() => _RegistrationFormState();
}

class _RegistrationFormState extends State<RegistrationForm> {
  final _formKey = GlobalKey<FormState>();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();
  bool _obscurePassword = true;
  bool _isSubmitting = false;

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  String? _validateEmail(String? value) {
    if (value == null || value.trim().isEmpty) return 'Email is required';
    final emailRegex = RegExp(r'^[w.-]+@[w.-]+.w{2,4}$');
    if (!emailRegex.hasMatch(value)) return 'Enter a valid email address';
    return null; // null = valid
  }

  String? _validatePassword(String? value) {
    if (value == null || value.isEmpty) return 'Password is required';
    if (value.length < 8) return 'Password must be at least 8 characters';
    if (!value.contains(RegExp(r'[A-Z]'))) return 'Must contain an uppercase letter';
    if (!value.contains(RegExp(r'[0-9]'))) return 'Must contain a number';
    return null;
  }

  Future<void> _submit() async {
    // Validate all fields — shows error messages
    if (!_formKey.currentState!.validate()) return;

    // Save the form (triggers onSaved callbacks)
    _formKey.currentState!.save();

    setState(() => _isSubmitting = true);

    try {
      await ApiService().register(
        email: _emailController.text.trim(),
        password: _passwordController.text,
      );
      if (mounted) context.go('/dashboard');
    } catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Registration failed: $e'), backgroundColor: Colors.red),
        );
      }
    } finally {
      if (mounted) setState(() => _isSubmitting = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      autovalidateMode: AutovalidateMode.onUserInteraction,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          TextFormField(
            controller: _emailController,
            keyboardType: TextInputType.emailAddress,
            textInputAction: TextInputAction.next,
            decoration: const InputDecoration(
              labelText: 'Email',
              prefixIcon: Icon(Icons.email_outlined),
              border: OutlineInputBorder(),
            ),
            validator: _validateEmail,
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: _passwordController,
            obscureText: _obscurePassword,
            textInputAction: TextInputAction.done,
            onFieldSubmitted: (_) => _submit(),
            decoration: InputDecoration(
              labelText: 'Password',
              prefixIcon: const Icon(Icons.lock_outline),
              border: const OutlineInputBorder(),
              suffixIcon: IconButton(
                icon: Icon(_obscurePassword ? Icons.visibility : Icons.visibility_off),
                onPressed: () => setState(() => _obscurePassword = !_obscurePassword),
              ),
            ),
            validator: _validatePassword,
          ),
          const SizedBox(height: 24),
          ElevatedButton(
            onPressed: _isSubmitting ? null : _submit,
            style: ElevatedButton.styleFrom(padding: const EdgeInsets.all(16)),
            child: _isSubmitting
                ? const CircularProgressIndicator(color: Colors.white)
                : const Text('Register', style: TextStyle(fontSize: 16)),
          ),
        ],
      ),
    );
  }
}

For more complex validation needs, consider the reactive_forms package, which brings an Angular-style reactive form model to Flutter, or formz for encapsulating validation logic in dedicated value objects that are easy to unit test independently.

9. Deployment: iOS App Store, Google Play, Flutter Web, and Desktop Builds

One of Flutter's strongest value propositions is unified deployment. A single Flutter codebase produces production artifacts for every supported platform. Here is a practical deployment guide for each target.

Android (Google Play)

# 1. Create a signing keystore (one-time)
keytool -genkey -v -keystore ~/release.jks \
  -alias release -keyalg RSA -keysize 2048 -validity 10000

# 2. Configure android/key.properties
# storePassword=<password>
# keyPassword=<password>
# keyAlias=release
# storeFile=<path-to-release.jks>

# 3. Reference key.properties in android/app/build.gradle

# 4. Build Android App Bundle (recommended for Play Store)
flutter build appbundle --release

# Output: build/app/outputs/bundle/release/app-release.aab

# Alternative: APK for direct distribution
flutter build apk --release --split-per-abi

iOS (App Store)

# Requires macOS + Xcode + Apple Developer Account ($99/yr)

# 1. Configure bundle ID in Xcode (ios/Runner.xcworkspace)
#    Set: Runner > Targets > Runner > Bundle Identifier

# 2. Set version in pubspec.yaml
# version: 1.0.0+1  (format: version+buildNumber)

# 3. Build IPA
flutter build ipa --release

# Output: build/ios/ipa/app-name.ipa

# 4. Upload to App Store Connect
xcrun altool --upload-app -f build/ios/ipa/*.ipa \
  -u "your@email.com" -p "@keychain:AC_PASSWORD"

# Or use: open Transporter.app and drag the .ipa in
# Or: flutter build ipa && open in Xcode → Product → Archive

Flutter Web

# CanvasKit renderer: best performance, larger initial download (~1.5 MB)
flutter build web --release --web-renderer canvaskit

# HTML renderer: smaller download, less GPU-accelerated
flutter build web --release --web-renderer html

# Auto renderer: canvaskit on desktop, html on mobile
flutter build web --release --web-renderer auto

# Output: build/web/ — a static site
# Deploy to Firebase Hosting, Vercel, Netlify, Cloudflare Pages etc.

# Deploy to Firebase
firebase deploy --only hosting

# Configure base href if not served from root
flutter build web --release --base-href /my-app/

Desktop (macOS, Windows, Linux)

# Enable desktop support (one-time per machine)
flutter config --enable-macos-desktop
flutter config --enable-windows-desktop
flutter config --enable-linux-desktop

# Build macOS .app
flutter build macos --release
# Output: build/macos/Build/Products/Release/MyApp.app

# Build Windows .exe
flutter build windows --release
# Output: build/windows/runner/Release/

# Build Linux binary
flutter build linux --release
# Output: build/linux/x64/release/bundle/

# Distribution:
# macOS: Package as .dmg, notarize with Apple, distribute via Mac App Store or direct download
# Windows: Package with MSIX (flutter_distributor package) for Microsoft Store
# Linux: Package as .deb, .rpm, .AppImage, or Flatpak via flutter_distributor

10. Performance Optimization Tips

Flutter is fast by default, but common mistakes can cause unnecessary rebuilds and janky animations. Follow these guidelines to keep your app smooth.

• Use const constructors everywhere possible — Flutter skips rebuilding const widgets entirely. Prefix every widget with const that does not depend on runtime data.
• Use ListView.builder instead of ListView — builder lazily renders only visible items. Never put a Column with 500 children in a ScrollView.
• Minimize setState scope — call setState on the smallest possible subtree. Extract sub-widgets into their own StatefulWidget to avoid rebuilding the entire screen.
• Use RepaintBoundary for isolated animations — wrapping an animated widget in RepaintBoundary prevents it from triggering repaints in the rest of the tree.
• Cache images with cached_network_image — avoids re-downloading and re-decoding images on every rebuild.
• Avoid building widgets in initState — use FutureBuilder or Consumer/ref.watch for async data instead of storing futures in state and calling setState.
• Profile with Flutter DevTools — run flutter run --profile and open DevTools to identify frame drops, excessive rebuilds, and memory leaks with the Widget Inspector, Performance tab, and Memory tab.
• Use isolates for heavy computation — compute() runs a function in a background isolate, preventing the main UI thread from blocking on CPU-intensive work like JSON parsing of large payloads.

// ── const widgets ──
// Bad: rebuilds unnecessarily
AppBar(title: Text('Home'));

// Good: Flutter caches this entirely
AppBar(title: const Text('Home'));

// ── Minimal setState scope ──
// Bad: rebuilds entire screen
class MyScreen extends StatefulWidget { ... }
class _MyScreenState extends State<MyScreen> {
  bool _liked = false;
  Widget build(context) => Column(children: [
    HeavyWidget(),  // also rebuilt!
    IconButton(onPressed: () => setState(() => _liked = !_liked), ...),
  ]);
}

// Good: extract the small changing part
class LikeButton extends StatefulWidget { ... }
class _LikeButtonState extends State<LikeButton> {
  bool _liked = false;
  Widget build(context) => IconButton(
    onPressed: () => setState(() => _liked = !_liked),
    icon: Icon(_liked ? Icons.favorite : Icons.favorite_border),
  );
}

// ── compute() for heavy work ──
import 'dart:convert';
import 'package:flutter/foundation.dart';

Future<List<User>> parseUsersInBackground(String jsonString) async {
  return compute(_parseUsers, jsonString);
}

List<User> _parseUsers(String jsonString) {
  final data = jsonDecode(jsonString) as List<dynamic>;
  return data.map((json) => User.fromJson(json as Map<String, dynamic>)).toList();
}

Frequently Asked Questions