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


System requirements

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

To install and run Flutter, your development environment must meet these minimum requirements:

  • 操作系统:macOS(64 位)

    Operating Systems: macOS (64-bit)

  • 磁盘空间:2.8 GB(不包含 IDE 或其余工具所需要的磁盘空间)

    Disk Space: 2.8 GB (does not include disk space for IDE/tools).

  • 命令工具:Flutter 需要你的开发环境中已经配置了以下命令行工具。

    Tools: Flutter depends on these command-line tools being available in your environment.

    • bash
    • curl
    • git 2.x
    • mkdir
    • rm
    • unzip
    • which
    • zip

获取 Flutter SDK

Get the Flutter SDK

  1. 下载以下安装包来获取最新的 stable Flutter SDK:

    Download the following installation bundle to get the latest stable release of the Flutter SDK:


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

    For other release channels, and older builds, see the SDK archive page.

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

    Extract the file in the desired location, for example:

    $ cd ~/development
    $ unzip ~/Downloads/flutter_macos_vX.X.X-stable.zip

    如果你不想安装固定版本的安装包,你可以跳过步骤 1 和 2。或者是从 GitHub 上的 Flutter repo 获取源代码,并根据需要更改分支或标签。

    If you don’t want to install a fixed version of the installation bundle, you can skip steps 1 and 2. Instead, get the source code from the Flutter repo on GitHub with the following command:

    $ git clone https://github.com/flutter/flutter.git


    You can also change branches or tags as needed. For example, to get just the stable version:

    $ git clone https://github.com/flutter/flutter.git -b stable --depth 1
  3. 配置 flutter 的 PATH 环境变量:

    Add the flutter tool to your path:

    $ export PATH="$PATH:`pwd`/flutter/bin"

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

    This command sets your PATH variable for the current terminal window only. To permanently add Flutter to your path, see Update your path.

  4. 开发二进制文件预下载(可选操作)

    Optionally, pre-download development binaries:

    flutter 命令行工具会下载不同平台的开发二进制文件,如果需要一个封闭式的构建环境,或在网络可用性不稳定的情况下使用等情况,你可能需要通过下面这个命令预先下载 iOS 和 Android 的开发二进制文件:

    The flutter tool downloads platform-specific development binaries as needed. For scenarios where pre-downloading these artifacts is preferable (for example, in hermetic build environments, or with intermittent network availability), iOS and Android binaries can be downloaded ahead of time by running:

    $ flutter precache

    更多使用方式,请使用 flutter help precache 命令查看。

    For additional download options, see flutter help precache.

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

You are now ready to run Flutter commands!

运行 flutter doctor 命令

Run flutter doctor

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

Run the following command to see if there are any dependencies you need to install to complete the setup (for verbose output, add the -v flag):

$ flutter doctor

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

This command checks your environment and displays a report to the terminal window. The Dart SDK is bundled with Flutter; it is not necessary to install Dart separately. Check the output carefully for other software you might need to install or further tasks to perform (shown in bold text).


For example:

[-] Android toolchain - develop for Android devices
    • Android SDK at /Users/obiwan/Library/Android/sdk
    ✗ Android SDK is missing command line tools; download from https://goo.gl/XxQghQ
    • Try re-installing or updating your Android SDK,
      visit https://flutter.dev/setup/#android-setup for detailed instructions.


The following sections describe how to perform these tasks and finish the setup process.

当你安装了任一缺失部分的依赖后,可以再次运行 flutter doctor 命令来确认是否成功安装。

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

更新 PATH 环境变量

Update your path

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

You can update your PATH variable for the current session only at the command line, as shown in Get the Flutter SDK. You’ll probably want to update this variable permanently, so you can run flutter commands in any terminal session.


The steps for modifying this variable permanently for all terminal sessions are machine-specific. Typically you add a line to a file that is executed whenever you open a new window. For example:

  1. 首先决定你想要将 Flutter SDK 放置在哪一个目录内,获取并记录这个目录的路径,你将要在第 3 步中用到它。

    Determine the directory where you placed the Flutter SDK. You will need this in Step 3.

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

    Open (or create) the rc file for your shell. Typing echo $SHELL in your Terminal tells you which shell you’re using. If you’re using Bash, edit $HOME/.bash_profile or $HOME/.bashrc. If you’re using Z shell, edit $HOME/.zshrc. If you’re using a different shell, the file path and filename will be different on your machine.

  3. 在文件中增加下列这行命令,并将其中的 [PATH_TO_FLUTTER_GIT_DIRECTORY] 更改为你第一步获取到的路径:

    Add the following line and change [PATH_TO_FLUTTER_GIT_DIRECTORY] to be the path where you cloned Flutter’s git repo:

    $ export PATH="$PATH:[PATH_TO_FLUTTER_GIT_DIRECTORY]/flutter/bin"
  4. 运行 source $HOME/.bash_profile 来刷新当前命令行窗口。

    Run source $HOME/.<rc file> to refresh the current window, or open a new terminal window to automatically source the file.

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

    Verify that the flutter/bin directory is now in your PATH by running:

    $ echo $PATH

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

    Verify that the flutter command is available by running:

    $ which flutter


