Flutter项目结构全解析：目录规范、配置与工程化

接手一个别人做了一半的 Flutter 项目，最难受的往往不是业务代码写得多乱，而是你打开目录一看，根本分不清哪些文件是脚手架自动生成的、哪些是人写的、哪些改了会出事。我见过把整个build目录提交进版本库的，也见过把三个环境的密钥硬编码在main.dart里的，更常见的是lib下面平铺着四十多个文件，谁都不敢动。所以我一直觉得，搞清楚一个完整的 Flutter 项目到底由哪些部分构成，是所有后续工作的地基——你得先知道这个工程的"骨架"长什么样，才谈得上往上面挂业务、做工程化、配 CI。这篇内容面向的读者范围比较宽：刚flutter create完不知道从哪下手的新人，能从目录层级和配置文件读起；带团队、要给多人协作定规范的负责人，可以直接参考中间几节的目录划分与环境配置思路；做工程化、搭流水线的同学，重点看测试与构建那部分。全文围绕 Flutter 项目结构展开，讲清楚每一层的职责、为什么这么分、以及我实际踩过的坑。

1. 先搞清楚一个 Flutter 工程到底由哪些"零件"拼成

1.1 脚手架跑完之后，目录里那些文件夹各自是什么角色

敲下flutter create之后，屏幕上会打印一堆Creating ...的日志，最后给你一棵树。很多人扫一眼就关掉了，其实这棵树的每一层都有明确归属，分成三类就好理解了：Dart 侧代码、平台侧壳工程、工程配置文件。

my_app/ ├── android/ # Android 平台壳工程 ├── ios/ # iOS 平台壳工程 ├── web/ # Web 平台壳工程 ├── linux/ macos/ windows/ # 桌面三件套 ├── lib/ # Dart 业务代码，你 90% 的时间在这里 │ └── main.dart ├── test/ # 测试代码 ├── assets/ # 图片、字体、JSON 等静态资源（需自建） ├── pubspec.yaml # 依赖与资源配置，等价于 package.json ├── pubspec.lock # 依赖锁定文件 ├── analysis_options.yaml # 静态检查规则 ├── .metadata # Flutter 工具链记录，别手动改 ├── .gitignore └── README.md

lib是核心，这一点没什么争议。但我想强调一下android/、ios/这些目录的性质：它们不是"Flutter 的一部分"，而是原生工程，里面是真正的 Gradle 脚本和 Xcode 工程文件。Flutter 相当于往这些原生工程里塞了一个渲染引擎和一层 Dart 运行时。理解这一点很关键——你要改应用图标、改包名、改权限声明、调签名配置、加原生依赖，全部得进这些目录动手，Dart 层是碰不到这些的。

我在一个模拟的电商类项目里吃过亏：需求是加一个扫码功能，我以为改 Dart 侧就行，结果发现相机权限的描述必须写到 iOS 的Info.plist和 Android 的AndroidManifest.xml里，否则调用时直接静默失败，日志里也不报错，排查了半天。这类"跨层"的坑，本质上是没分清 Dart 侧和平台侧的边界。

.metadata这个文件经常被误删。它记录了当前工程是用哪个渠道、哪个版本的工具创建和迁移过来的，删掉之后工具链就无法判断要不要执行某些自动迁移，可能在下次升级时把工程改成奇怪的状态。我的建议是：永远不要手动编辑它，也永远不要从版本库里删掉它。

pubspec.lock的争议最大。应用型项目（要以 App 形式发布）必须提交它，因为它锁住了每个依赖的实际解析版本，保证 A 同学和 B 同学拿到的是完全一致的三方代码；而如果你做的是一个给别人用的库，那就不该提交，否则会把你的解析结果强加给使用者。这条区分我见过太多团队搞混。

1.2 版本库取舍：哪些该进 git，哪些必须拦住

.gitignore的默认内容已经覆盖了大部分，但默认规则是"代码洁癖版"，实际团队协作里通常要加几条。核心原则只有一句话：只提交人能写、工具能重新生成的东西；构建产物和本机状态一律不提交。

