Flutter环境搭建

刚开始接触 Flutter 的过程是极其痛苦的，不是说这门技术栈有多难，而是它的开端——环境搭建就让人望而却步，太多的坑等着你来踩。接下来我们就来体验下 Flutter 的环境安装和项目启动调试。

1. 使用镜像

由于在国内访问 Flutter 有时可能会受到限制，Flutter官方为中国开发者搭建了临时镜像，大家可以将如下环境变量添加到到用户环境变量中：

export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

ps：此镜像为临时镜像，并不能保证一直可用，读者可以参考flutter.dev/community/c… 以获得有关镜像服务器的最新动态。

2. 在 Windows 上搭建 Flutter 开发环境

系统配置要求

• 操作系统：Windows 10 或更高的版本（基于 x86-64 的 64 位操作系统）。

• 磁盘空间：除安装 IDE 和一些工具之外，还应有至少 1.64 GB 的空间。

• 设置：必须在 Windows 10/11 上启用开发者模式。

• 工具：要让 Flutter 在你的开发环境中正常使用，依赖于以下的工具：

  • Windows PowerShell 5.0 或者更高的版本（Windows 10 中已预装）；
  • Git for Windows 2.x，并且勾选从 Windows 命令提示符使用 Git 选项。

如果 Windows 版的 Git 已经安装过了，那么请确保能从命令提示符或者 PowerShell 中直接执行 Git 命令。

2.1 安装 Android Studio

直接到 Android Studio 官网下载安装，选择默认配置、安装对应的包：

下载完成后，安装 SDK Manager:

下图中勾选的项都要下载：

ps：flutter2 的项目只能使用sdk Commin-line Tools 8.0版本：

可能出现的报错：

• Intel HAXM installation failed. To install Intel HAXM follow the instructions found at...

解决方式请参考文章：blog.csdn.net/qq_24033983…

直到出现如下图所示，说明该问题已解决：

2.2 Android SDK 环境变量配置

Android SDK默认安装路径为：C:\Users\YourName\AppData\Local\Android\Sdk，如果更换了Android SDK的安装路径，则下面的环境变量设置是必须的。

依次打开：系统属性>高级>环境变量。

首先，系统变量中新增ANDROID_HOME ，设置值为安装根目录：

然后在系统变量Path中，增加两个值；%ANDROID_HOME%\tools，%ANDROID_HOME%\platform-tools

2.3 安装 fvm

fvm，全称：Flutter Version Management，Flutter版本管理工具，使用fvm可以在不同版本的 flutter 直接切换。可以类比 nvm 管理不同版本 node

关于 fvm 的安装，很多文章都会推荐通过 pub 来全局安装，即下面命令

dart pub global activate fvm 

通过这种方式安装好的 fvm 可能会出现闪退的情况，最重要的是你得要让 dart 这个命令能用的起来，那么你就得去 flutter 官网 下载稳定版本，然后再去配置 flutter 环境变量，但是你又得使用 fvm ，那么一开始配置的 flutter 的环境变量又得要修改。为了简便且不再去踩更多的坑，我们直接在 github下载 fvm。

配置 fvm 环境变量：

其中 D:\fvm\default\bin 指向默认的flutter版本

2.4 下载 flutter sdk

公司关于 pad 的项目， flutter 使用到了 2.2.3 和 3.10.2 两个版本，我们通过 fvm 来下载版本

fvm install 2.2.3
fvm install 3.10.2

除了使用命令安装，也可以直接将从官网已经下载好的 sdk 解压到 D:\fvm\versions （安装路径按照自己实际的来）中，注意要将文件夹名称改成对应的版本号。

关于 fvm 的一些命令：

fvm releases 查看所有可以安装的flutter版本
fvm list 查看当前下载了哪些版本的sdk
fvm install 2.2.3 安装指定版本的 flutter
fvm remove 2.2.3 删除指定版本的 flutter
fvm global 3.10.2 设置全局 flutter 版本
fvm use 3.10.2 设置当前项目的 flutter 版本

如果发现无法切换，可在命令后添加 --force

