企业官网建设流程全解析

Flutter .new——这是我私下给“新建Flutter项目”这个动作起的代号。每次敲下flutter create，我都觉得一个项目真正开始了：不是因为代码从这时候开始长，而是因为这一瞬间会把一堆隐藏约定一次性生成出来。标题里的.new不是什么隐藏命令，它代表我这些年沉淀下来的一套新项目流程：环境检查、参数设计、目录规划、依赖选型，以及第一轮工程质量配置。

这篇内容适合两类人。一类是刚接触 Flutter、马上要创建第一个项目的朋友：你可以把后面当成一份可以直接照做的清单；另一类是已经写过一两个项目、但总感觉初始化阶段没做对的开发者：我会把容易忽略的细节和排查思路摊开来讲。所有内容都来自真实项目里的反复试错，不是命令行文档的复述。

1. 为什么“新建项目”这个动作值得单独写一篇

很多人觉得flutter create敲完就完事了，剩下的直接开写。但恰恰是这一步，决定了项目后面三个月的维护姿势。我见过太多次“新建时省事、维护时加倍还债”的情况，所以先把这件事拆开看。

1.1 一条 flutter create 到底替你做了什么

新手最容易低估flutter create的产出。它不是一个空目录加一个 main.dart，而是一整套多平台工程骨架：

• Android：android/目录下已经有 Gradle 工程、build.gradle配置、MainActivity 入口；
• iOS/macOS：ios/、macos/目录里是完整的 Xcode 工程结构；
• Web 与桌面端：web/、windows/、linux/各自有平台壳；
• Dart 侧：lib/main.dart入口、默认pubspec.yaml、测试目录test/；
• 工程规范：analysis_options.yaml、.gitignore、README.md、.metadata都顺带生成。

这些生成物不是装饰，它们是一套隐藏契约。举个例子，Android 侧的applicationId在这时候定下来，后面上架市场想改包名就非常痛苦；iOS 侧虽然可以后改 Bundle ID，但会牵扯签名、描述文件、推送配置。也就是说，flutter create把很多“这辈子不常改、改一次伤筋动骨”的信息一次性焊在了工程里。

所以我把新建项目看作一个完整的工程活动，而不是一条命令。你要在按下回车之前就想好：这个项目叫什么、包名前缀是什么、面向哪些平台、模板用哪种。后面我会把每个参数都说清楚。

1.2 初始化前的半小时，怎样影响后面的维护成本

我观察过两个对比明显的项目。

A 项目：创建时全用默认值，开发同学直接在lib/main.dart里堆页面，文件按页面平铺，功能模块混在一起。一个半月后要加离线缓存，发现所有跟网络相关的请求逻辑散落在各处，状态管理也换过两轮，那段时间基本是在重构旧代码。

B 项目：创建第一天就按 feature 分组，每个功能模块下再分data/domain/presentation子目录，路由、依赖注入、状态管理都定了基准方案。后面迭代明显顺畅，新同学进来也能快速定位代码。

这两个项目差了不是代码量，而是“起步时的架构决策”。脚手架只保证“最小可用”，但“最小可用”不等于“可扩展”。状态管理选哪家、路由怎么组织、目录按类型还是按功能划分，这些是工具不会替你做的决定。新建项目这个动作，本质上是把这一类决定集中做一遍。

2. 动手前先检查环境：flutter doctor 的每一行怎么读

在运行flutter create之前，我会先跑一遍flutter doctor。大部分人只看最后一句“No issues found”，但中间几行如果有警告，新项目八成会在第一天踩坑。

2.1 用诊断输出反向检查工具链

flutter doctor的输出是有明确分组的，我建议按下表逐项核对：

如果某一行出现[!]，不要急着忽略。常见几种情况：

• Android licenses 未接受，命令是flutter doctor --android-licenses，一路按 y 即可；
• Java 版本不对，java -version确认，Flutter 3.x 对 Java 17 支持最好，不一定非要装最新版；
• iOS 侧报 CocoaPods 问题，新项目晚点也会在这里卡住，最好在创建之前处理好。

2.2 create 参数是决定新生项目“出身”的地方

flutter create的参数很多，但真正值得每次都敲的全在这里：

我自己新建 App 项目时，命令基本是固定格式：

flutter create --org com.example --project-name my_app --platforms android,ios --template app --empty my_app

