环境搭建与第一个应用

Flutter 的环境问题几乎是新手遇到的第一道坎，而且绝大多数报错都能用一条 flutter doctor 定位。本章按"装 SDK → 装 IDE → 逐项过 doctor → 建项目 → 跑起来"的顺序走一遍，并解释 main.dart 的结构、热重载与热重启的区别，以及 pubspec.yaml 与各平台目录各自负责什么。

第一步：安装 Flutter SDK

下载稳定版（stable）压缩包或使用官方安装包，解压到不含中文与空格的路径，然后把 flutter/bin 加入 PATH。

# Windows 用 PowerShell 验证；macOS/Linux 用 which flutter
flutter --version
flutter doctor

首次执行 flutter doctor 会联网下载 Dart SDK 与引擎产物，耗时较长属于正常现象。

第二步：装 IDE 与插件

IDE	必装插件	说明
Android Studio	Flutter、Dart	自带 Android SDK 与模拟器管理，调试体验最完整
VS Code	Flutter、Dart	轻量，配合 DevTools 足够日常开发
IntelliJ IDEA	Flutter、Dart	已习惯 Java 系工具链的团队可用

命令面板里的 Flutter: Select Device 与 Flutter: Hot Reload 是日常最高频的两个操作。

第三步：逐项排查 flutter doctor

flutter doctor 的每一项都有明确的修复路径，按下面的表对症处理即可：

报错项	常见原因	处理方式
Android toolchain 缺失	未装 Android SDK 或许可未接受	安装 Android Studio 并执行 flutter doctor --android-licenses
Android license status unknown	许可协议未接受	同上，逐条输入 y 确认
Xcode 未配置	未装 Xcode 或未装命令行工具	macOS 上执行 xcode-select --install 并同意协议
CocoaPods not installed	iOS 依赖管理器缺失	sudo gem install cocoapods
Chrome 未找到	未装 Chrome，无法跑 Web	安装 Chrome，或在支持桌面端时用 -d windows
卡在 "Downloading"	网络受限	配置国内镜像环境变量后重试

# 国内网络常见做法：为 pub 与引擎产物配置镜像
set PUB_HOSTED_URL=https://pub.flutter-io.cn
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
flutter doctor -v

第四步：创建并运行第一个项目

flutter create my_app
cd my_app
flutter pub get
flutter run -d chrome       # 运行到浏览器
flutter run -d windows      # 运行到 Windows 桌面
flutter run -d android      # 运行到 Android 设备或模拟器
# 出包：flutter build apk --release / flutter build appbundle / flutter build web --release

flutter create 会生成一套包含全平台目录的工程；如果只做某个端，可以用 --platforms=android,ios 只生成需要的平台目录。

main.dart 的结构

lib/main.dart 是应用入口，结构只有三层：入口函数、根 Widget、页面 Widget。

import 'package:flutter/material.dart';

void main() {
  // 入口：绑定引擎后挂载根 Widget
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // MaterialApp 提供主题、路由与本地化等全局能力
    return MaterialApp(
      title: '第一个应用',
      theme: ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo)),
      home: const HomePage(),
    );
  }
}

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

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  int _count = 0; // 状态放在 State 里，修改后界面自动刷新

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('计数器')),
      body: Center(child: Text('点击了 $_count 次')),
      floatingActionButton: FloatingActionButton(
        onPressed: () => setState(() => _count++),
        child: const Icon(Icons.add),
      ),
    );
  }
}

热重载 vs 热重启

对比项	热重载 Hot Reload（r）	热重启 Hot Restart（R）
作用范围	重建 Widget 树，保留 State	重新执行 main()，State 清空
生效速度	通常 1 秒内	数秒
何时用	改 UI、改样式、改 build 逻辑	改 main()、改全局变量、状态被写坏

在终端按 r 触发热重载、R 触发热重启；VS Code 里保存文件即可自动热重载。

项目目录结构

路径	作用
lib/	你的 Dart 代码，只有这里的文件参与编译
android/	Android 工程，改包名、权限、签名时进来
ios/	iOS 工程，改 Info.plist、Podfile 时进来
web/	Web 入口与 index.html
test/	单元测试与 Widget 测试
pubspec.yaml	依赖、资源、字体、SDK 版本约束
build/	编译产物，不要提交到版本库

小结：环境问题先用 flutter doctor -v 定位再动手修，建好工程后用 flutter run -d chrome 快速验证；lib/ 放业务代码、pubspec.yaml 管依赖与资源，日常开发用热重载、状态写坏时用热重启。