关于设置全局/切换 flutter 版本的命令需要在管理员身份下执行cmd或PowerShell

使用如下命令可以查看当前所有环境变量的设置情况：

flutter doctor

输入命令 flutter devices 可以查看可供运行的设备：

2.5 安装 java sdk

对于 fluter2 的项目，需要去安装 jdk 和配置 java 环境变量，flutter3 开始不再需要。

我下载的 jdk 版本是 11.0.24，具体版本每个人按照自己的实际情况来，jdk 相关安装和环境配置请参考文章：Win10安装jdk11及环境变量配置

2.6 安装 Visual Studio

如果需要开发 windows 桌面端的程序，还需要安装以下内容： Visual Studio 2022 或 Visual Studio 2022 生成工具

在选择安装 Visual Studio 时或只安装生成工具的时候，你需要选择「使用 C++ 的桌面开发」，包括其所有默认组件，以安装必要的 C++ 工具链和 Windows SDK 的头文件。

2.7 配置安卓模拟器

因为我们做的是pad端开发，因此修改AVD name为：pad

安卓模拟器使用起来一般比较卡顿，我们需要将 Graphics 即图形渲染模式由 默认的 Automatic 改为 Hardware - GLES2.0。

Hardware 即使用电脑中的显卡进行渲染，这个选项可以提高虚拟机的渲染性能。Software 即CPU渲染，该渲染模式一般会较慢。

启动模拟器：

2.8 连接Android真机设备

要准备在Android设备上运行并测试Flutter应用，需要Android 4.1（API level 16）或更高版本的Android设备.

• 在Android设备上启用 开发人员选项 和 USB调试 。详细说明可在Android文档 (opens new window)中找到。
• 使用USB将手机插入电脑。如果设备出现调试授权提示，请授权你的电脑可以访问该设备。
• 在命令行运行 flutter devices 命令以验证Flutter识别您连接的Android设备。
• 运行 flutter run 启动应用程序。

默认情况下，Flutter使用的Android SDK版本是基于你的 adb 工具版本。 如果想让Flutter使用不同版本的Android SDK，则必须将该 ANDROID_HOME 环境变量设置为相应的SDK安装目录。

3. 在 macOS 上搭建 Flutter 开发环境

想要安装并运行 Flutter，你的开发环境需要最低满足以下要求：

• 操作系统：macOS。
• 磁盘空间：2.8 GB（不包含 IDE 或其余工具所需要的磁盘空间）。
• 工具：Flutter 使用 git 进行安装和升级，建议你安装包含了 git 的 Xcode，或者也可以单独安装 git。

如果你要在 Apple 芯片的 Mac 电脑上使用，你还需要安装 Rosetta 2 环境，因为一些辅助工具仍然需要，你可以通过手动运行下面的命令来安装：

 sudo softwareupdate --install-rosetta --agree-to-license

3.1 fvm 及 flutter sdk 的安装

我们可以直接使用 homebrew 来安装 fvm ：

brew tap befovy/taps
brew install fvm

如果出现如下图所示情况：

则需要你安装上述第一条命令或者使用 brew update 来升级你的 homebrew

关于 homebrew 的安装，请参考我的第一篇文章：MacBook Pro（M1芯片）配置前端开发环境 —— 安装 Homebrew

当然你也可以上文叙述中那样，直接在 github 手动安装

接下来配置环境变量，输入命令打开 .zshrc 或 bash_profile

open ~/.zshrc 
或 open ~/.bash_profile

在打开的文件中输入:

export FVM_HOME="$HOME/.fvm"

保存并关闭文件并在终端输入如下命令使配置立即生效

source ~/.zshrc
或 source ~/.bash_profile

通过命令fvm --version来查看 fvm 版本

通过 fvm 来安装 flutter 各个版本的操作同上文即可。操作过程遇到的问题解决方式请参考如下两篇文章：

使用Flutter包管理工具fvm过程中遇到的问题

Flutter版本管理器-FVM

如果使用了上述方式之后 fvm 命令还没生效，那么就直接暴力点，直接去官网下载 Flutter SDK。下载后直接双击解压拖到用户目录下面。我比较喜欢用命令来操作，此处以下载了 fllutter2.2.3 版本为例：

