在macOS上构建Flutter iOS应用

本文是基于安装和环境配置 | Flutter 中文文档 - Flutter 中文开发者网站 - Flutter

的实践

在macOS上构建Flutter iOS应用

在安装和运行 Flutter 前，你的 macOS 环境必须满足以下要求：

硬件要求

你的 macOS Flutter 开发环境必须满足以下最低硬件要求。

要求	最低	推荐
CPU 核心数	4	8
内存 (GB)	8	16
显示器分辨率（像素）	WXGA (1366 x 768)	FHD (1920 x 1080)
可用磁盘空间 (GB)	44.0	70.0

软件要求

要为 iOS 编写和编译 Flutter 代码，请安装以下软件包。

但你无需单独安装 Dart，因为 Flutter SDK 包含了完整的 Dart SDK。

在 Mac 默认运行 zsh shell的认知基础上有本指南

安装 Flutter SDK

本次使用 VS Code Flutter 扩展来安装 Flutter SDK。

根据 VS Code 的提示，安装 Flutter

1. 启动 VS Code。

2. 打开 命令面板 (Command Palette)，按下快捷键 Command + Shift + P。

3. 在 命令面板 (Command Palette) 中输入 flutter。

4. 选择 Flutter: New Project。

5. VS Code 会提示你在计算机上找到 Flutter SDK。

   1. 如果你已经安装 Flutter SDK，请单击 Locate SDK。

   2. 如果你没有安装 Flutter SDK, 请单击 Download SDK。

      如果你没有按照 开发工具的必要条件安装 Git ，单击该按钮后会导航至 Flutter 安装页面。

6. 当提示 Which Flutter template? 的时候，请忽略它。可以按下 Esc。你可以在检查完开发配置后创建初始测试项目。

Mac的Git安装

最后使用方法3，因为比较便捷

方法 1：通过 Homebrew 安装 Git（推荐）

如果你已经安装了 Homebrew（macOS 的包管理工具），可以使用它来安装 Git：

1. 打开终端（按下 Command (⌘) + 空格，搜索 终端 Terminal，然后打开）。

2. 输入以下命令安装 Git：

    brew install git

---

方法 2：直接下载安装 Git

如果你没有安装 Homebrew，可以直接下载安装 Git：

1. 访问 Git 官方网站：Git for Mac。

2. 下载 .dmg 安装包，然后双击进行安装。

3. 安装完成后，打开终端并运行：

    git --version

   确保 Git 正确安装。

---

方法 3：使用 Xcode 命令行工具安装 Git

macOS 自带 Git，但默认没有安装。如果你不想安装 Homebrew 或者 Git 官方版本，可以直接运行：

 xcode-select --install

然后按照提示完成安装。

检查 Git 是否正常运行

 git --version

如果输出 Git 版本号，说明安装成功

下载 Flutter SDK

1. 当对话框 Select Folder for Flutter SDK 显示时，选择你想要安装 Flutter 的位置。

   VS Code 会打开你默认的位置。你可以选择其他位置。

   请考虑 ~/development/ 这样的位置

2. 单击 Clone Flutter。

   在下载 Flutter 时，VS Code 会弹出该通知：

    Downloading the Flutter SDK. This may take a few minutes.

   下载需要一些时间。如果你怀疑下载被挂起，请单击 Cancel 取消下载后，再重新尝试安装。

3. Flutter 一旦完成下载， 输出 (Output) 面板就会显示。

    Checking Dart SDK version...
    Downloading Dart SDK from the Flutter engine ...
    Expanding downloaded archive...

   成功后，VS Code 会弹出该通知：

    Initializing the Flutter SDK. This may take a few minutes.

   初始化时，输出 (Output) 面板会显示下面的内容：

    Building flutter tool...
    Running pub upgrade...
    Resolving dependencies...
    Got dependencies.
    Downloading Material fonts...
    Downloading Gradle Wrapper...
    Downloading package sky_engine...
    Downloading flutter_patched_sdk tools...
    Downloading flutter_patched_sdk_product tools...
    Downloading windows-x64 tools...
    Downloading windows-x64/font-subset tools...

   该进程还会运行 flutter doctor -v。此时，请忽略该输出。因为 Flutter Doctor 可能会显示与本次快速启动无关的错误。

   Flutter 安装成功后，VS Code 会弹出该通知：

    Do you want to add the Flutter SDK to PATH so it's accessible
    in external terminals?