--empty这个参数很多人没用过。它生成的lib/main.dart干净到几乎没有样板代码，不会给你一屏幕的 Counter Demo。别小看这个差异——默认模板自带的计数器页面和对应测试，会在新项目第一天给你一种“先跑通再说”的错觉，而--empty直接把起点切成真实项目的样子。

2.3 新项目成立后，先做三件不起眼的小事

创建完成后，我的固定顺序是：

cd my_app flutter analyze flutter test flutter run -d chrome

flutter analyze会立刻暴露未使用的变量、类型问题、格式问题；flutter test保证测试链路是通的；flutter run -d chrome则能不开模拟器就验证“代码能编译成可运行产物”。这三件事加起来不到两分钟，却能把后续调试时一半的“怎么跑不起来”消灭在萌芽阶段。

3. 默认模板不等于最佳模板：新建当天我会改掉的几个默认项

flutter create生成的模板质量相当高，但它是面向大众的。真实项目通常会基于它做一轮“私人订制”，我建议在新建当天就把下面这些改掉，不要拖。

3.1 计数器 Demo 先放一边：用 --empty 起步更干净

不是计数器 Demo 有什么问题，而是真实项目迟早要把那套占位代码删干净。既然迟早要删，不如一开始就不生成。--empty模板生成的 main.dart 只有最小启动代码，这能帮你从第一个 commit 开始就把目录规划成“业务项目的形状”，而不是“示例改出来的形状”。

3.2 pubspec.yaml 先补三行

打开pubspec.yaml，我至少会改三处：

name: my_app description: 一个用于新项目初始化的示例工程。 publish_to: 'none' environment: sdk: '>=3.4.0 <4.0.0'

description看起来很不起眼，但它会在 API 文档、错误上报和同事核对依赖时反复出现；publish_to: 'none'表示这个工程不是要发布到公共包仓库的包；environment.sdk写清约束，能防止某天在更低版本 SDK 上跑出莫名奇妙的兼容问题。

3.3 最小可用的 main.dart 骨架

用--empty创建后，我第一件事是把 main.dart 补成下面这个样子：

import 'package:flutter/material.dart'; void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp( title: 'My App', theme: ThemeData( colorSchemeSeed: Colors.indigo, useMaterial3: true, ), home: const HomePage(), ); } } class HomePage extends StatelessWidget { const HomePage({super.key}); @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text('Home')), body: const Center(child: Text('Hello, Flutter .new')), ); } }

这里useMaterial3: true在较新版本里已经是默认值，但显式写出来能让团队明确“我们采用的是 Material 3 设计基线”，减少后续组件风格不一致的讨论。

3.4 analysis_options.yaml：还没有代码就先定规矩

代码风格这种东西，等写了几千行再统一就要靠大范围重构了。新建项目当天就应该把analysis_options.yaml打开，确认它默认带着flutter_lints，再补几个我常用的规则：

include: package:flutter_lints/flutter.yaml linter: rules: prefer_const_constructors: true prefer_const_declarations: true

prefer_const_constructors会提醒你给不变的组件加const，这个小规则能让渲染性能更稳，也让代码意图更清楚。配合 IDE 的“保存时自动格式化”，新项目的代码风格偏差会小很多。

3.5 平台目录里的隐藏坑

默认生成的 App 图标是 Flutter 官方图标，应用名也叫项目名，这些一般都要改。但我不建议手动去改 Android/iOS 的图标资源，比较折腾。我用的是flutter_launcher_icons，在dev_dependencies里加一行：

dev_dependencies: flutter_launcher_icons: ^0.13.1

然后把图标路径配置好，运行dart run flutter_launcher_icons即可。注意版本号要以包管理器上的最新版本为准，我只是给个参考。

另外一个很容易漏的点：iOS 的启动页面名称、Android 的android:label。这些决定了 App 装到手机上之后显示的文字，建议新建当天就统一成正式产品名，否则后面容易被内部测试包搞得晕头转向。

3.6 测试文件：从第一天起就写真正有用的检查

默认模板会生成一个针对计数器的widget_test.dart，如果你用--empty，测试目录基本是空的。别让它空着。我倾向先写一个最简单的冒烟测试，确认主页能渲染出来：

import 'package:flutter_test/flutter_test.dart'; import 'package:my_app/main.dart'; void main() { testWidgets('首页应该显示标题', (tester) async { await tester.pumpWidget(const MyApp()); expect(find.text('Home'), findsOneWidget); }); }