cd /Users/xxx
unzip ~/Downloads/flutter_macos_2.2.3-stable.zip

配置环境变量：

export PATH=/Users/xxx/flutter/bin:$PATH
export PATH=/Users/xxx/flutter/bin/cache/dart-sdk/bin:$PATH

用命令flutter --version来看下是否配置成功。

然后通过命令dart pub global activate fvm 来安装 fvm，配置环境变量：

export PATH="$PATH":"$HOME/.pub-cache/bin" 

要记得去掉之前通过 homebrew 安装 fvm 的环境变量，然后通过 fvm 安装几个你需要的 flutter 版本并设置一个当前全局使用的 flutter 版本。这个过程可能会出现你安装了一个新的版本会将前一个版本覆盖的情况，目前还不知道是什么原因，我这边出现了，解决方式就是多安装几次直到那你通过命令 fvm list 查看到你安装的所有的 fluuter 版本。

使用下面命令查看你的 flutter 的安装路径：

which flutter

你会发现你的 flutter 路径还是指向你在官网下载的 flutter 版本放在本地的路径，使用 fvm 全局设置的 flutter 路径并没有被正确指向。这时候需要修改通过官网下载的 flutter 的环境变量：

export PATH=$HOME/fvm/default/bin:$PATH

另外要注意的是当你输入source ~/.zshrc或source ~/.bash_profile后，flutter 路径还是没有正确指向的话，需要你关闭当前的终端再次打开即可。

至此，你就可以通过 fvm 随意切换使用 flutter 版本了。

ps：当你的 fvm 命令可以正常使用后，若是切换全局使用了最新版本或者某个版本，出现如下错误：

那么重新执行命令 dart pub global activate fvm 即可

关于 fvm 的相关命令的使用请参考上面 windows 环境下 fvm 的使用

关于 mac 的 flutter doctor 的可能会遇到的一些坑，请参考解决方案： Flutter doctor(Android)踩坑

3.2 安装 java sdk

我这边安装的是 jdk 11版本，官网下载：

在终端执行以下命令，查看是否安装成功：

/usr/libexec/java_home -V

出现如下图所示版本信息，则说明安装成功了：

将上图圈出来的路径复制一下，配置环境变量：

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

执行查看java版本命令

java -version

至此java sdk安装成功！

3.3 安装ios开发环境

3.3.1 安装 Xcode

开发 iOS 平台上的 Flutter 应用，你需要一个已经安装了 Xcode 的 Mac 设备。

• 通过官网直接下载或者通过Mac App Store来安装最新稳定版 Xcode
• 使用以下命令来配置 Xcode 命令行工具：

 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
 sudo xcodebuild -runFirstLaunch

运行一次 Xcode 或者通过输入命令 sudo xcodebuild -license 来确保已经同意 Xcode 的许可协议。打开 xcode 之后记得选择勾选 ios，这样你就可以在 iOS 真机或者模拟器上运行 Flutter 应用了。

使用命令flutter doctor 发现，我们还要安装 cocoapods

在 flutter 中，cocoapods 是用来管理 Xcode 的项目依赖。使用以下命令来安装：

sudo gem install cocoapods

安装完成后，执行命令 pod --version查看版本信息，确保安装成功。

我这边就显示安装失败了，那么换用如下命令来安装即可：

brew install ideviceinstaller iOS-deploy cocoapods

再次执行 flutter doctor命令：

我们发现关于 flutter 的基本配置都已完成！

3.3.2 配置 ios 模拟器

• 如果你在安装 Xcode 之后没有选择勾选 ios，那么使用以下命令下载并安装 iOS 模拟器：

xcodebuild -downloadPlatform iOS

这个命令会触发 Xcode 从 App Store 或其他源下载 iOS 模拟器所需的组件。

• 在你安装了 ios 模拟器之后，通过 Spotlight 或者以下命令来运行模拟器：

 open -a Simulator

这个命令通过 open 命令启动名为 "Simulator" 的应用程序，这是 Xcode 提供的 iOS 模拟器的正式名称。