4. VS Code 可能会显示一则 Google Analytics 的通知。

   如果你同意，请单击 OK。

5. 在所有 Terminal 窗口中启用 flutter：

   1. 关闭，然后重新打开所有 Terminal 窗口。

   2. 重新启动 VS Code。

以上为制作 iOS 应用 | Flutter 中文文档 - Flutter 中文开发者网站 - Flutter指导内容

实际上，还要把 Flutter 添加到系统的 PATH 环境变量中，这样你就可以在任何地方使用 flutter 命令了

添加环境变量

1. 打开终端

• 按 Command (⌘) + 空格，搜索 终端 (Terminal)，然后回车打开。

2. 编辑环境配置文件

在 Mac 上，默认的 shell 是 zsh（如果你使用的是 Catalina 或更高版本）。你需要将 Flutter 的路径添加到 ~/.zshrc 文件中。

本人配置过程使用zsh版本，确认操作无误

• 使用以下命令编辑该文件：

 nano ~/.zshrc

如果你使用的是 bash（旧版 macOS），那么应该编辑 ~/.bash_profile：

 nano ~/.bash_profile

3. 添加 Flutter 到 PATH

在打开的文件末尾，添加如下内容：

 export PATH="$HOME/flutter/bin:$PATH"

这会把 Flutter 安装目录的 bin 目录添加到你的 PATH 环境变量 中，确保你可以在任何地方运行 flutter 命令。

4. 保存并退出

在 nano 编辑器中，按 Control + O 保存文件，然后按 Enter 确认保存，最后按 Control + X 退出编辑器。

5. 使改动生效

执行以下命令，使改动生效：

 source ~/.zshrc

如果你编辑的是 ~/.bash_profile 文件，使用：

 source ~/.bash_profile

6. 验证是否成功

你可以通过以下命令来检查 Flutter 是否成功添加到 PATH 中：

 flutter doctor

如果看到 Flutter 的安装信息并没有报错，说明配置成功。

安装并配置 Xcode

要为 iOS 开发 Flutter 应用，请安装 Xcode，以便编译为原生字节码。

打开 App Store 并登录。

搜索 Xcode。

点击 获取 (Install)。

Xcode 安装程序占用 6 GB 以上的存储空间。下载可能需要一些时间。

请运行以下命令，来配置命令行工具使用已安装的 Xcode 版本。

 sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

使用以上路径可以获取最新版本的 Xcode。如果你需要使用其他版本，请自行指定该路径。

签署 Xcode 许可证协议。

 sudo xcodebuild -license

问题与解决方式

Clone Flutter失败

问题解决过程

报错

 Failed to clone Flutter: Cloning into 'flutter'...
 error: RPC failed; curl 92 HTTP/2 stream 5 was not closed cleanly: CANCEL (err 8)
 error: 6128 bytes of body are still expected
 fetch-pack: unexpected disconnect while reading sideband packet
 fatal: early EOF
 fatal: fetch-pack: invalid index-pack output

怀疑被墙，采取全局代理后

 Failed to clone Flutter: Cloning into 'flutter'...
 error: RPC failed; curl 92 HTTP/2 stream 5 was not closed cleanly: CANCEL (err 8)
 error: 5566 bytes of body are still expected
 fetch-pack: unexpected disconnect while reading sideband packet
 fatal: early EOF
 fatal: fetch-pack: invalid index-pack output

发现对比来看xxx bytes of body are still expected中的xxx变少，说明是传输问题

因而查阅后更改git配置

 git config --global http.postBuffer 524288000

这将会增加 Git 的上传缓冲区大小，以防下载过程中数据被截断

更改后问题得到解决

其他可能的解决方法

配置 Git 限制传输速度

执行以下命令调整 Git 的 HTTP 设置，以适应慢速或不稳定的网络：

 sh复制编辑git config --global http.lowSpeedLimit 0
 git config --global http.lowSpeedTime 999999