Platform setup

macOS 可以允许开发 iOS、Android 和 Web(技术预览版正式发布)三个平台的 Flutter 应用,你可以任选一个平台完成初始配置,以此来搭建并运行起来你的第一个 Flutter 应用。

macOS supports developing Flutter apps in iOS, Android, and the web (technical preview release). Complete at least one of the platform setup steps now, to be able to build and run your first Flutter app.

设置 iOS 开发环境

iOS setup

安装 Xcode

Install Xcode

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

To develop Flutter apps for iOS, you need a Mac with Xcode installed.

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

    Install the latest stable version of Xcode (using web download or the Mac App Store).

  2. 通过在命令行中运行以下命令来配置 Xcode command-line tools:

    Configure the Xcode command-line tools to use the newly-installed version of Xcode by running the following from the command line:

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

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

    This is the correct path for most cases, when you want to use the latest version of Xcode. If you need to use a different version, specify that path instead.

  3. 运行一次 Xcode 或者通过输入命令 sudo xcodebuild -license 来确保已经同意 Xcode 的许可协议。

    Make sure the Xcode license agreement is signed by either opening Xcode once and confirming or running sudo xcodebuild -license from the command line.

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

Versions older than the latest stable version may still work, but are not recommended for Flutter development. Using old versions of Xcode to target bitcode is not supported, and is likely not to work.

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

With Xcode, you’ll be able to run Flutter apps on an iOS device or on the simulator.

配置 iOS 模拟器

Set up the iOS simulator

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

To prepare to run and test your Flutter app on the iOS simulator, follow these steps:

  1. 在你的 Mac 中,通过 Spotlight 或者以下命令来运行模拟器:

    On your Mac, find the Simulator via Spotlight or by using the following command:

    $ open -a Simulator
  2. 通过模拟器菜单中的 Hardware > Device 选项检查当前模拟器是否是 64 位机型(iPhone 5S 或之后的机型)。

    Make sure your simulator is using a 64-bit device (iPhone 5s or later) by checking the settings in the simulator’s Hardware > Device menu.

  3. Depending on your development machine’s screen size, simulated high-screen-density iOS devices might overflow your screen. Grab the corner of the simulator and drag it to change the scale. You can also use the Window > Physical Size or Window > Pixel Accurate options if your computer’s resolution is high enough.

    • If you are using a version of XCode older than 9.1, you should instead set the device scale in the Window > Scale menu.

    根据你当前开发机器的屏幕尺寸,模拟器模拟出来的高密度屏幕的设备可能会占满你的屏幕,你可以通过菜单中的 Window > Scale 选项来更改模拟器的缩放比例。

创建并运行一个简单的 Flutter 应用

Create and run a simple Flutter app

通过以下步骤来创建你的第一个 Flutter 应用并进行测试:

To create your first Flutter app and test your setup, follow these steps:

  1. 通过运行以下命令来创建一个新的 Flutter 应用:

    Create a new Flutter app by running the following from the command line:

    $ flutter create my_app
  2. 上述命令创建了一个 my_app 的目录,包含了 Flutter 初始的应用模版,切换路径到这个目录内:

    A my_app directory is created, containing Flutter’s starter app. Enter this directory:

    $ cd my_app
  3. 确保模拟器已经处于运行状态,输入以下命令来启动应用:

    To launch the app in the Simulator, ensure that the Simulator is running and enter:

    $ flutter run

部署到 iOS 真机上

Deploy to iOS devices

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