最后一行是重灾区。local.properties里写的是你电脑上 SDK 的绝对路径，提交上去之后别人拉下来编译，会报一堆"找不到 SDK"的错，而且报错信息完全不指向这个文件，新手极难定位。我在一个多人协作的项目里见过这个文件被提交了三次，每次都有人被坑。

至于*.g.dart要不要提交，实践中有两派。我的观点是：如果 CI 里第一步就跑代码生成，那就不提交，保持仓库干净、避免合并冲突；如果团队里有人习惯直接拉代码就跑、不做生成步骤，那提交更省事。关键是全队统一，最怕一半人提交一半人不提交，那冲突就没完没了。

提示：加完.gitignore之后，已经被跟踪的文件不会自动失效，需要用git rm --cached <路径>把它从索引里摘出来，否则改了规则也没用。

2. pubspec.yaml：整个工程真正的中枢配置

2.1 依赖分区与版本约束，怎么写才不至于半年后编译不过

pubspec.yaml是我认为最应该被认真对待的一个文件，它的地位相当于前端的package.json加上资源清单。一份结构清晰的配置大概长这样：

name: my_app description: 一个用于演示工程结构的示例项目 publish_to: 'none' version: 1.4.2+37 environment: sdk: '>=3.3.0 <4.0.0' flutter: '>=3.19.0' dependencies: flutter: sdk: flutter # 基础能力 dio: ^5.4.0 # 状态管理与依赖注入 flutter_riverpod: ^2.5.1 # 路由 go_router: ^13.2.0 # 本地存储 shared_preferences: ^2.2.2 dev_dependencies: flutter_test: sdk: flutter flutter_lints: ^3.0.0 build_runner: ^2.4.8 json_serializable: ^6.7.1 flutter: uses-material-design: true assets: - assets/images/ - assets/config/ fonts: - family: AppFont fonts: - asset: assets/fonts/AppFont-Regular.ttf - asset: assets/fonts/AppFont-Bold.ttf weight: 700

几个细节值得单独说。

version: 1.4.2+37里的加号后面是构建号，前面是语义化版本。这个字段不是装饰品，各平台的打包工具会读它：Android 侧构建号映射到版本号整数字段，必须递增，否则商店拒收；iOS 侧同理。我见过有人手动改版本号忘了加构建号，连续三次上传都被挡回来，还以为是签名问题。

environment里的 SDK 约束千万别写得太松。写>=2.12.0意味着允许任何 3.x 甚至未来的 4.x 来解析，一旦语言层面出现破坏性变更（比如某些语法被废弃），你的代码会在别人机器上莫名其妙报错。我的习惯是下界写当前使用的稳定版本，上界卡死在大版本前一位。flutter:这一条也一样，团队里 Flutter SDK 版本不统一是编译失败的头号原因之一，写进约束至少能在pub get阶段就暴露出来。

依赖的^前缀表示"允许升级到不破坏兼容的最大版本"，这是默认推荐。但核心依赖建议收紧，比如状态管理框架、路由框架这种会影响全项目写法的东西，升级一个大版本可能要改几百个文件。我的做法是：框架级依赖用精确版本（2.5.1，不带^），工具类依赖用^。这样日常小升级不会被挡住，大改动也不会突然砸下来。

dev_dependencies里放的是只在开发和测试阶段用的东西。有人把代码生成器、lint 规则放进dependencies，结果打进产物里白白增大体积，虽然 tree-shaking 会处理掉一部分，但没必要冒这个险。

依赖来源也不止一种，除了默认的包仓库，还能指向本地路径、git 仓库：

dependencies: # 本地路径依赖，适合多包拆分的单体仓库 common_widgets: path: packages/common_widgets # git 依赖，可以钉到某个提交 some_sdk: git: url: https://example.com/some_sdk.git ref: 3f2a1b9