模拟器运行起来，你会看到如下图效果：

• 通过模拟器菜单中的 Hardware > Device 或者 File > Open Simulator 选项检查当前模拟器是否是 64 位机型（iPhone 5S 或之后的机型）。

• 根据你当前开发机器的屏幕尺寸，模拟器模拟出来的高密度屏幕的设备可能会溢出你的屏幕，你可以调整模拟器的边角来拖动改变比例，如果你的开发机分辨率很高的话，也可以通过菜单中的 Window > Physical Size or Window > Pixel Accurate 选项来更改模拟器的缩放比例。

ps：如果你使用的 Xcode 版本低于 9.1，调整模拟器比例的菜单选项应该是 Window > Scale。

3.3.3 连接 iOS 真机设备

如果你想把 Flutter 应用部署到 iPhone 或 iPad 上，你还需要一些别的工具和一个 Apple 开发者账号。另外，你还需要在 Xcode 上针对你的机器做一些设置。

• 第一次使用 iPhone 真机，需要同时信任 iOS 和 Mac 上的证书，iOS16 以上设备需要打开开发者模式。
• 手机第一次连接电脑时，请选择信任：

在 iOS 设备上打开“设置”应用，选择“通用” > “设备管理”，然后信任你的证书。对于第一次使用的用户，你可能需要选择“通用” > “描述文件与设备管理”选项。在 iOS 16 及更高版本上，回到“设置”应用的顶层菜单，选择“隐私与安全” > “开发人员模式”，并将“开发人员模式”开启。

3.4 设置 Android 开发环境

关于 Android Studio 及安卓模拟器的安装，同上面 windows 一样配置即可，不再赘述。

4. 项目的创建和启动

4.1 开发工具

flutter 官方推荐的编辑器有 IDEA/Android Studio 和 VSCode。 不过 Android Studio 始终比较重，我这里为了方便，选择 VSCode 作为 flutter 的开发工具。

如果你还没有安装 Visual Studio Code (VS Code)，你需要先从 VS Code 官网 下载并安装。

4.2 插件安装

建议安装以下插件：

• Flutter，主插件

• Dart，Dart语言插件

• Flutter Files，quickly scaffold flutter BLoC templates

• Flutter Color，颜色快捷显示

• ARB Editor，多语言.arb文件，该扩展可增添语法高亮显示、片段、诊断和快速修复功能，以辅助编辑 .arb 模板文件

• Flutter Intl，Flutter国际化插件

• Awesome Flutter Snippets， 快速创建代码块

• Flutter Widget Snippets，快速创建Flutter和Dart代码块（推荐使用这个，记太多Snippet也是一件头疼的事）

主要是前两个插件，后面几个随意。

4.3 新建一个 Flutter 项目

我们打开命令行终端工具（macOS 上是 Terminal 或者 iTerm 等，Windows 上是 Powershell 或者安装的 Terminal 等），运行flutter create xxx 命令，这个脚本会创建一个 Flutter 模板项目，我们后续会在这个基础之上继续开发。

使用 vscode 打开项目，看到如图所示：

先看下目录结构，lib是所有代码存放目录，其他的android ios macos windows linux web是6个原生代码所在的目录，除此之外pubspec.yaml是用来管理 Flutter 项目配置的文件包含了我们开发项目所用的三方库等等。

main.dart 文件中 main函数是我们程序的入口，通过 runApp来启动我们的程序。

接下来，我们来启动刚才新建的 flutter 项目。

在 windows 上，运行 flutter run 命令：

选择 1，win桌面端效果：

可能会出现的报错：

这是因为系统未启用开发者模式，阻止了 Flutter 插件的 symlink 支持。Flutter 插件会通过符号链接的方式与 Flutter 工程连接,所以需要启用开发者模式和符号链接支持。

以 win11 为例，使用快捷键 win + i 调出设置，输入框搜索开发人员模式，打开开关，如图所示：

选择2，可以看win上web效果，但是不如人愿，报错了：

需要我们指定主机名和端口号才能正常运行起来

输入以下命令：

flutter run -d chrome --web-port=8080 --web-hostname=127.0.0.1

