在 macOS 上安装和配置 Flutter 开发环境

系统配置要求

获取 Flutter SDK

运行 flutter doctor 命令

直接从 Github 上（而不是归档）下载

更新 PATH 环境变量

平台配置

设置 iOS 开发环境

安装 Xcode

配置 iOS 模拟器

部署到 iOS 真机

创建 Apple ID 和 Apple Developer 账户

将 iOS 真机连接到 Mac

启用开发者代码签名证书 (signing certificates)

启用 Mac 和 iOS 设备之间的信任

可选的部署步骤

设置 Android 开发环境

安装 Android Studio

配置 Android 设备

配置 Android 模拟器

同意 Android 协议

macOS 安装

其他 macOS 需要的内容

下一步

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

操作系统：macOS，需要 10.14 (Mojave) 以及以上版本的操作系统

磁盘空间：2.8 GB（不包含 IDE 或其余工具所需要的磁盘空间）

工具：Flutter 使用 git 进行安装和升级，我们建议您安装包含了 git 的 Xcode，或者您也可以 单独安装 git。

error 重点提醒:

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

error 重点提醒: 国内的网络环境下可能需要对 Flutter 工具进行一些额外配置，请参考文档 在中国网络环境下使用 Flutter。

下载以下安装包来获取最新的 stable Flutter SDK：

想要获取到其他版本的安装包，请参阅 SDK 版本列表 页面。

tips_and_updates 小提示:

若要确定你的 Mac 是否是使用了 Apple 芯片处理器，请查阅苹果官网的说明页面: 搭载 Apple 芯片的 Mac 电脑。

将文件解压到目标路径, 比如:

配置 flutter 的 PATH 环境变量：

这个命令配置了 PATH 环境变量，且只会在你 当前 命令行窗口中生效。如果想让它永久生效，请查看 更新 PATH 环境变量。

现在你可以愉快地运行 Flutter 的命令行啦！

info 提示:

如果想要升级当前的 Flutter 版本，可以查看 升级 Flutter。

通过运行以下命令来查看当前环境是否需要安装其他的依赖（如果想查看更详细的输出，增加一个 -v 参数即可）：

这个命令会检查你当前的配置环境，并在命令行窗口中生成一份报告。安装 Flutter 会附带安装 Dart SDK，所以不需要再对 Dart 进行单独安装。你需要仔细阅读上述命令生成的报告，看看别漏了一些需要安装的依赖，或者需要之后执行的命令（这个会以 加粗的文本 显示出来）。

比如你可能会看到下面这样的输出：

之后的部分会向你描述如果执行这些命令来完成整体的配置过程。

Once you have installed any missing dependencies, run the flutter doctor command again to verify that you’ve set everything up correctly.

该建议仅适用于高级用例

你也可以不从归档，而是用 Git 直接下载。例如，可以运行下方的命令，以下载稳定分支的 SDK：

更新环境变量，并运行 flutter doctor。这个命令将会告诉你，是否还缺少运行 Flutter 所需要安装的其他依赖项（例如 Android SDK）。

如果你不使用归档，Flutter 将会下载必要的开发二进制文件（如果你使用的归档，那么这些文件已经包含在内了）。你也许会想要提前下载这些开发二进制文件（例如，您可能希望设置系统构建环境，或是您的网络可用性不佳）。那么你可以运行以下命令：

更多额外下载选项，请参阅 flutter help precache。

report_problem 请注意:

Flutter 工具可能会偶尔从 Google 的服务器上下载资源，下载了或使用 Flutter SDK 代表您同意了 Google 服务条款。

举个例子，当开发者们从 GitHub 安装（而不是从预打包的归档文件中安装），为了要执行 flutter 命令，Flutter 工具将会在首次运行时从谷歌服务器下载 Dart SDK。升级 Flutter 时亦会发生 (比如运行 flutter upgrade 命令) 。

flutter 工具使用了 Google Analytics 来对基本使用情况和 崩溃报告 进行匿名的统计。这些数据用来帮助改善 Flutter 工具。

在第一次运行或者任何涉及到 flutter config 的信息都不会进行发送，所以你可以在发送分析数据之前选择禁止分析数据的统计。要禁用这一功能，只需要输入 flutter config --no-analytics 即可，想要查看当前设置使用命令 flutter config。如果你禁用了统计信息发送，这次的禁用行为会被记录发送，其他任何信息，以及未来都不会再有任何数据会被记录。