修改 Git 的压缩设置

执行以下命令关闭 Git 的 压缩 设置：

 git config --global core.compression 0

重新克隆 Flutter

 git clone https://github.com/flutter/flutter.git -b stable

还是不行就考虑手动下载安装

Flutter安装后报错

 Downloading Material fonts...                                    1,067ms
 Downloading Gradle Wrapper...                                       93ms
 Downloading package sky_engine...                                  137ms
 Downloading package flutter_gpu...                                  88ms
 Downloading flutter_patched_sdk tools...                           277ms
 Downloading flutter_patched_sdk_product tools...                   174ms
 Downloading darwin-arm64 tools...                                2,919ms
 Downloading libimobiledevice...                                    155ms
 Downloading usbmuxd...                                             135ms
 Downloading libplist...                                            240ms
 Downloading openssl...                                             140ms
 Downloading ios-deploy...                                           88ms
 Downloading darwin-arm64/font-subset tools...                      353ms
 [!] Flutter (Channel stable, 3.27.4, on macOS 15.2 24C101 darwin-arm64, locale zh-Hans-CN)
     • Flutter version 3.27.4 on channel stable at /Users/yolemac1/flutter
     ! The flutter binary is not on your path. Consider adding /Users/yolemac1/flutter/bin to your path.
     ! The dart binary is not on your path. Consider adding /Users/yolemac1/flutter/bin to your path.
     • Upstream repository https://github.com/flutter/flutter.git
     • Framework revision d8a9f9a52e (9 days ago), 2025-01-31 16:07:18 -0500
     • Engine revision 82bd5b7209
     • Dart version 3.6.2
     • DevTools version 2.40.3
     • If those were intentional, you can disregard the above warnings; however it is recommended to use "git" directly to perform update checks and upgrades.
 ​
 [✗] Android toolchain - develop for Android devices
     ✗ Unable to locate Android SDK.
       Install Android Studio from: https://developer.android.com/studio/index.html
       On first launch it will assist you in installing the Android SDK components.
       (or visit https://flutter.dev/to/macos-android-setup for detailed instructions).
       If the Android SDK has been installed to a custom location, please use
       `flutter config --android-sdk` to update to that location.
 ​
 ​
 [✗] Xcode - develop for iOS and macOS
     ✗ Xcode installation is incomplete; a full installation is necessary for iOS and macOS development.
       Download at: https://developer.apple.com/xcode/
       Or install Xcode via the App Store.
       Once installed, run:
         sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
         sudo xcodebuild -runFirstLaunch
     ✗ CocoaPods not installed.
         CocoaPods is a package manager for iOS or macOS platform code.
         Without CocoaPods, plugins will not work on iOS or macOS.
         For more info, see https://flutter.dev/to/platform-plugins
       For installation instructions, see https://guides.cocoapods.org/using/getting-started.html#installation
 ​
 [✗] Chrome - develop for the web (Cannot find Chrome executable at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome)
     ! Cannot find Chrome. Try setting CHROME_EXECUTABLE to a Chrome executable.
 ​
 [!] Android Studio (not installed)
     • Android Studio not found; download from https://developer.android.com/studio/index.html
       (or visit https://flutter.dev/to/macos-android-setup for detailed instructions).
 ​
 [✓] VS Code (version 1.97.0)
     • VS Code at /Users/yolemac1/Downloads/Visual Studio Code.app/Contents
     • Flutter extension version 3.104.0
 ​
 [✓] Connected device (1 available)
     • macOS (desktop) • macos • darwin-arm64 • macOS 15.2 24C101 darwin-arm64
 ​
 [!] Network resources
     ✗ A network error occurred while checking "https://maven.google.com/": Operation timed out
 ​
 ! Doctor found issues in 6 categories.
 exit code 0

查询可知报错：

• Flutter 和 Dart 没有在 PATH 中

即Flutter未添加环境变量

• Android SDK 未安装

• Xcode 未完全安装

• Chrome 未安装

• Android Studio 未安装

• Flutter 在访问 https://maven.google.com/ 时遇到了网络超时问题。