Flutter 实践：第一个应用与界面状态

前置：Dart 基础。先理解类型、函数、命名参数、对象与回调，再进入界面开发；这里专讲 Flutter 项目和界面状态。Flutter SDK 自带 Dart，不需要为同一个工程混用另一套 Dart SDK。

1. 安装并确认工具链

按Flutter 官方安装说明选择操作系统和目标平台。下载、解压 SDK 后，将 Flutter SDK 的 bin 目录加入 PATH，重新打开终端。

macOS/Linux 的路径写法示例（替换为实际目录）：

export PATH="$HOME/development/flutter/bin:$PATH"

Windows 在环境变量 Path 中加入实际的 flutter\bin 目录，不使用上面的 Shell 语句。不要把原笔记中的用户名和本机绝对路径照搬到自己的配置。

flutter --version
dart --version
flutter doctor -v

前两条确认命令来自预期 SDK，doctor 检查开发目标需要的依赖。Android 需要 Android SDK 和相应工具；iOS 开发需要 macOS 与 Xcode。只修复自己目标平台对应的问题，不要求为入门项目安装所有平台工具。

2. 创建并启动 Flutter 工程

flutter create study_app
cd study_app
flutter pub get
flutter devices

选择 flutter devices 实际列出的设备；启动模拟器或连接真机后，再用以下命令运行，替换设备 ID：

flutter run -d <device-id>

先运行新建项目自带的示例，再修改 lib/main.dart。pubspec.yaml 管理项目配置和依赖，lib/ 存放 Dart 源码，test/ 存放测试。Android Studio 或 VS Code 是编辑入口；旧版 IDE 菜单路径不属于项目必需的配置步骤。

3. 理解界面与状态

先认识框架示例的额外语法：extends 继承框架类型，@override 表示重写其方法，State<StudyPage> 指明这份状态对应的界面类型。super.key 把可选的控件标识交给父类构造函数；const 构造使满足条件的控件可以作为常量创建。再把 lib/main.dart 替换为下面的最小应用：

import 'package:flutter/material.dart';

void main() => runApp(const MaterialApp(home: StudyPage()));

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

  @override
  State<StudyPage> createState() => _StudyPageState();
}

class _StudyPageState extends State<StudyPage> {
  int completed = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('学习记录')),
      body: Center(child: Text('已完成 $completed 次练习')),
      floatingActionButton: FloatingActionButton(
        onPressed: () => setState(() => completed += 1),
        child: const Icon(Icons.add),
      ),
    );
  }
}

Widget 描述界面结构；State 保存会变化的数据；事件处理中的 setState 通知框架根据新状态更新界面。练习添加一个清零按钮，再说明数据应放在 State 而不是 build 的局部变量中的原因。

4. 检查代码并定位故障

dart format lib
flutter analyze

修改了默认界面后，也要同步调整 test/ 中引用旧界面的测试，再执行 flutter test。格式化成功不代表设备构建成功；设备启动、分析检查和测试分别验证不同的问题。

现象	先检查
找不到 flutter 或 dart	PATH、终端是否重新打开、命令来自哪套 SDK
没有设备	设备连接、模拟器状态、flutter doctor -v 的对应平台问题
拉依赖长时间不结束	错误日志、网络和项目使用的包源，避免无依据地切换镜像
提示另一个命令持有启动锁	是否还有下载、构建或 IDE 后台任务；不要直接递归删除 SDK 缓存
构建失败	第一条实际错误与当前 SDK/工程配置，不沿用旧文中的固定 Build Tools 版本

完成本例后，再学习 Flutter 布局、状态共享、导航与测试；Dart 语法遇到疑问时返回语言基础对应章节，不必重复安装工具链。

参考：Dart SDK 与 Flutter 的关系、Flutter PATH 配置、安装问题排查。