1. 环境搭建之前先把“搭的是什么”想明白1.1 一次flutter run背后到底经过了多少只手每次带新同事第一步都是 Flutter 环境搭建。大部分人把它理解成“装个 Flutter跑个 demo”结果装完之后发现flutter doctor一屏红叉然后就开始按报错顺序乱点越点越乱。问题的根源不在于操作复杂而在于没搞清楚这条链路上到底有几个环节在协作。一条完整的运行链路是这样的你写的 Dart 代码先由 Flutter 自带的 Dart 编译器处理成可执行产物同时 Flutter 框架层把 Dart 的 Widget 树翻译成各平台原生的绘制指令到了 Android 侧还需要 JDK 提供 Java 运行环境、Gradle 负责依赖解析与打包、Android SDK 提供编译所需的平台与构建工具到了 iOS 侧则需要 Xcode 的命令行工具链和 CocoaPods 管理原生依赖。也就是说Flutter 只是这条链路的“上游”它自己并不生产最终的应用包最终还是要交给各平台的原生工具链去打包。想清楚这一点很多所谓的“环境问题”就有了解释flutter doctor报的错绝大多数不是 Flutter 本身的问题而是它探测到了下游工具链缺件比如缺 JDK、缺 Android SDK、缺 Xcode license。所以正确的心态是把它当成一个“体检报告”从下往上修而不是从上往下修。我在实际项目里带的几个组都是先让他们把下游装齐再回头装 Flutterdoctor一次全绿的概率高得多。还有一点容易被忽略Flutter 的 SDK 本身是自包含的它内部绑定了特定版本的 Dart 编译器、打包脚本、以及一堆模板文件。这意味着升级 Flutter 往往会顺带改变 Dart 版本和构建模板进而影响既有工程的构建结果。所以环境搭建不只是“装上”还得考虑“以后怎么换版本”。这是很多人搭完环境三个月后才开始后悔的地方那时候一堆工程已经建好了切版本代价陡增。适合看这篇内容的人我大致分成三类完全没接触过 Flutter、想从零搭一套能长期用的环境的装过但一直有红叉、跑不起来 demo 的以及环境能跑但每次依赖同步、切换分支都要重装一遍、效率极低的。这三类的处理路径其实不一样后面我会分别标出来。1.2 版本策略为什么不建议一上来就追最新先说一个反直觉的观点环境搭建阶段选版本的第一原则是“能被复现”不是“足够新”。很多人第一次装就下载最新版本然后照着一年前的教程配置命令对不上、参数名改了、目录结构也变了最后怀疑人生。我的做法是分两层考虑。第一层是渠道选择Flutter 提供多个发布渠道日常开发用正式发布渠道就够了试验性功能才去碰 beta 或 dev 渠道而且只在独立目录里碰绝不和主环境混在一起。第二层是具体版本号如果你要维护已有工程就去看那个工程pubspec.yaml里声明的 SDK 约束以及工程根目录下记录的版本信息照着装同一个大版本如果是全新项目选当前正式渠道的最新版本即可但要在搭建完成后立刻把版本号记到一份个人环境清单里后面所有机器都对齐它。为什么不建议“装最新的就行”还有一个现实原因Flutter 版本和 Android 的构建工具版本、JDK 版本之间存在兼容矩阵。新版本 Flutter 往往要求较新的 JDK而较新的 JDK 又可能和旧工程里的 Gradle 版本打架。你现在装个最新的三个月后接一个老工程就得再装一遍旧版本。与其到时候折腾不如一开始就把“多版本共存”这条路留出来。留路的方式很简单不要用安装器把 Flutter 装到系统默认位置而是手动下载压缩包解压到一个你自己管理的目录下一个版本一个文件夹。比如在一个统一的工作目录下建sdk/flutter-3.x-a、sdk/flutter-3.x-b这样的结构切版本时改一个环境变量或者用版本管理工具指过去就行全程不重装、不覆盖。这个习惯我坚持了好几年带人时也一直这么要求省下来的时间非常可观。2. 核心组件逐项拆解与配置要点2.1 Flutter SDK 的下载与目录规划路径里别留空格和中文Flutter SDK 本质就是一个压缩包解压即用不需要安装。听起来最省事的一步恰恰是踩坑率最高的地方罪魁祸首几乎都是路径。我把这条当成铁律Flutter SDK 的存放路径、工程路径、以及所有相关工具的安装路径全部不允许出现空格和中文。原因不是 Flutter 不支持而是它调用的下游工具链里有些老旧的脚本对路径转义处理不严谨一旦路径含空格就容易在构建过程中被截断成两段报出来的错还完全不相干比如“找不到某个文件”而你去看那个文件明明在。这类问题排查起来极其费时因为报错信息和真实原因之间没有逻辑关联。路径规划上我一般这么安排在最外层建一个纯英文的根目录下面按职责分层SDK 一层、Android SDK 一层、工程代码一层、缓存一层。分层的好处是后面清理缓存、迁移机器、给同事拷环境的时候不用在一堆系统目录里翻找。还有一个隐性收益如果你哪天要把环境整体搬到另一台机器直接压缩根目录拷过去改改环境变量基本就能用。解压之后不要急着跑命令先确认两件事。一是解压是否完整可以看目录下有没有bin、packages、bin/cache这几个关键目录二是第一次运行flutter命令时会触发一次初始化下载它会往bin/cache里拉取 Dart SDK 和若干工具产物这一步网络不好会卡很久属于正常现象不要以为卡住了就中断中断容易留下半截的缓存后面反而得手动删。如果这一步反复失败可以先把公共镜像源配好再重来镜像配置我在第 5 节展开。一个常见的误区是把 Flutter SDK 装到需要管理员权限的系统目录里。这样做的后果是后续 SDK 升级、缓存写入、插件下载都可能因为权限不足失败而在某些系统上这种失败表现得非常隐晦——不报“权限不足”而是报下载超时或者文件写入异常。所以尽量放在当前用户可完全控制的目录下。2.2 环境变量Path 里到底该放几条环境变量这一步很多教程只写“把 flutter/bin 加到 Path”但实际上一套能长期用的配置需要好几个变量而且它们的作用各不相同混在一起讲就容易记错。变量指向作用常见错误PathFlutter SDK 下的 bin 目录让终端能找到 flutter 命令指到了 SDK 根目录而不是 binPathAndroid SDK 下的 platform-tools让 adb 等命令可用与 Flutter 的 bin 顺序颠倒导致命令冲突JAVA_HOMEJDK 安装根目录构建时定位 Java 环境指到了 JDK 的 bin 目录ANDROID_HOMEAndroid SDK 根目录供构建工具和 IDE 定位 SDK与 IDE 内置路径不一致镜像变量公共镜像地址加速依赖与产物下载只配了一个另一个没配导致部分卡住这里面最容易错的是 JAVA_HOME。规则是指向 JDK 的根目录不是 bin 目录。判断方法很简单如果你设的路径下直接有bin/java可执行文件那就是对的如果你设的路径下只有一个bin文件夹那就多了一层。第二个容易出错的是 Path 里的顺序。如果你的机器上同时装了多个 Java 版本或者多个 Flutter 版本Path 里靠前的那个会生效。我见过因为旧版本残留在 Path 靠前位置导致flutter --version显示的和实际目录里的版本对不上排查半天以为是缓存问题。所以每次改完 Path务必新开一个终端窗口把flutter --version、java -version、adb version三条命令都跑一遍确认输出和你预期一致。旧终端不会重新加载环境变量这是个低级但高频的坑。至于镜像变量它们具体影响的是包索引查询和产物下载这两个环节。之所以要分开配是因为这两类请求走的域名不同只配一个的话另一类请求仍然会走默认地址表现出来就是“依赖能解析但下载很慢”或者“下载很快但依赖列表拉不出来”这种半好半坏的状态。判断有没有配全办法是清一次缓存后重新拉取依赖看过程是否都顺畅。2.3 Android 侧JDK、SDK、构建工具的三方关系Android 这一侧是环境搭建的重灾区因为它涉及三个互相牵制的组件JDK、Android SDK、Gradle。搞不清它们的关系就会陷入“升了这个坏那个”的循环。先说 JDK。现在主流的做法是直接用 Android Studio 自带的那套 JDK位于其安装目录下的jbr目录里。这样做的好处是版本天然匹配不用另外装坏处是如果你在终端里直接跑 Gradle 命令需要手动把 JAVA_HOME 指过去。如果你想独立管理那就单独装一个 LTS 版本的 JDK并且记住Flutter 新版本普遍要求较新的 JDK老工程里的 Gradle 又可能不支持太新的 JDK。这是一对现实矛盾处理办法就是多版本共存用的时候切换 JAVA_HOME。再说 Android SDK。通过 IDE 的 SDK 管理器安装时至少要勾选这几类平台版本对应你要编译的目标版本、构建工具、平台工具、以及模拟器相关组件。很多人只装了平台版本结果flutter doctor提示缺构建工具或者缺 adb就是因为漏勾了。另外SDK 的存放路径同样要遵守纯英文无空格的规则而且一旦选定就不要轻易改因为改了之后需要同步更新 ANDROID_HOME 和 IDE 里的配置工程里也可能有本地配置文件记着旧路径。最后是 Gradle。这里有一个必须建立的认知Gradle 版本和 Android 构建插件版本是强绑定的不能各升各的。工程里通常有两个地方涉及版本一个是 Gradle 自身的版本一个是构建插件的版本两者必须落在官方给出的兼容区间内。当你从别处拉来一个工程跑不起来报的错又和构建脚本相关第一反应应该是去看这两个版本号而不是盲目升级到最新。另外还有个常被忽视的点Gradle 的守护进程会吃掉不少内存。默认配置下同时开几个工程构建机器就容易变得很卡。我一般会在工程的构建配置里显式设置内存上限比如给到 4GB同时开启并行构建和构建缓存。参数不是越大越好超过物理内存会导致频繁换页反而更慢。经验值是机器 16GB 内存给 4GB32GB 给 6GB再往上收益不明显。2.4 iOS 侧命令行工具与原生依赖管理如果你只做 Android这节可以先跳过但只要目标平台包含 iOS就必须先把这套东西装齐否则flutter doctor会一直挂一条警告而且真机调试时会直接失败。第一件事是装 Xcode 命令行工具。注意这里有个顺序先完整安装 Xcode再执行命令行工具的安装命令最后同意许可协议。很多人卡在“许可协议未同意”这条报错上原因就是装完 Xcode 后从来没跑过同意许可的那条命令。这条命令需要管理员权限执行时会让你滚动阅读一长段文本读到底输入同意即可。第二件事是原生依赖管理工具。Flutter 的 iOS 工程在构建前会执行一次依赖安装如果这个工具缺失或者版本太旧构建就会在这一步中断。安装方式有几种我倾向于用系统包管理器安装避免和系统自带的运行时版本纠缠。装完之后要验证版本因为版本过低会导致依赖解析失败而报错信息往往指向具体的依赖包看起来像是包的问题实际是工具太旧。第三件事是签名配置。这一步不属于“装环境”但它是第一次真机运行必然撞上的墙。模拟器不需要签名所以很多人模拟器跑得飞起一插真机就懵。建议的做法是环境搭完后立刻在 Xcode 里打开一次生成的工程把开发者账号和签名团队配置好同时确认设备已注册。这些操作在 IDE 里点几下就完成但如果等到写完代码才发现会很打断节奏。还有一个实操细节iOS 的构建缓存目录非常大一个中等工程跑几次就能占到几个 GB。如果你机器空间紧张定期清理这个目录是必要的但清完之后第一次构建会明显变慢这是正常代价不要以为环境坏了。2.5 IDE 与插件编辑器选谁插件装哪几个编辑器这件事没有标准答案但有两个现实约束值得说清楚。如果你要维护原生工程里的配置比如签名、权限声明、原生依赖用功能更全的那套 IDE 会省很多事因为它对原生工程的支持是原生的如果你日常就是写 Dart、跑热重载、看日志轻量的编辑器启动快、占用小体验更顺。我自己是两套都装重活开重的日常改 UI 开轻的工程目录共用互不干扰。插件方面核心的只有两个语言支持插件和运行调试插件前者提供代码补全、跳转、格式化后者提供设备选择、热重载按钮、调试面板。这两个装好剩下的都是锦上添花。我见过有人装了十几个相关插件结果互相抢快捷键、抢格式化规则代码保存时被改成两套风格反而添乱。需要特别提醒的是格式化配置。Dart 的格式化规则会随 SDK 版本变化如果编辑器里配置的行宽和团队约定不一致提交代码后会出现大量纯格式的 diff非常影响 code review。建议在工程根目录放一份分析配置文件把行宽、规则集写进去让编辑器读取工程配置而不是全局配置这样团队里所有人格式化结果一致省掉无数无意义的争论。3. 动手实操从零到第一次成功运行3.1 落地顺序先下游后上游前面讲了原理这里给一套可以直接照做的顺序。我把顺序设计成“从下游往上游”理由是每一步都能独立验证出错时定位范围小。第一步装 JDK。选一个 LTS 版本装到纯英文路径配置 JAVA_HOME然后在终端验证java -version输出版本号且没有报错。这一步不通后面全白搭。第二步装 Android SDK。通过 IDE 的 SDK 管理器安装勾选平台、构建工具、平台工具、模拟器四类。装完在终端验证adb version能输出版本。如果提示命令不存在说明 platform-tools 目录没进 Path回去补。第三步装 Flutter SDK。下载压缩包解压到规划好的目录把 bin 目录加进 Path配好镜像变量然后执行flutter --version。第一次会初始化下载耐心等它走完看到版本号和渠道信息就说明 SDK 本身没问题。第四步把 Flutter 和 Android 绑起来。执行 SDK 路径配置命令把 Android SDK 的路径告诉 Flutter然后执行许可接受命令把一系列 SDK 许可一次性同意。这一步不做构建时会报许可未接受而这个报错在构建日志里位置很靠后容易被忽略。第五步体检。执行flutter doctor -v注意加-v详细模式能看到具体路径和版本比简版有用得多。然后按“缺什么补什么”的原则逐条处理顺序是从最底层的缺失项往上修。这套顺序我在不同机器上走过很多次只要每步都验证过最后一次性全绿的概率很高。反过来说如果你跳步比如跳过 JDK 验证直接装 Flutter那么后面任何一个构建错误你都得先怀疑是不是 JDK 的问题排查成本翻倍。3.2 逐条消红flutter doctor的正确读法flutter doctor的输出分几大块每块前面有个状态标记。我的处理原则是只看有问题的块从上往下修修完一块重跑一次。不要一次性修完所有再跑因为后面的问题有可能是前面的问题导致的连锁反应。第一块是 Flutter 自身。这里出问题一般是缓存损坏或者渠道异常处理办法是清缓存后重新初始化。清缓存命令会删掉bin/cache下的产物重新执行 flutter 命令时会自动重拉网络通畅的话几分钟就恢复。第二块是 Android 工具链。常见提示有三种缺 SDK、缺许可、缺构建工具。缺 SDK 就去配路径缺许可就跑接受命令缺构建工具就去 SDK 管理器补装。第三块是 IDE 插件。这里提示的是某个编辑器没装 Flutter 插件不影响命令行构建按需处理即可。第四块是设备。提示“未连接设备”是最常见的因为还没开模拟器。这时候不要急着建模拟器先用命令列出可用设备确认工具能识别到已经开着的模拟器或真机。还有一块是网络资源检查它探测的是几个关键下载地址是否可达。如果你的网络访问这些地址很慢这里会一直挂着提示。它不影响本地构建但因为每次doctor都会跑一遍会拖慢整个体检过程。我一般会在确认其他项都正常之后用跳过网络检查的参数跑一次拿到干净的结果。这里分享一个判断技巧如果某一块的提示信息里带了具体路径那就说明它找到了这个组件只是在核对版本或者状态如果提示里完全没提路径那就是压根没找到。这两种情况的处理方式完全不同前者要查版本兼容后者要查环境变量和安装完整性。3.3 创建工程与首次运行把变量控制到最少环境体检全绿之后别急着在已有工程上试那会引入太多变量。先用命令新建一个最小工程跑通它再回头处理你的目标工程。新建命令里有两个参数建议显式指定一个是组织标识它会影响包名后面上架或者接第三方服务都会用到中途改很麻烦另一个是工程名注意只能用下划线命名不能用横杠这是 Dart 包命名的强制要求。工程名一旦定了改起来涉及目录名、包名、配置文件多处很烦。所以第一次建工程时多花三十秒想名字后面省半小时。建好之后先别急着跑先确认目录结构。根目录下你会看到几个关键文件和目录依赖声明文件、分析配置文件、以及各个平台的原生工程目录。理解这个结构的意义在于你会知道哪些代码是共享的、哪些是按平台定制的。共享的那部分是 Dart 代码定制的那些是各平台的原生壳工程——这也是 Flutter 项目在需要深度定制原生能力时依然能下手的入口。运行分两步先用设备列表命令确认目标设备在线再用运行命令启动。第一次启动会做完整的构建耗时明显长于后续因为要下载依赖、编译原生壳工程、生成本地产物。这个过程如果卡住看日志里的最后一行是哪个任务基本就能定位到卡在依赖下载还是编译阶段。首次运行成功后别关掉故意改一行界面代码保存看热重载是否生效。这个验证很关键因为热重载依赖调试连接连接有问题时虽然能启动但热重载会失效而你会在写了两小时代码之后才发现每次改都要重启效率损失巨大。3.4 写一个自己的启动脚本把每次要敲的命令收起来环境搭好后日常开发其实就那么几个动作选设备、拉依赖、运行、清缓存。但它们都带一长串参数敲多了烦记错一个参数就白等。我的习惯是在工作目录下放几个脚本把固定参数固化进去。比如一个“干净启动”的脚本先拉依赖再跑构建遇到问题就清缓存重来再比如一个“切换目标设备”的脚本把设备标识作为参数传进去。脚本不用写得多优雅能省掉记忆负担就行。这里有个心得脚本里的路径一律用变量不要写死绝对路径。写死的后果是换机器、换目录、给同事用的时候全部失效还得逐行改。用变量的成本是多写一行定义收益是可移植。我一般会把 SDK 路径、工程路径、设备标识都提成变量放在脚本顶部一眼能看全。再补一个细节脚本执行失败时默认可能继续往下跑导致后面的步骤在错误状态下执行产生一堆误导性日志。稳妥的做法是在脚本开头加上“遇错即停”的设置让它在第一个失败点就中断。这样日志干净定位也快。4. 踩坑实录环境问题排查速查表4.1 先分类再动手三类问题的判断方法环境出问题时最忌讳的是“看到报错就搜”。我一般先花一分钟做分类因为不同类别的排查路径完全不同。第一类是找到不到工具典型表现是命令不存在、路径找不到、文件缺失。这类问题九成出在环境变量上变量没配、配错层级、或者配了但终端没重新加载。处理办法是回终端验证每一条路径变量的实际值然后手动进那个目录看文件在不在。第二类是能跑但构建失败典型表现是依赖解析失败、版本冲突、编译报错。这类问题看报错的第一行比最后一行有用因为构建工具会把根本原因放在前面后面全是级联的失败信息。判断的关键词是版本号和不兼容看到就直奔兼容矩阵去查。第三类是能构建但运行异常典型表现是装到设备上闪退、白屏、功能不响应。这类问题往往不是环境问题而是配置或代码问题比如权限没声明、原生依赖没注册。这类排查要看设备日志而不是构建日志两者的信息完全不同源。分类之后还有个技巧改一个变量就重跑一次不要一次改五处。我见过有人对着报错连改五处配置然后问题消失了但他不知道是哪一处起了作用下次遇到同样问题还得重来一遍。环境配置这件事可复现比“能跑”更值钱。4.2 高频问题速查表下面这张表是我这些年攒下来的基本覆盖了新人搭建环境时八成的卡点。现象大概率原因处理方向命令提示不存在路径没进环境变量或终端未重载核对变量值新开终端验证首次初始化卡住很久正在下载工具产物或网络受阻观察缓存目录是否在增长必要时配镜像构建报许可未接受未执行许可接受命令补跑许可命令同意全部条目构建报某版本不兼容构建工具与插件版本不匹配查兼容矩阵成对调整版本依赖拉取失败包索引地址不可达或缓存损坏清缓存重试检查镜像变量是否配全模拟器起不来硬件虚拟化未开启或镜像未下载进固件设置开启虚拟化补下系统镜像真机连不上调试模式未开或驱动/授权未完成开调试模式重新插拔并确认授权弹窗构建成功但装不上设备架构与产物不匹配检查目标架构配置热重载无效调试连接断开重启调试会话检查端口占用构建极慢首次构建无缓存或内存配置过低调高构建内存确认缓存开关已开表里每一行背后都有具体场景我挑两个最费时的展开说。“构建报某版本不兼容”这一条新人最常见的错误反映是“那我把它升到最新”。这个动作在环境没问题时是优化在有问题时是加变量。正确做法是先看清楚是谁和谁不兼容是构建工具和插件不兼容还是 JDK 和构建工具不兼容。这两对关系的调整方向相反——前者要成对升或成对降后者一般是降 JDK 而不是升构建工具。搞错方向就会陷入“升完这个又报那个”的循环。“模拟器起不来”这一条很多时候不是软件问题。模拟器需要硬件虚拟化支持而这个开关在机器出厂时可能是关闭的需要进固件设置里打开。打开之后还要注意某些系统上多个虚拟化方案会互相抢占装了两个模拟器方案时可能出现“明明开了虚拟化却报不可用”处理办法是确认只启用一套方案。这个坑我在三台不同机器上遇到过每次都要重新回忆一遍排查顺序。4.3 几条压箱底的处理技巧第一条遇到说不清的构建错误先做一次彻底清理再重来。清理包括工程内的构建产物、依赖缓存、以及全局构建缓存。很多人只清了工程内的产物全局缓存里的脏数据还在重跑之后错误照旧于是判定“清理无效”。清理完第一次构建会慢这是必然的。第二条日志不要只看末尾。构建工具的日志顺序是先报根本原因后面是一连串的衍生失败。末尾那些“任务执行失败”基本都是噪音。看日志的正确姿势是从上往下找第一个带有具体原因的行。第三条把环境信息记录成文档。这不是形式主义。我在每个项目的仓库里放一份环境说明写清楚 SDK 版本、JDK 版本、构建工具版本、以及关键配置项。新人进来照着装出了问题一比对就知道差在哪。这份文档的维护成本极低收益极高尤其是在团队里有人换机器或者加人的时候。第四条别在环境有问题时写业务代码。听起来像废话但实际很常见热重载失效了就手动重启重启要等一分钟一天下来浪费的时间非常可观而且打断思路。环境问题应该在十分钟内解决掉解决不了就先停下来专门处理不要带着问题开发。第五条备份一份能用环境。配置全部验证通过后把 SDK 目录、环境变量配置、关键配置文件打包存一份。下次换机器或者环境被搞坏时恢复比重装快得多。这一步我是在吃过一次亏之后才养成习惯的某次升级后环境彻底崩掉重装加调试花了大半天而如果当时有个备份恢复也就十几分钟。5. 环境通了之后让它长期好用的几个配置5.1 镜像与缓存把重复下载的成本降下来环境能跑只是起点真正影响日常体验的是依赖下载速度。Flutter 的依赖分两类Dart 生态的包和原生侧的构建依赖它们走的是不同的仓库需要分别配置。Dart 侧的镜像通过环境变量配置一般需要配两个一个指向包索引服务一个指向产物存储服务。两个都要配只配一个会出现半好半坏的状态前面提过。配置完成后建议清一次缓存再拉依赖确保新配置真正生效而不是命中旧缓存让你误以为配好了。原生侧的依赖走的是另一套仓库机制需要在工程的构建脚本里声明仓库地址。这里的原则是把公共镜像地址放在仓库列表靠前的位置官方地址保留在后面兜底。这样既享受了速度又不会因为镜像缺包而彻底失败。需要注意仓库声明的位置在不同版本的构建脚本里有变化新版倾向于集中在一个统一的地方声明老版则分散在各个工程文件里。改之前先看清楚当前工程的脚本结构别照着老教程改错文件。缓存这一块我建议定期清理但不要频繁清理。清理的收益是释放空间、消除脏数据导致的神秘错误成本是下次构建变慢。合理的节奏是遇到说不清的构建错误时清一次以及每隔一段时间集中清一次其余时候别动。5.2 多版本共存把切版本变成一条命令前面提过要一个版本一个目录这里说具体怎么用。最朴素的做法是维护几套环境变量切版本时改 Path 的顺序。缺点是要手动改容易忘。稍微好一点的做法是写个切换脚本把不同版本的路径写成配置执行脚本时自动改当前会话的环境变量。这个方案的优点是零依赖缺点是只对当前终端会话生效IDE 里还得单独配。再进一步是用版本管理工具这类工具的原理其实很简单它把多个 SDK 版本放在统一目录下然后在项目里放一个版本声明文件进入项目目录时自动切换。好处是切换粒度精确到项目坏处是多了一个需要维护的工具以及它对某些 IDE 的自动识别支持不一定完善。我用下来的建议是如果你同时维护三个以上不同 Flutter 版本的项目值得上工具如果只有一两个脚本加目录管理就够了别为了工具而工具。不管用哪种方案有一条必须遵守切换版本后要清一次构建缓存。不同版本的构建产物格式可能不兼容混在一起用会出现很难解释的错误比如编译通过但运行白屏。清缓存这一步花几分钟能省掉几小时的排查。5.3 新工程默认配置一开始就设对后面少改最后说说新工程的初始化配置这些设置改起来不难但改晚了要动很多文件。第一项是依赖版本约束的写法。尽量用范围约束而不是固定版本范围能让你在拉依赖时拿到兼容的补丁版本固定版本则会让整个依赖树僵化后面想升某个包时会发现处处受限。当然范围也不能太宽太宽容易拉到不兼容的大版本一般是锁定主版本号放开次版本和补丁版本。第二项是分析规则配置。把团队约定的规则写进工程内的配置文件包括行宽、禁用哪些写法、开启哪些检查。这份配置会和编辑器联动让所有人保存时格式一致。这件事越早做越好等到代码写了几万行再来统一格式diff 会非常难看。第三项是构建产物的忽略配置。把构建产物目录、本地配置文件、缓存目录都加进忽略列表避免误提交。这块最容易漏的是本地环境配置文件一旦提交上去别人拉下来会拿到你的本地路径构建直接失败。第四项是目录结构的约定。Flutter 工程默认只有一层源码目录项目稍大就会乱。建议在开始写业务代码之前就定好分层比如按功能分目录、把共享组件单独放一层、把平台相关代码隔离开。这个决定不用一开始就很完美但要有因为后面迁移成本会随时间线性上升。我个人在实际操作中的体会是环境搭建这件事的价值被严重低估了。大部分人把它当成一次性的体力活装完就忘结果在之后的每一周都要为当初的随意付出一点代价构建慢一点、切版本烦一点、出错排查久一点。这些代价单次都不大累积起来很可观。把两三个小时花在把环境理清楚上后面几个月都会顺很多。尤其是路径规范和版本管理这两件事前者决定你会不会遇到那些毫无道理的报错后者决定你半年后接老项目时是十分钟上手还是折腾一天。