ref用提交哈希而不是分支名，这是我在一次事故之后定下的规矩。之前有个私有 SDK 依赖写的是分支名，某天对方把分支推倒重写，我们整条流水线直接挂了，而且错误信息是"找不到某个符号"，看起来像自己代码的问题。

2.2 资源声明、字体与代码生成配置

flutter:这一节管的是资源。这里有个非常经典的坑：目录声明不会递归。写- assets/images/只包含这一层，子目录assets/images/icons/里的文件是拿不到的。很多人写完Image.asset报"Unable to load asset"，翻来覆去看路径没错，其实就是因为漏声明了子目录。

另一个坑是文件名大小写。macOS 和 Windows 默认文件系统不区分大小写，你写assets/Logo.png而实际文件叫logo.png，本机跑得好好的，一到 Linux 的 CI 上就崩。所以资源命名我统一要求全小写加下划线，并且在 CI 里跑一遍资源引用校验。

字体那段也有讲究。同一个 family 下多个字重，靠weight字段区分，如果不写，框架无法正确匹配粗体，导致你设置fontWeight: FontWeight.w700时页面显示的仍是常规体，看起来像"加粗失效"。中文项目尤其要注意：很多字体文件的字重命名和实际的weight值对不上，得自己打开确认。

代码生成这一块，凡是用了json_serializable、freezed、riverpod_generator之类的，pubspec.yaml里只是声明，真正的配置往往在build.yaml：

targets: $default: builders: json_serializable: options: field_rename: snake explicit_to_json: true include_if_null: false

field_rename: snake让生成的toJson/fromJson自动把驼峰字段映射成下划线，省掉每个字段写@JsonKey(name: ...)；explicit_to_json: true解决嵌套对象序列化时偶发的类型转换异常。这些选项写一次，全项目受益，比在模型类上一个一个标注舒服得多。

再提一个流程问题：build_runner的产物要不要纳入版本库，前面说过要全队统一。此外生成命令也有讲究，日常开发用一次性的dart run build_runner build --delete-conflicting-outputs，长期开发开watch模式更省心：

# 全量生成一次，带冲突清理 dart run build_runner build --delete-conflicting-outputs # 持续监听，改一个生成一个 dart run build_runner watch --delete-conflicting-outputs

--delete-conflicting-outputs这个参数几乎必须带上。不带的后果是：你改了模型字段名，生成器发现目标文件已存在，直接报"conflicting outputs"然后什么都不生成，你会以为命令跑成功了，实际拿到的是旧代码，编译报错时一脸懵。

3. lib 目录怎么组织：分层、分功能，还是混着来

3.1 三层分法的落地姿势与适用边界

lib是唯一没法靠脚手架生成的部分，而它恰恰决定了这个项目半年后还能不能维护。最常见的两种组织思路是"按技术分层"和"按业务功能切分"，我先把分层法摊开讲。

lib/ ├── main.dart ├── app.dart ├── core/ │ ├── constants/ # 常量、枚举 │ ├── theme/ # 主题、颜色、字体规范 │ ├── network/ # 网络客户端、拦截器 │ ├── error/ # 统一异常类型与处理 │ └── utils/ # 无状态工具函数 ├── data/ │ ├── models/ # 数据模型与序列化 │ ├── datasources/ # 远程与本地数据源 │ └── repositories/ # 仓储实现 ├── domain/ │ ├── entities/ # 领域实体 │ └── repositories/ # 仓储接口 └── presentation/ ├── pages/ # 页面 ├── widgets/ # 可复用组件 └── providers/ # 状态与业务逻辑

这套结构的优点是"同类东西放在一起"，找网络相关代码就去core/network，找数据模型就去data/models，路径非常可预测。它适合业务面比较窄的应用，比如工具类、单一大流程的 App。

但它的缺点在业务膨胀后会非常明显：一个"订单详情"功能，它的模型在data/models，仓储在data/repositories，页面在presentation/pages，状态在presentation/providers。你要改一个需求，得在四个目录之间来回跳。我做过一个业务模块超过二十个的项目，用这套结构，改一次"优惠券"相关逻辑要开七八个文件标签页，脑子很容易乱。