这种测试看起来简单，但它固定了一个关键事实：应用的入口组件能正常 mount。以后如果有人在启动流程里塞了会抛异常的初始化逻辑，这个测试会第一时间跳出来报错。

4. 状态管理与路由选型：新项目第一天就该定下来的事

新项目最耗精力的不是写页面，而是选型。状态管理、路由、依赖注入，这三样不趁早定，后面每个功能模块都可能各自为政。

4.1 状态管理怎么选：别按社区热度选，按项目规模选

我给出的判断框架是先看规模再看团队：

选状态管理的核心逻辑不是“哪个火选哪个”，而是“哪个能在未来半年内减少沟通成本”。如果你一个人维护小项目，setState 完全够用；如果是三个人以上协作，Riverpod 这种带显式依赖关系的方案会更稳；如果模块很多、需要强约束，Bloc 的事件驱动模型能帮团队把业务逻辑写成相对统一的形状。

4.2 路由：自定义 Navigator 还是上框架

Flutter 自带的路由能力分成两代。Navigator 1.0用push/pop，写起来直观，但页面一多就会出现散落各处的跳转逻辑；Navigator 2.0提供完整能力，但要手动维护路由栈状态，容易做错。我建议中大型新项目直接上声明式路由，比如 go_router，因为它的核心价值不只是“跳转”，而是把路由表收拢成一个可测试、可深链的对象：

final router = GoRouter( routes: [ GoRoute( path: '/', builder: (context, state) => const HomePage(), ), GoRoute( path: '/detail/:id', builder: (context, state) => DetailPage( id: state.pathParameters['id'] ?? '', ), ), ], );

新建项目在第一天就把MaterialApp.router接好，后面每新增一个页面就是在路由表里加一行，比翻代码找Navigator.push要容易得多。

4.3 我给最常见起步项目的组合建议

不要第一天就上全家桶。我常用的演进路径是：

1. 第一个版本先用setState和原生 Navigator 写，跑通核心业务；
2. 页面超过五六个、共享状态开始出现时，引入 Riverpod；
3. 模块边界真正清晰、团队多人协作时，再把 Bloc 的层隔离引入。

依赖注入也不一定要上框架。构造函数传依赖在中小项目里完全够用，硬上框架反而会让每个页面多一层“从哪拿对象”的成本。新项目第一天要定的不是某个库，而是演进路径——比如“我们先用 Riverpod，等某条业务线复杂到需要事件流再局部引入 Bloc”，这个共识比库本身重要得多。

5. 从“能跑”到“稳定跑”：新项目必须完成的基础配置

很多人跑到flutter run能看到页面就以为新项目完成了。但“能跑”和“能长期稳定地跑”之间，还隔着一堆基础工程配置。

5.1 应用标识、版本号、图标与启动页

版本号在pubspec.yaml里看起来只有一行：

version: 1.0.0+1

它的含义是版本名 + 构建号。Android 平台会把这两个值映射到versionName和versionCode，iOS 侧需要在 Xcode 里同步。建议新项目第一天就把版本号策略定下来，比如：功能迭代升版本名，每次打包升构建号。否则在 TestFlight 或内部测试时，你根本分不清装的是哪个包。

应用图标和启动页也属于基础设施，越早定越好。我见过项目上线前一周才换图标，结果 iOS 审核因启动画面不符合规范被退回，整个团队陪着加班。这些活适合放在项目中前期做，越早做越不着急。

5.2 热重载的边界：哪些改动必须重启

flutter run之后，大多数人习惯按r热重载，但热重载不是万能的。我用下来的经验是：

遇到“改了代码屏幕没反应”，先判断改的是哪一种。尤其是pubspec.yaml改过依赖之后，热重载不会生效，必须停掉进程重新flutter run。这条规则早一点写进团队约定，能省掉很多“明明改了为什么没变化”的困惑。

5.3 工程质量基线：让 analyze 和 test 跑在每次提交里

新项目第一天就可以挂上持续集成。基础工作流很简单：拉取代码、装依赖、跑静态检查、跑测试。

name: flutter_ci on: push jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: subosito/flutter-action@v2 with: channel: stable - run: flutter pub get - run: flutter analyze - run: flutter test

