第一个 Flutter 应用

前置条件：已安装 Flutter SDK，并通过 flutter doctor 检查好开发环境。 本篇我们将从零创建一个 Flutter 项目，把它跑起来，并读懂默认模板的代码。

学完本文你将掌握：

1. 用 Flutter CLI 创建项目
2. 在模拟器 / 浏览器 / 桌面端运行应用
3. 使用热重载快速调试
4. 理解 lib/main.dart 的基本结构

一、使用 Flutter CLI 创建项目

Flutter CLI 是 Flutter 自带的命令行工具，项目的创建、运行、构建、测试都通过它完成。

1. 创建新项目

打开终端，进入你存放代码的目录，执行：

flutter create my_first_app

my_first_app 是项目名，Flutter 会自动生成同名文件夹及全部初始文件。

项目命名规则：

• 只能使用小写字母、数字和下划线
• 必须以字母或下划线开头
• 不能包含空格、中划线和特殊字符

2. 常用命令参数

flutter create 支持不少参数，常用的有：

例如，只面向 iOS 和 Android 创建项目：

flutter create my_first_app --org com.mycompany --platforms ios,android

3. 创建过程的输出

执行后终端会列出新生成的文件，并自动拉取依赖：

Creating project "my_first_app"...
Resolving dependencies in `my_first_app`... 
Got dependencies in 8.3s.
Wrote 129 files.

All files written to:
  /Users/you/code/my_first_app

You can find general documentation for Flutter at: https://docs.flutter.dev/

看到 Got dependencies 就表示依赖下载完成，项目可以运行了。

二、运行 Flutter 应用

1. 启动应用

进入项目目录，执行 flutter run：

cd my_first_app
flutter run

如果当前只有一个可用设备，Flutter 会直接把应用安装并启动到该设备上；有多个设备时会提示你选择。

首次编译需要一些时间（Gradle / Xcode 构建），之后再次运行会快很多。

2. 指定运行设备

使用 -d 参数可以直接指定目标设备：

3. 查看所有可用设备

不确定设备 ID 时，先执行：

flutter devices

输出示例：

3 connected devices:

macOS (desktop)  • macos  • darwin-arm64   • macOS 15.0
Chrome (web)     • chrome • web-javascript • Google Chrome 130
iPhone 16 Pro    • xxxxxx • ios            • com.apple.CoreSimulator.SimRuntime.iOS-18-0

也可以用模拟器 ID 精确指定：

flutter run -d xxxxxx

4. 运行时的终端快捷键

flutter run 启动后，终端会进入热重载控制台，常用按键：

三、热重载（Hot Reload）

热重载是 Flutter 最具代表性的开发特性：

1. 在编辑器里修改 Dart 代码并保存；
2. 回到运行中的终端按 r（在 VS Code / Android Studio 中保存文件会自动触发）；
3. 约 1 秒内，模拟器或真机上的界面就会刷新成最新代码。

热重载的特点：

• 保留应用状态：计数器数值、输入框内容、页面栈都不会丢失；
• 原理是把改动后的代码注入正在运行的 Dart VM，再重新构建 Widget 树；
• 少数改动（如 main() 入口、应用初始化逻辑、枚举改为类等）热重载无法生效，此时按大写 R 做热重启，或完全重新运行。

四、入口文件 main.dart 解析

每个 Flutter 项目的入口都是 lib/main.dart。默认模板是一个点击按钮计数的示例，下面给出带详细注释的版本：

// lib/main.dart

// 1. 导入 Material Design 组件库
import 'package:flutter/material.dart';

// 2. main() 是 Dart 程序的入口函数
void main() {
  // runApp() 接收一个 Widget 作为应用的根节点
  runApp(const MyApp());
}

// 3. 根组件：无状态组件
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // MaterialApp 提供 Material 风格的页面导航、主题等配置
    return MaterialApp(
      title: 'Flutter Demo',                 // 应用标题（任务管理器中显示）
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,                  // 启用 Material 3
      ),
      home: const MyHomePage(title: 'Flutter 示例首页'),
    );
  }
}

// 4. 首页：有状态组件
class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title; // 不可变的配置数据

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

// 5. 首页的状态类：持有可变状态并负责构建 UI
class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0; // 计数器状态

  void _incrementCounter() {
    // setState 通知框架：状态变了，请重新执行 build()
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    // Scaffold 提供页面的基本骨架（应用栏、主体、悬浮按钮等）
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center, // 垂直方向居中
          children: [
            const Text('按钮被点击的次数：'),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: '增加',
        child: const Icon(Icons.add),
      ),
    );
  }
}

代码结构对照表

试着改一改

建议立刻体验热重载，例如：

• 把 '按钮被点击的次数：' 改成 '你已经点了'，保存后按 r；
• 把 seedColor: Colors.deepPurple 改成 Colors.blue，观察主题色变化；
• 把 Icon(Icons.add) 改成 Icon(Icons.plus_one)。

这些改动都会在不丢失计数值的情况下即时生效。

五、小结

• flutter create 项目名 创建项目，--org / --platforms / --empty 是最常用的三个参数；
• flutter devices 查看设备，flutter run -d 设备ID 指定设备运行；
• r 热重载保留状态，R 热重启重置状态；
• 一切 UI 皆 Widget：StatelessWidget 管静态界面，StatefulWidget 管会变化的界面；
• 改状态要包在 setState() 里，界面才会刷新。

上一篇：Flutter 安装与环境配置 下一篇：Flutter 项目结构说明