顺带说一个判断标准：如果你发现自己频繁在"跨层"跳转，那说明该考虑按功能切了。

3.2 按功能切分：Feature-first 的目录长什么样

按功能切分的思路是"一个功能的所有代码放在一个目录里"，把跨层跳转变成本地跳转：

lib/ ├── main.dart ├── app.dart ├── core/ # 依然是全局共享部分 │ ├── network/ │ ├── theme/ │ ├── router/ │ └── di/ ├── features/ │ ├── auth/ │ │ ├── data/ │ │ │ ├── auth_api.dart │ │ │ └── auth_repository_impl.dart │ │ ├── domain/ │ │ │ ├── user.dart │ │ │ └── auth_repository.dart │ │ ├── presentation/ │ │ │ ├── login_page.dart │ │ │ ├── register_page.dart │ │ │ └── auth_controller.dart │ │ └── auth.dart # 对外只暴露这一个入口 │ ├── order/ │ └── profile/ └── shared/ ├── widgets/ └── extensions/

注意最后那个auth.dart桶文件（barrel file）。它的作用是给功能模块划一条边界：模块外部只能从features/auth/auth.dart导入，不能深入到features/auth/data/...里去。这样做的好处是重构时你能放心大胆地改内部文件路径，只要桶文件导出的东西没变，外部就不会编译失败。

我自己定的规矩是：跨 feature 只能通过auth.dart这种入口文件通信，不允许横向 import 别人的内部实现。这一条能避免大量"删一个文件炸一片"的连锁反应。

core和shared的区别我一般这么界定：core放"和业务无关的基础设施"（网络、主题、路由、日志），shared放"和业务有关、但多个功能都要用的东西"（通用弹窗、业务组件、扩展方法）。分不清的时候，问自己一句"这东西换个 App 还能用吗"，能用就进core，只能用在我们这个业务里，就进shared。

3.3 入口文件、路由与依赖注入的组织

main.dart的责任应该被极度压缩——只做初始化，然后把控制权交给app.dart。我见过把路由表、主题配置、网络单例、状态容器全塞在main.dart里的，那个文件能到五百行，谁都不想打开。

// main.dart —— 只做启动前置工作 Future<void> main() async { WidgetsFlutterBinding.ensureInitialized(); final container = await bootstrap(); // 初始化存储、日志、环境配置 runApp(ProviderScope( overrides: [appContainerProvider.overrideWithValue(container)], child: const App(), )); }

WidgetsFlutterBinding.ensureInitialized()这行不是可有可无的。凡是runApp之前要调用平台通道（读本地存储、初始化推送、拿设备信息），不写这行就会抛"Binding has not yet been initialized"。我自己就踩过——写了个读取本地配置的异步函数放在runApp之前，报错信息完全没提这一层，找了好久。

app.dart里则专心搭壳：主题、路由、全局错误捕获、语言本地化。

class App extends StatelessWidget { const App({super.key}); @override Widget build(BuildContext context) { return MaterialApp.router( title: '示例应用', theme: AppTheme.light, darkTheme: AppTheme.dark, routerConfig: appRouter, builder: (context, child) => GlobalErrorBoundary(child: child!), ); } }

路由这块我强烈建议用声明式方案而不是手写Navigator.push。原因很实在：页面跳转逻辑散落在各处之后，做深链接、做埋点、做登录拦截会变得异常痛苦。登录拦截尤其典型——你希望未登录用户点任何需要权限的页面都跳登录页，命令式写法得在每个入口都写一遍判断，声明式路由只需要在路由配置里加一层redirect。

依赖注入这部分，小项目直接用一个全局容器就够了，大项目再引入专门的 DI 框架。我的经验是：不要在项目初期上重型的依赖注入框架，那会让新人的上手成本陡增，而且多数项目根本不需要那么强的能力。先从构造参数传递开始，等发现"参数要穿透七八层"时再抽象，这时候抽象的边界也更清楚。

