Skip to content

项目结构 ​

了解 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 作为根组件,挂载到屏幕
MaterialAppMaterial 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运行测试

下一步 ​

基于 Flutter 官方文档整理