这里我建议把channel显式写成stable，甚至锁一个具体 Flutter 版本。因为flutter analyze的规则和警告会随版本变化，不锁版本的话，团队不同成员可能得到不同的分析结果，持续集成的意义就少了一半。

5.4 构建产物：最小体积从第一天开始考虑

移动端包体积的优化不是后期专项，而是构建姿势的问题。Android 构建我建议从一开始就用：

flutter build apk --release --split-per-abi

--split-per-abi会让 Gradle 按 CPU 架构分别产出 armeabi-v7a、arm64-v8a、x86_64 三种包，整体体积比单一大包小不少。上架应用商店时，我建议用flutter build appbundle --release，让商店按设备架构分发。iOS 侧的对应命令是flutter build ipa。这些命令写在项目 README 的“构建指南”里，后来者就不会凭着记忆乱敲。

6. 新项目启动后最容易卡住的四个场景与排查思路

准备做得再充分，新项目启动阶段还是会遇到莫名其妙的问题。我按踩坑频率排序，把四个典型场景的完整排查链路写出来，遇到类似问题可以直接照着做。

6.1 Gradle 卡在下载依赖或构建超时

很多 Flutter 新项目第一次跑 Android 端会长时间停在Running Gradle task 'assembleDebug'...，然后超时。这不代表代码有问题，而是一次构建在下载大量依赖。

我的排查顺序是：

1. 先看 JDK 版本：java -version，Flutter 3.x 建议用 JDK 17，版本太老会直接触发 Gradle 兼容错误；
2. 停掉可能锁住 Gradle 的旧进程：

   cd android ./gradlew --stop

3. 回到项目根目录做一次干净构建：

   flutter clean flutter pub get flutter run

4. 如果还卡，确认本机网络能否稳定连接依赖仓库。

这条链路里，flutter clean常常被人忽略，但它在“Gradle 状态和 pub 缓存不一致”时非常有效。

6.2 模拟器上热重载不生效或白屏

热重载不生效比构建失败更烦。遇到白屏，我建议不要直接反复按r，而是做一次链路排查：

1. 用flutter run -v跑起来，看完整日志里有没有PlatformException或 Dart 异常；
2. 日志看不出问题时，按大写R做热重启，重新初始化整个 widget 树；
3. 如果热重启也没用，检查模拟器状态，有些模拟器的缓存和真机差异很大；
4. 最后兜底还是flutter clean再跑。

这类问题绝大多数不是热重载本身坏了，而是 App 的全局状态被污染了。尤其是环境配置、启动初始化逻辑这类代码，热重载保留状态的特征反而让问题残留，热重启和完整重启才是正规解法。

6.3 新建的 iOS 工程在模拟器上编译失败

iOS 侧的常见故障基本围绕 Xcode 和 CocoaPods。第一次编译失败时，我按这个顺序查：

1. 确认 Xcode 版本是否满足当前 Flutter 版本要求，版本差太大会出现奇怪的编译报错；
2. 执行cd ios && pod install --repo-update，很多问题是 Pods 没有生成或依赖版本陈旧；
3. 如果 Pods 还是报错，删除ios/Pods和Podfile.lock，重新pod install；
4. 签名类报错先不慌，模拟器构建本来不需要真机签名，检查一下 Project 里 Signing 配置是否被误设成真机模式。

不要一上来就改 Podfile，特别是不要为了消除警告去动platform版本，那经常是饮鸩止渴。

6.4 “我这里没报错啊”：构建环境不一致的灵异问题

团队协作时最经典的一幕是：A 说项目跑得好好的，B 却一编译就崩。大部分情况下是构建环境悄悄不一致了。我建议优先核对这四个变量：

一个非常实用的习惯：从新项目创建那天起，就把 Flutter 版本、JDK 版本、各平台工具版本写进 README，并让 CI 使用同一套版本。出现灵异问题时，先flutter clean再重启 IDE，比漫无目的地改代码有效得多。

最后说点个人体会。我现在每次新建项目，第一件事不是打开编辑器写代码，而是先在 README 里写清环境版本和目录约定，再执行那条flutter create。这个动作看起来多此一举，但两个月后新同学加入时，它会帮你省掉大量解释成本。Flutter .new 的真正含义，对我来说不是一条命令，而是把一个项目从“能跑”推向“能长期维护”的整个起点流程。希望这份记录，对你的下一个新项目也有帮助。