4. 平台壳工程与多环境配置

4.1 android/ 与 ios/ 里真正需要动的地方

这两个目录虽然看着吓人，但日常真正会碰的就那么几个位置。我把它们列成表，方便需要时按图索骥。

表格里两处值得展开。

第一处是 iOS 的权限用途描述。iOS 的规则是：调用敏感能力时必须先在Info.plist里写明用途，用户看到的弹窗文案就来自这里。漏写的后果不是"弹窗文案难看"，而是调用直接失败，而且 Dart 侧往往只抛一个泛化异常。我在做一个扫码需求时就卡在这儿，最后靠逐条比对Info.plist才找到。

第二处是最低系统版本。这个值必须三处一致：Android 的minSdkVersion、iOS 的Podfile平台声明、Xcode 工程的 Deployment Target。只要有一处偏低，某些依赖在编译期就会报"要求更高的最低版本"，而报错指向的是依赖包，不是你的配置，很容易误判成"这个包不能用"。

.gitignore在这两个目录里也要补充规则，尤其是local.properties、Pods/、*.jks这类。签名文件绝对不能进仓库，密钥泄露的后果不用多说。我的做法是签名信息全部走环境变量或本机的key.properties，仓库里只留一个key.properties.example作为模板。

4.2 用编译期变量做多环境隔离，别硬编码

一个正式项目至少有开发、测试、生产三套环境，它们的接口地址、日志级别、统计开关都不一样。最常见的错误做法是写一个if (kDebugMode)三元表达式到处判断，或者更糟——直接改地址然后祈祷别忘了改回来。

我更推荐用编译期变量，一套代码打出不同产物：

flutter run --dart-define=APP_ENV=dev --dart-define=API_BASE=https://dev.example.com

class Env { static const appEnv = String.fromEnvironment('APP_ENV', defaultValue: 'dev'); static const apiBase = String.fromEnvironment('API_BASE', defaultValue: ''); static bool get isProd => appEnv == 'prod'; static bool get enableLog => !isProd; }

String.fromEnvironment是编译期常量，能被 tree-shaking 正确处理，也不会在产物里留下多余的字符串。相比之下，把配置写进一个 JSON 文件再运行时读取，虽然灵活，但等于把配置暴露在产物里，谁都能改。

更彻底的做法是配合各平台的构建变体（Android 的 productFlavors、iOS 的 Scheme），这样能做到"同一个手机上装两个版本、图标不同、包名不同、数据互不干扰"。做这个配置的工作量不小，但如果你的测试同学需要同时对比测试环境和生产环境，这个投入非常值。

我踩过的一个坑是：--dart-define的值里如果含有空格或特殊字符，必须加引号，而且不同 shell 的转义规则不一样。曾经有个接口地址带了查询参数里的&，在本地终端跑没问题，在 CI 的脚本里就被截断了，请求打到了错误的路径上，排查了很久才发现是 shell 把它当成了后台执行符。

4.3 图标、启动屏和那些"打包前才想起来"的配置

图标和启动屏属于典型的"开发时完全不管、发版前集体返工"的东西。手动去改各平台的资源目录非常容易漏，尤其 Android 的密度目录有五六个，iOS 的尺寸有十几种。我一般用现成的生成工具，准备一张 1024×1024 的源图，配置好之后一条命令跑完：

# 图标生成配置示例 flutter_launcher_icons: android: true ios: true image_path: assets/branding/icon.png adaptive_icon_background: "#FFFFFF" adaptive_icon_foreground: assets/branding/icon_foreground.png

dart run flutter_launcher_icons

Android 的自适应图标要特别留意：如果只给了前景图没给背景，某些启动器上图标会被裁成一个奇怪的形状。前景图还要预留安全边距，系统会做圆形、方形、水滴形等各种遮罩，图太满就会被切掉关键元素。