Dart 工具同样可能会发送使用指标数据和崩溃报告给 Google。控制这些发送的数据，请参考下面的 [dart 命令行][dart tool 参数：

--enable-analytics: 启用匿名分析；

--disable-analytics: 禁用匿名分析。

Google 的隐私权政策 里详细描述了这些服务会如何控制这些数据。

正如 获取 Flutter SDK 一文中所展示你可以在当前命令行会话中更新你的 PATH 环境变量。但你也许想让这个配置永久生效，这样就可以在任意一个命令行会话中使用 flutter 命令了。

以下配置环境变量让其永久生效的方法在不同的机器上有略微的差别。基本上方法都是在某一个文件中增加一句命令，让它在每次新的命令行窗口打开时都执行一遍。比如：

首先决定你想要将 Flutter SDK 下载或者通过 git clone 命令到哪一个目录内，获取并记录这个目录的路径，你将要在第 3 步中用到它。

打开或者创建 shell 的 rc 文件，比如，在 Linux 和 macOS Mojave 或 Mojave 之前的系统里，是默认使用 Bash 的，所以需要修改 $HOME/.bashrc 文件。 macOS Catalina 操作系统默认使用 Z Shell，所以需要修改 $HOME/.zshrc 文件。请知晓，如果你使用不同的 shell，文件目录或文件名可能会有所不同。

在文件中增加下列这行命令，并将其中的 [PATH_OF_FLUTTER_GIT_DIRECTORY] 更改为你第一步获取到的路径：

运行 source $HOME/.bash_profile 来刷新当前命令行窗口。

通过运行以下命令来验证 flutter/bin 文件夹是否已经添加到 PATH 环境变量中：

验证 flutter 命令是否可用，可以执行下面的命令检测：

macOS 系统可以开发支持 iOS、Android、macOS 桌面以及 Web 的 Flutter 应用，你可以任选一个平台完成初始配置，以此来搭建并运行你的第一个 Flutter 应用。

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

通过 直接下载 或者通过 Mac App Store 来安装最新稳定版 Xcode；

配置 Xcode 命令行工具以使用新安装的 Xcode 版本。从命令行中运行以下命令：

当你安装了最新版本的 Xcode，大部分情况下，上面的路径都是一样的。但如果你安装了不同版本的 Xcode，你可能要更改一下上述命令中的路径。

同意 Xcode 的许可协议：

运行一次 Xcode。

在终端输入命令并运行：

旧版本可能也能够正常工作，但是不建议在 Flutter 开发环境中使用。旧版本的 Xcode 不支持定位代码，还可能无法正常工作。

安装了 Xcode 之后，你就可以在 iOS 真机或者模拟器上运行 Flutter 应用了。

如果想要在 iOS 模拟器中运行和测试 Flutter 应用，按照以下步骤即可：

如果使用 Xcode 15 或更高的版本，请运行以下指令下载并安装 iOS 模拟器：

如果你想使用其他方式下载和安装 iOS 模拟器，请查阅 Apple 文档中的安装模拟器 了解更多方案。

运行以下指令启动模拟器：

将模拟器设置使用为 64 位设备（iPhone 5s 或更新的设备）。

通过 Xcode 选择模拟器设备类型。打开 Product > Destination > 选择目标设备。

通过 Simulator app 选择模拟器设备。打开 File > Open Simulator > 选择目标设备。

在模拟器中检查设备版本。打开 Settings app > General > About。

模拟的高分辨率 iOS 设备可能会溢出你的屏幕。如果在 Mac 上出现这种情况，请在 Simulator app 中更改显示大小。

以小尺寸显示模拟器，设置 Window > Physical Size 或者快捷键 Cmd + 1。

以中尺寸显示模拟器，设置 Window > Point Accurate 或者快捷键 Cmd + 2。

以 HD 高清显示模拟器，设置 Window > Pixel Accurate 或者快捷键 Cmd + 3。

模拟器默认为 Fit Screen（适应屏幕）。如果你需要恢复到该尺寸的设置，设置 Window > Fit Screen 或者快捷键 Cmd + 4。

你需要执行以下操作，将 Flutter 应用程序部署到 iPhone 或 iPad 真机上：

创建 Apple Developer 账户。

在 Xcode 中设置真机设备部署。

创建开发配置文件 (Provisioning Profile)，并自行签署证书 (Signing Certificate)。

如果你的应用程序使用 Flutter 插件，请安装第三方 CocoaPods 依赖管理器。

测试部署到 iOS 真机，你需要一个 Apple ID。

要在 App Store 发布你的应用程序，你必须注册 Apple Developer Program。

如果你只需要测试部署应用程序，请完成第 1 步后继续下一节。

如果你没有 Apple ID，请创建一个。

如果你未注册 Apple Developer program，请立即注册。

了解有关会员类型的更多信息，请查阅 选择会员资格。

配置你的 iOS 真机连接到 Xcode。

将 iOS 设备连接到 Mac 的 USB 端口。

首次将 iOS 设备连接到 Mac 时，你的 iOS 设备会显示 信任这台电脑吗？ 的对话框。

点击 信任。

出现提示时，解锁你的 iOS 设备。

从 iOS 16 开始，Apple 要求你启用 开发者模式，以防止恶意软件。在部署到 iOS 16 或更高版本的设备之前，请启用开发者模式。

点击 设置 > 隐私与安全性 > 开发者模式。

将 开发者模式 切换为 打开。

点击 重新启动。

重新启动 iOS 设备后，解锁 iOS 设备。

当出现 打开开发者模式吗？ 对话框时，点击 打开。

对话框会提示开发者模式会降低 iOS 设备的安全性。

解锁你的 iOS 设备。

在部署到 iOS 真机前，你需要在 Mac 与 iOS 设备之间建立信任。这需要将签名的开发者证书加载到 iOS 设备上。在 Xcode 中签署应用程序，你需要创建一个开发者配置文件 (Provisioning Profile)。

请按照 Xcode 签名流程配置你的项目。

打开 Xcode。

使用 Apple ID 登录 Xcode。

选择 Xcode > *Settings…

点击 Accounts。

点击 +。

选择 Apple ID 并点击 Continue。

出现提示时，请输入你的 Apple ID 和 Password。

关闭 Settings 对话框。

开发和测试支持任意 Apple ID。

打开 File > Open…

你还可以使用快捷键 Cmd + O。

导航至 Flutter 项目目录。

打开项目中默认的 Xcode workspace：ios/Runner.xcworkspace。

在运行按钮右侧的设备下拉菜单中选择你要部署的 iOS 真机。

它应该出现在 iOS devices 标题下方。

在左侧导航面板的 Targets 下，选择 Runner。

在 Runner 设置窗内，点击 Signing & Capabilities。

选择顶部的 All。

选择 Automatically manage signing。

从 Team 下拉菜单中选择一个团队。

团队是在 Apple Developer Account 页面的 App Store Connect 创建的。如果你尚未创建团队，可以选择 个人团队 (personal team)。

Team 下拉菜单中会显示名为 你的名称 (Personal Team) 的选项。

选择团队后，Xcode 会执行以下工作。

创建并下载开发证书

将设备注册到你的账户

根据需要创建并下载配置文件 (Provisioning Profile)

如果在 Xcode 中自动签名失败，请检查项目的 General > Identity > Bundle Identifier 值是否唯一。

首次连接 iOS 真机时，为你的 Mac 和 iOS 设备上的开发证书启用信任。

将你的设备连接到 Mac 时，需要 启用 iOS 设备对 Mac 的信任。

在不同版本的 iOS 中，启用证书的方式也不尽相同。

打开 iOS 设备上的 设置。

点击 通用 > 设备管理。

点击你的证书切换为 启用。

打开 iOS 设备上的 设置。

点击 通用 > VPN 与设备管理。

点击你的证书切换为 启用。

打开 iOS 设备上的 设置。

点击 通用 > VPN 与设备管理。

在 开发者应用 标题下，你需要找到你的证书。

点击你的证书。

点击 信任 ““。

显示对话框时，点击 信任。

如果出现提示，请在 codesign 想要访问密钥… 的对话框中输入 Mac 密码，然后点击 始终允许。

你可以跳过这些步骤。它们可以启用更多调试功能。

按照以下步骤使用 Wi-Fi 连接调试设备。

使用无线调试：

将 iOS 设备连接到与 macOS 设备相同的网络。

为 iOS 设备设置密码。

将 iOS 设备连接到 Mac 后：

打开 Xcode。

选择 Window > Devices and Simulators。

你还可以使用快捷键 Shift + Cmd + 2。

选择你的 iOS 设备。

选择 Connect via Network。

一旦设备名称旁边出现网络图标，请将 iOS 设备从 Mac 拔下。

如果在使用 flutter run 时没有看到设备列表，请延长超时时间。超时默认为 10 秒。要延长超时时间，请将值改为大于 10 的整数。

了解更多信息，请查阅 Apple 文档中的 pairing a wireless device with Xcode。

要排除故障，请访问 Apple’s Developer Forums。

要了解如何使用 flutter attach 配置无线调试，请查阅 在混合开发模式下进行调试。

如果你的应用程序依赖于带有原生 iOS 代码的 Flutter 插件，请遵循此步骤。

请运行以下指令，安装并设置 CocoaPods：

info 提示:

Ruby 的默认版本需要 root 权限 sudo 来安装 CocoaPods gem，如果你使用的是 Ruby Version 管理器，可能就无需 root 权限。

除此之外，如果你是在 Apple 芯片的 Mac 上安装，则需要运行下面的命令：

info 提示:

Flutter 依赖 Android Studio 的全量安装来为其提供 Android 平台的支持。但你也可以使用其他的编辑器来写 Flutter 应用，接下来的步骤会提到这个问题。

help Help

下载并安装 Android Studio。

运行 Android Studio，并进入 ‘Android Studio Setup Wizard’，这会安装最新的 Android SDK， Android SDK Platform-Tools 以及 Android SDK Build-Tools，这些都是在开发 Android Flutter 应用时所需要的。

运行 flutter doctor 确保 Flutter 已经定位到了你的 Android Studio 的安装位置。如果 Flutter 并未定位到，运行 flutter config --android-studio-dir 设置你的 Android Studio 的安装目录。

help Help

在 Android 设备上运行或测试 Flutter 应用之前，你需要一个运行 Android 4.1（API 版本 16）或者更高的设备。

在设备上打开 Developer options 和 USB debugging 选项，你可以在 Android documentation 上查看更详细的方法介绍。

[可选] 要使用无线调试，启用设备上的 Wireless debugging。详细的操作步骤在 Android 文档 里有。

如果是在 Windows 平台上使用，需要安装 Google USB Driver

通过 USB 接口连接手机和电脑，如果在设备上弹出需要授权弹窗，允许授权以便让电脑能够访问你的开发设备。

在终端中，运行 flutter devices 命令来确认 Flutter 是否识别到你连接的 Android 设备。默认情况下，Flutter 会使用你的 adb 工具所在的 Android SDK 版本。如果你希望 Flutter 使用不同的 Android SDK 安装版本，你必须设置 ANDROID_SDK_ROOT 环境变量到那个安装目录。

help Help

根据以下步骤来将 Flutter 应用运行或测试于你的 Android 模拟器上：

激活机器上的 VM acceleration 选项。

打开 Android Studio，点击 Device Manager 按钮，在 Virtual 这个标签页下选择 Create Device

在一些旧的 Android Studio 版本里，需要通过 Android Studio > Tools > Android > AVD Manager，然后选择 Create Virtual Device… 选项。（只有在 Android 项目中才会显示 Android 子选项。）

如果你以及还没打开某个项目，你可以选择 3-Dot Menu / More Actions > Virtual Device Manager 然后选择 Create Device 选项

选择相应的设备并选择 Next 选项。

选择一个或多个你想要模拟的 Android 版本的系统镜像，然后选择 Next 选项。推荐选择 x86 或者 x86_64 镜像。

在 Emulated Performance 下选择 Hardware - GLES 2.0 选项来开启 硬件加速。

确保 AVD 选项配置正确，并选择 Finish 选项。

想要查看上述步骤的更多详细信息，请查看 Managing AVDs 页面。

在 Android Virtual Device Manager 中，点击工具栏中的 Run 选项，模拟器会启动并为你所选择的系统版本和设备显示出相应的界面。

help Help

在使用 Flutter 前，你必须同意 Android SDK 平台的协议。你可以在安装完上述工具后执行这一步。

打开一个已经提升管理员权限的终端窗口，运行以下命令进行协议的确认。

仔细阅读每条协议后同意。

当你同意所有协议后，再次运行 flutter doctor 以确认是否已经可以正常使用 Flutter。

对于开发 macOS 桌面端应用来说，除了 Flutter SDK 以外你还需要以下内容：

CocoaPods 如果你需要使用插件

编辑器设置。