项目结构

了解 Flutter 项目的目录结构，是开发的第一步。本文按先整体后细节的顺序，带你快速搞清楚一个 Flutter 项目里有什么、什么重要、什么可以先忽略。

创建项目

bash

# 创建新项目
flutter create my_app

# 指定组织名和平台
flutter create --org com.example --platforms android,ios,web my_app

目录总览

创建完成后，项目结构如下：

my_app/
├── lib/                    # ⭐ Dart 源码（你 90% 的时间都在这里）
│   └── main.dart           #   应用入口
├── pubspec.yaml            # ⭐ 项目配置（依赖、资源、元数据）
├── analysis_options.yaml   #   代码规范配置
├── test/                   #   测试文件
├── android/                #   Android 原生工程（很少直接改）
├── ios/                    #   iOS 原生工程（很少直接改）
├── web/                    #   Web 平台文件
├── ohos/                   #   鸿蒙平台文件（需开启鸿蒙支持）
└── README.md

初学者关注点

现在就搞懂：lib/、pubspec.yaml、main.dart
用到再看：android/、ios/ 等原生目录（需要写插件或改原生配置时才动）
暂时忽略：test/（先学会写功能，再学测试）

三个核心文件

1. pubspec.yaml — 项目配置

这是 Flutter 项目的"身份证"，定义了项目是谁、依赖什么、包含哪些资源。

yaml

name: my_app               # 包名（唯一标识）
description: My Flutter App # 描述
version: 1.0.0+1           # 版本号+构建号（1.0.0 是版本，1 是构建号）

environment:
  sdk: ^3.6.0              # Dart SDK 版本约束

dependencies:              # 运行时依赖（打包进 APP 的包）
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8  # iOS 风格图标
  http: ^1.2.0             # 第三方包示例

dev_dependencies:          # 开发依赖（只在开发时用，不打包进 APP）
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:                   # Flutter 专属配置
  uses-material-design: true  # 使用 Material 图标
  assets:                     # 声明静态资源（必须声明才能使用）
    - images/
    - assets/data.json
  fonts:                    # 自定义字体
    - family: MyFont
      fonts:
        - asset: fonts/MyFont-Regular.ttf
        - asset: fonts/MyFont-Bold.ttf
          weight: 700

常用操作：

操作	命令
安装/更新依赖	`flutter pub get`
添加第三方包	`flutter pub add http`
移除第三方包	`flutter pub remove http`
查看过期依赖	`flutter pub outdated`
升级依赖	`flutter pub upgrade`

注意

每次修改 pubspec.yaml 后，必须运行 flutter pub get 安装依赖，否则 IDE 会报错。

2. main.dart — 应用入口

Flutter 应用的启动文件，main() 函数是程序执行的起点：

dart

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());   // runApp 把根组件挂载到屏幕上
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(           // Material 风格应用外壳
      title: 'My App',
      home: Scaffold(             // 页面骨架（提供 AppBar、Body 等）
        appBar: AppBar(title: const Text('首页')),
        body: const Center(child: Text('Hello Flutter!')),
      ),
    );
  }
}

关键理解：

概念	说明
`main()`	程序入口，调用 `runApp()` 启动应用
`runApp()`	接收一个 Widget 作为根组件，挂载到屏幕
`MaterialApp`	Material Design 风格的应用外壳，配置主题、路由等
`Scaffold`	页面骨架，提供 AppBar、Body、FloatingActionButton 等区域

随着项目变大，main.dart 应该只保留启动逻辑，页面代码拆分到 lib/pages/ 下。详见项目架构。

3. analysis_options.yaml — 代码规范

Dart 的静态代码分析配置，相当于"拼写检查器"——在你写代码时实时提示问题。

yaml

# 引入 Flutter 官方推荐规则集
include: package:flutter_lints/flutter.yaml

# 自定义规则
linter:
  rules:
    prefer_const_constructors: true   # 优先用 const 构造函数
    prefer_single_quotes: true        # 优先用单引号
    avoid_print: true                 # 避免用 print

# 排除不需要分析的文件
analyzer:
  exclude:
    - "**/*.g.dart"        # 代码生成的文件
    - "**/*.freezed.dart"

# 第三方 lint 插件（如使用 Riverpod 时添加）
# plugins:
#   riverpod_lint: 3.1.3

验证是否生效：

bash

flutter analyze    # 扫描整个项目，报告所有问题

IDE 会自动读取此文件，在编写代码时实时标黄/标红提示问题。修改配置后如果未生效，运行 flutter pub get 或重启 IDE。

lib/ 目录 — 你的主战场

lib/ 是你编写 Dart 代码的地方。项目初期只有一个 main.dart，随着功能增长需要合理组织：

lib/
├── main.dart                # 入口：只做初始化和启动
├── app.dart                 # 根 Widget（MaterialApp）
├── pages/                   # 页面
│   ├── home_page.dart
│   └── login_page.dart
├── widgets/                 # 可复用组件
│   └── loading.dart
├── models/                  # 数据模型
│   └── user.dart
├── services/                # 服务（网络请求、本地存储等）
│   └── api_service.dart
└── utils/                   # 工具函数
    └── validators.dart

组织原则

入口简洁：main.dart 只负责启动，不超过 20 行
按功能分层：页面、组件、模型、服务各归其位
适度拆分：至少 2-3 处复用时才提取公共组件，避免过度封装

更详细的目录组织方式和大型项目架构，请参考项目架构。

原生平台目录

目录	作用	何时需要改
`android/`	Android 原生工程	修改包名、权限、SDK 版本等
`ios/`	iOS 原生工程	修改 Bundle ID、权限描述等
`web/`	Web 平台文件	修改 index.html、添加 JS 等
`ohos/`	鸿蒙平台文件	修改鸿蒙相关配置

初学者不必焦虑

这些目录的内容由 Flutter 自动生成和管理，绝大多数情况下不需要手动修改。当你需要配置权限（如网络、相机）或修改应用名/图标时才会涉及，相关操作会在应用发布章节详细介绍。

常用命令速查

日常开发

命令	说明
`flutter run`	运行应用（debug 模式）
`flutter run -d chrome`	在 Chrome 中运行 Web 版
`flutter run -d ohos`	在鸿蒙设备运行
`flutter devices`	查看可用设备
`r`	热重载（运行中按，秒级生效）
`R`	热重启（运行中按，完全重启）
`q`	退出运行

依赖管理

命令	说明
`flutter pub get`	安装依赖
`flutter pub add 包名`	添加依赖包
`flutter pub remove 包名`	移除依赖包
`flutter pub outdated`	查看过期依赖
`flutter pub upgrade`	升级依赖

构建与检查

命令	说明
`flutter build apk`	构建 Android APK
`flutter build ios`	构建 iOS（需 macOS）
`flutter build web`	构建 Web
`flutter build ohos`	构建鸿蒙应用
`flutter clean`	清理构建产物
`flutter analyze`	静态代码分析
`flutter test`	运行测试

下一步

第一个应用 — 动手写一个计数器应用
Dart 语法速查 — 快速掌握 Dart 核心语法
Widget 基础 — 理解 Flutter 组件体系

项目结构 ​

创建项目 ​

目录总览 ​

三个核心文件 ​

1. pubspec.yaml — 项目配置 ​

2. main.dart — 应用入口 ​

3. analysis_options.yaml — 代码规范 ​

lib/ 目录 — 你的主战场 ​

原生平台目录 ​

常用命令速查 ​

日常开发 ​

依赖管理 ​

构建与检查 ​

下一步 ​