启动屏也是同理，而且它有个额外作用——避免白屏闪烁。原生启动屏会一直显示到 Flutter 引擎完成首帧渲染，如果没有配置，用户看到的就是一段纯白（或纯黑）界面，体验很差。配置的时候注意背景色要和 Flutter 首屏的背景色一致，否则会出现"启动屏消失 → 闪一下 → 内容出现"的割裂感。

还有一个容易忘的点：pubspec.yaml里的assets声明和实际文件必须严格对应。如果声明了一个不存在的目录，flutter build会直接报错退出；如果目录存在但是空的，某些版本的工具链也会警告。CI 上跑构建时这个问题会立刻暴露，但本地开发时很容易被忽略。

5. 测试、静态检查与工程化配套

5.1 analysis_options.yaml：把团队风格固化下来

这个文件常年被忽略，但它其实是团队代码风格的最低成本约束手段。默认生成的只有一行include: package:flutter_lints/flutter.yaml，够用但不够严格。

include: package:flutter_lints/flutter.yaml analyzer: exclude: - "**/*.g.dart" - "**/*.freezed.dart" errors: unused_import: error dead_code: error missing_return: error linter: rules: prefer_const_constructors: true prefer_final_locals: true avoid_print: true require_trailing_commas: true always_declare_return_types: true

exclude那两行很重要。代码生成产物的格式往往不符合人工书写规范，不排除的话分析器会报几百条警告，把真正的问题淹没掉。

avoid_print: true这条我建议所有正式项目都开。用print打日志在调试时方便，但产物里它会照常执行，既影响性能又可能把敏感信息带到用户的日志里。团队里应该统一用一个可开关的日志封装。

require_trailing_commas是争议比较大的一条。强制要求尾随逗号会让格式化后的代码更整齐，每次新增参数都只改一行，diff 更干净。但一开始团队会很不适应。我的处理方式是：先开成info级别跑两周，等大家习惯之后再提成强制。

关于自定义规则，还有个实用场景：禁止直接引用某些不该用的内部包。这可以通过analyzer的自定义 lint 插件实现，不过成本较高。更轻量的替代方案是在 CI 里跑一条 grep 检查，禁止lib/features/a/里出现import '../b/data/...'这种跨模块深度导入。

5.2 test/ 目录的分层与哪些代码值得写测试

测试目录的组织方式应该和lib镜像，这样找测试文件不用思考：

test/ ├── unit/ │ ├── repositories/ │ └── utils/ ├── widget/ │ └── features/ │ └── auth/ │ └── login_page_test.dart ├── integration/ │ └── flows/ │ └── checkout_flow_test.dart └── helpers/ ├── fixtures.dart └── test_harness.dart

分三层，各自的目标不一样：

• 单元测试：测纯逻辑，比如格式化函数、数据模型解析、仓储里的业务规则。跑得极快，应该占测试总量的七成以上。
• 组件测试：测单个 Widget 的渲染与交互，比如"输入框为空时按钮是否禁用"。它不需要真机，能在宿主机跑。
• 集成测试：测完整流程，跑在模拟器或真机上，速度慢、稳定性差，只保留最关键的主干路径。

哪些代码值得写测试？我的经验是按"改错的代价"排序，而不是按覆盖率排序。支付金额计算、优惠券叠加规则、订单状态机这类一旦算错就真金白银损失的逻辑，必须有单元测试；纯 UI 布局、颜色调整这类，写测试的收益远低于成本。追求 80% 覆盖率是个很危险的目标，它会逼着团队写一堆"能跑但没用"的测试。

组件测试里有个细节要提：涉及网络或平台通道的地方，必须替换成假实现，否则测试会依赖真实环境，稳定性极差。我习惯在helpers/test_harness.dart里封装一个"测试用的应用外壳"，统一注入假的仓储和假的状态容器，各个测试文件直接复用：

Widget wrapForTest(Widget child) { return ProviderScope( overrides: [ authRepositoryProvider.overrideWithValue(FakeAuthRepository()), ], child: MaterialApp(home: child), ); }