To deploy your Flutter app to a physical iOS device you need the third-party CocoaPods dependency manager and an Apple Developer account. You’ll also need to set up physical device deployment in Xcode.

  1. 通过下面的代码安装和设置 CocoaPods:

    Install and set up CocoaPods by running the following commands:

    $ sudo gem install cocoapods
    $ pod setup
  2. 按照下面 Xcode 签名流程来配置你的项目:

    Follow the Xcode signing flow to provision your project:

    1. 通过在命令行中于你当前 Flutter 项目目录下运行 open ios/Runner.xcworkspace 命令来打开默认的 Xcode 工程。

      Open the default Xcode workspace in your project by running open ios/Runner.xcworkspace in a terminal window from your Flutter project directory.

    2. 在运行按钮的下拉列表里选择你想要部署到的设备;

      Select the device you intend to deploy to in the device drop-down menu next to the run button.

    3. 在左侧的导航面板中选择 Runner 项目;

      Select the Runner project in the left navigation panel.

    4. Runner 项目的设置页面,请确保勾选你的开发团队。在不同的 Xcode 版本里,这一部分的操作界面不同:

      In the Runner target settings page, make sure your Development Team is selected. The UI varies depending on your version of Xcode.

      • 在 Xcode 10 版本中,请在这里设置:General > Signing > Team

        For Xcode 10, look under General > Signing > Team.

      • 在 Xcode 11 版本以后,请在这里设置 Signing & Capabilities > Team

        For Xcode 11 and newer, look under Signing & Capabilities > Team.

      Runner 项目的设置页面中,确保 General > Signing > Team 选项下的 Development Team 选中状态。

      • 在开始你的第一个 iOS 项目开发之前,你需要先在 Xcode 中登陆你的 Apple 开发者账号 Xcode account add 任何 Apple ID 都可以进行开发和测试。如果想将应用上架 App Store,你需要加入 Apple Developer Program,你可以在 Choosing a Membership 页面中查看详细的说明。

        To start your first iOS development project, you might need to sign into Xcode with your Apple ID. Xcode account add Development and testing is supported for any Apple ID. Enrolling in the Apple Developer Program is required to distribute your app to the App Store. For details about membership types, see Choosing a Membership.

      • 当你第一次将设备连接到开发机用于开发时,你需要分别在 Mac 和开发机上进行信任设备的操作。当你第一次连接时,会有个弹窗,点击 Trust 即可。

        The first time you use an attached physical device for iOS development, you need to trust both your Mac and the Development Certificate on that device. Select Trust in the dialog prompt when first connecting the iOS device to your Mac.

        Trust Mac

        然后在 iOS 开发机上进入 Settings 应用,选择 General > Device Management 然后信任相应的证书。对于首次打开的用户,请选择 General > Profiles > Device Management

        Then, go to the Settings app on the iOS device, select General > Device Management and trust your Certificate. For first time users, you may need to select General > Profiles > Device Management instead.

      • 如果 Xcode 的自动签名失败了,你可以检查以下项目中 General > Identity > Bundle Identifier 里的值是否是唯一的。

        If automatic signing fails in Xcode, verify that the project’s General > Identity > Bundle Identifier value is unique.

        Check the app's Bundle ID

  3. 执行 flutter run 命令来运行你的应用。

    Start your app by running flutter run.

设置 Android 开发环境

Android setup

安装 Android Studio

Install Android Studio

  1. 下载并安装 Android Studio

    Download and install Android Studio.

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

    Start Android Studio, and go through the ‘Android Studio Setup Wizard’. This installs the latest Android SDK, Android SDK Command-line Tools, and Android SDK Build-Tools, which are required by Flutter when developing for Android.

配置 Android 设备

Set up your Android device

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

To prepare to run and test your Flutter app on an Android device, you need an Android device running Android 4.1 (API level 16) or higher.

  1. 在设备上打开 Developer optionsUSB debugging 选项,你可以在 Android documentation 上查看更详细的方法介绍。

    Enable Developer options and USB debugging on your device. Detailed instructions are available in the Android documentation.

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

    Windows-only: Install the Google USB Driver.

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

    Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device.

  4. 在命令行中,使用 flutter devices 命令来确保 Flutter 能够识别出你所连接的 Android 设备。

    In the terminal, run the flutter devices command to verify that Flutter recognizes your connected Android device. By default, Flutter uses the version of the Android SDK where your adb tool is based. If you want Flutter to use a different installation of the Android SDK, you must set the ANDROID_SDK_ROOT environment variable to that installation directory.

默认情况下,Flutter 会使用当前版本 adb 工具所依赖的 Android SDK 版本,如果你想让 Flutter 使用别的 Android SDK,你可以通过设置 ANDROID_HOME 环境变量来达到这个目的。

By default, Flutter uses the version of the Android SDK where your adb tool is based. If you want Flutter to use a different installation of the Android SDK, you must set the ANDROID_HOME environment variable to that installation directory.

配置 Android 模拟器

Set up the Android emulator

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

To prepare to run and test your Flutter app on the Android emulator, follow these steps:

  1. 激活机器上的 VM acceleration 选项。

    Enable VM acceleration on your machine.

  2. 打开 Android Studio,点击 AVD Manager 按钮,选择 Create Virtual Device…

    Launch Android Studio, click the AVD Manager icon, and select Create Virtual Device…

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

      In older versions of Android Studio, you should instead launch Android Studio > Tools > Android > AVD Manager and select Create Virtual Device. (The Android submenu is only present when inside an Android project.)

    • 如果你以及还没打开某个项目,你可以选择 Configure > AVD Manager 然后选择 Create Virtual Device 选项

      If you do not have a project open, you can choose Configure > AVD Manager and select Create Virtual Device…

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

    Choose a device definition and select Next.

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

    Select one or more system images for the Android versions you want to emulate, and select Next. An x86 or x86_64 image is recommended.

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

    Under Emulated Performance, select Hardware - GLES 2.0 to enable hardware acceleration.

  6. 确保 AVD 选项配置正确,并选择 Finish 选项。

    Verify the AVD configuration is correct, and select Finish.

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

    For details on the above steps, see Managing AVDs.

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

    In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device.

Web 平台设置

Web setup

现在你已经可以通过使用 beta 渠道的 Flutter SDK 构建 Web 应用了。要开始,请通过阅读 这些步骤 完成设置。

Flutter has early support for building web applications using the beta channel of Flutter. To add support for web development, follow these instructions when you’ve completed the setup above.


Next step


Set up your preferred editor.