在 mac 上，运行 flutter fun 命令：

选择 1，我们要看mac上桌面端效果：

选择 2，mac上 web 效果：

ps：按住r或者R键，进行热更新；按住 q 键，停止运行。

4.4 启动现有项目

接下来，我们要启动一个已经安装大量包的 flutter 项目。

4.4.1 安装包依赖

1. 在项目文件 pubspec.yaml 中点击右上角下载，会自动安装包依赖，这个过程可能会较长

或者通过以下命令来安装：

flutter pub get

安装的过程中可能会出现一些报错：

• Flutter unable find git in your PATH

这个问题是 git 权限问题，首先要确认你已经安装了git，执行以下命令来解决：

git config --global --add safe.directory '*'

• Could not read from remote repository

这个问题是没有远程仓库的权限。查看 pubspec.yaml 文件，发现需要安装 pad-common-lib 的库

这个是我们内部的库，我是有该库项目的gitlab的权限的，真正的问题在于这个库的url写的不是http形式，而是git形式的，而这需要在gitlab里面去配置密钥的。我这几天换了台电脑，账户名称也换了，所以需要在gitlab添加新的key密钥。 关于 git 密钥的配置，请参考我写的第一篇文章：MacBook Pro（M1芯片）配置前端开发环境 ——  使用Homebrew安装git

• 还有可能报一些关于 java 的错误

这要看你的flutter是哪个版本的了，如果是flutter2大概率是你没有安装 jdk 和配置 java 环境；如果是flutter3项目，那可能是你的 Android Studio 安装出了问题，需要 flutter doctor 命令做进一步检查。

2. pad 项目中使用了国际化，需要执行下面两个命令：

flutter pub global activate intl_utils
flutter pub global run intl_utils:generate

3. x86的机器，需要在此处添加x86的范围运行：

4.4.2 运行

在项目中启动调试：

选择上面步骤创建好的 pad 这一项：

第一次启动会是很漫长的过程，可能需要几分钟（如果你安装了本文第一个步骤中所说的 Flutter 官方中国区镜像的环境变量，这个过程相对较快些），当看到如下画面，即启动成功：

该过程中可能会出现的报错：

• Exception in thread "main" java.net.ConnectException: Connection timed out: connect

这是无法下载 gradle 导致的。打开项目文件 gradle-wrapper.properties 找到当前 gradle 版本，如图所示：

解决方式：

（1）用腾讯镜像 mirrors.cloud.tencent.com/gradle/grad… 取代项目中 gradle 下载地址

（2）从官网下载当前版本 gradle 对应的zip文件，修改 distributionUrl 为你所下载的zip文件本地路径，下面给出路径示例：

win地址：
distributionUrl=file:///C:/Users/xxx/Downloads/gradle-7.6-all.zip

mac地址：
distributionUrl=file:///Users/xx/gradle-7.6-all.zip

• Exception in thread "main" java.util.zip.ZipException: zip END header not found

这个是 gradle 版本不对的问题。一般而言，有版本冲突都是降低当前版本来解决问题，但我遇到的这个就反其道而行之，当我将 gradle 版本升至 7.6 的时候就跑起来了！

• Unable to find bundled Java version

这个报错解决方案参考文章：Flutter问题记录 - Unable to find bundled Java version

• Unable to make field private final java.lang.String java.io.File.path accessible

解决方案参考文章：Android问题记录 - Unable to make field private final java.lang.String java.io.File.path accessible（持续更新）

• 项目启动成功，模拟器页面显示正常，但后续可能会出现白屏情况

这时候需要卸载掉模拟器中的关于该项目的app，然后重新启动该项目即可。

ps：本地某个项目用的是 Flutter2.2.3 版本，当我使用命令 fvm global 3.10.2 将 Flutter2.2.3 全局切换成 Flutter 3.10.2 版本的时候，这时候该项目会缓存 Flutter2.2.3 的版本，继续正常使用即可。通过fvm list查看使用情况：

Global 表示你全局使用的 Flutter 版本，Local 表示你本地当前项目使用的 Flutter 版本