这段封装看起来不起眼，但它让每个测试文件少了十几行样板代码，而且换框架时只需要改一处。

5.3 CI 流水线里最少该有的四步

CI 我不追求花哨，先保证四件事跑通，就能挡掉八成问题：

# 1. 依赖一致性检查 flutter pub get # 2. 代码生成（有则跑） dart run build_runner build --delete-conflicting-outputs # 3. 静态检查 flutter analyze --fatal-infos # 4. 测试 flutter test --coverage

顺序有讲究。pub get放最前面，因为pubspec.lock不一致时会立刻失败，这比等到编译阶段才发现要省时间。代码生成放在分析之前，否则分析器会把生成文件当成缺失引用报错。--fatal-infos让警告也导致失败，这一条会逼着团队顺手清理警告，否则警告会越积越多最后没人看。

打包产物这块，Android 侧要注意构建缓存。CI 环境每次都是干净的，flutter build apk会重新下载依赖、重新编译，第一次可能要十几分钟。缓存~/.pub-cache、build/、Android 的 Gradle 缓存能把这时间压到两三分钟。但缓存也会带来"缓存中毒"的问题——缓存里存着旧的生成文件，导致构建结果和预期不符。我的处理方式是缓存目录里不包含build/，只缓存依赖下载部分。

一个真实场景：某次流水线突然开始失败，报"找不到某个生成类"，本地却是好的。最后定位到是缓存的build_runner中间产物过期，和新的模型定义对不上。清掉缓存重新跑就恢复了。所以我会在 CI 里加一个手动触发参数CLEAN_BUILD，遇到诡异问题时能一键绕过缓存验证。

6. 常见问题与排查实录

6.1 一张表覆盖大部分"目录结构"相关故障

6.2 几条不太会写在文档里的经验

第一，新项目第一件事不是写业务，是定目录规范。我在一个中期项目上做过"推翻重来"的目录重构，代价是两周内所有分支全部冲突，团队被迫冻结提交。如果一开始就花半天把features边界、core的职责、桶文件的导出规则定下来，这笔成本能省掉。规范不需要完美，能执行就行。

第二，别在lib根下放业务文件。哪怕只有一个页面，也建个features/xxx/presentation/放进去。我见过太多项目从lib/home_page.dart开始，最后长成四十多个文件平铺在根目录的样子，那时候再想整理，改动量已经大到没人愿意做了。

第三，build/目录出了问题，先删再重建，别查。这个目录纯粹是产物，删掉不会丢任何东西。我调过最久的一次编译失败，最后就是flutter clean加删除build/解决的，之前花的两小时全白费。养成"诡异问题先 clean"的肌肉记忆，能省很多时间。

第四，善用flutter doctor -v。它的输出里包含 SDK 路径、各平台工具链版本、模拟器状态，一半的"环境问题"看这一段就能定位。尤其是多人协作时报错不一致，第一件事就是交换flutter doctor -v的输出比对。

第五，把"新增一个 feature 需要改哪些文件"写成清单。我们当时的清单是：建目录、建桶文件、在路由表注册、在依赖注入里注册、建测试目录、加埋点常量。写下来贴在项目 wiki 里，新人照着做不会漏。这个清单每加一个新需求就可以验证一遍，它同时也是对目录设计是否合理的一次体检——如果某一步怎么都放不进去，说明结构本身该调整了。

第六，环境配置一定要能"一条命令切换"。我给自己定的标准是：换环境不需要改任何代码文件，单靠命令行参数就能完成。做到这一点之后，误把测试环境的地址打进生产包的概率基本归零。这条标准的成本很低，收益却贯穿整个项目生命周期。

最后分享一个我在实际项目里长期使用的判断方法：当你打开lib目录，能不能在三秒内说出"用户登录相关的代码在哪几个文件夹里"。能，说明结构是健康的；不能，那就别急着加功能，先把结构理顺。结构这个东西，越晚改成本越高，而它带来的收益是复利的。