内容
description bug_report

在 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 代码，请安装以下软件包。

操作系统

Flutter 支持 macOS 10.15（Catalina）或更高版本。本指南假定你的 Mac 将 zsh 作为默认 shell 运行。

要验证你的 shell 配置，请展开本部分

与大多数类 UNIX 操作系统一样，macOS 可以支持多个 shell，例如 bash、zsh 和 sh。从 macOS Catalina（macOS 10.15）的 2019 年 10 月发布开始，Zsh 或 zsh 是 macOS 的默认 shell。

检查并设置 zsh 为默认值

  1. 要验证 zsh 是否已设置为默认 macOS shell，请运行 目录服务命令行实用程序。

     $ dscl . -read ~/ UserShell

    应打印以下内容作为其响应。

     UserShell: /bin/zsh

    您可以跳过剩余的步骤。

  2. 如果您需要安装 zsh，请按照 此 Wiki 中的过程操作。

  3. 如果您需要将默认 shell 更改为 zsh，请运行 chsh 命令。

     $ chsh -s `which zsh`

要详细了解 macOS 和 zsh，请查看 macOS 文档中的 在 Mac 上使用 zsh 作为默认 shell。

某些 Flutter 组件需要在运行 Apple 芯片 的 Mac 上进行 Rosetta 2 转换过程。要在 Apple 芯片上运行所有 Flutter 组件，请安装 Rosetta 2。

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

开发工具

下载并安装以下软件包。

  • Xcode 15 用于调试和编译本机 Swift 或 ObjectiveC 代码。Xcode 安装包括 Git 2.27 或更高版本，用于管理源代码。
  • CocoaPods 1.13 用于编译在您的本机应用中启用 Flutter 插件。

上述软件的开发者为这些产品提供支持。要解决安装问题，请查阅该产品的文档。

当您运行当前版本的 flutter doctor 时，它可能会列出这些软件包中某个软件包的不同版本。如果出现这种情况，请安装它推荐的版本。

文本编辑器或集成开发环境

您可以使用任何文本编辑器或集成开发环境 (IDE) 结合 Flutter 的命令行工具来构建应用。

使用带有 Flutter 扩展或插件的 IDE 可提供代码补全、语法高亮显示、小部件编辑辅助、调试和其他功能。

热门选项包括

安装 Flutter SDK

要安装 Flutter SDK，可以使用 VS Code Flutter 扩展或者自行下载并安装 Flutter 捆绑包。

使用 VS Code 安装 Flutter

要使用这些说明安装 Flutter，请验证你是否已安装 Visual Studio Code 1.77 或更高版本，以及 适用于 VS Code 的 Flutter 扩展。

提示 VS Code 安装 Flutter

  1. 启动 VS Code。

  2. 要打开命令面板，请按 Command + Shift + P。

  3. 在命令面板中，键入 flutter。

  4. 选择Flutter: 新建项目。

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

    1. 如果你已安装 Flutter SDK，请单击找到 SDK。

    2. 如果你尚未安装 Flutter SDK，请单击下载 SDK。

      如果你未按照 开发工具先决条件 中的说明安装 Git，此选项会将你发送到 Flutter 安装页面。

  6. 当提示哪个 Flutter 模板？时，请忽略它。按 Esc。在检查你的开发设置后，你可以创建一个测试项目。

下载 Flutter SDK

  1. 当为 Flutter SDK 选择文件夹对话框显示时，选择你希望安装 Flutter 的位置。

    VS Code 会将你置于你的用户个人资料中以开始。选择其他位置。

    考虑 ~/development/

  2. 单击克隆 Flutter。

    在下载 Flutter 时，VS Code 会显示此弹出通知

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

    此下载需要几分钟。如果你怀疑下载已挂起，请单击取消，然后重新开始安装。

  3. 下载完 Flutter 后，输出面板会显示。

    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.

    初始化时，输出面板会显示以下内容

    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 通知。

    如果您同意，请单击确定。

  5. 要在所有终端窗口中启用 flutter

    1. 关闭所有终端窗口，然后重新打开。
    2. 重新启动 VS Code。

下载并安装 Flutter

要安装 Flutter，请从其存档下载 Flutter SDK 捆绑包，将捆绑包移动到您希望存储的位置，然后解压 SDK。

  1. 下载以下安装捆绑包以获取 Flutter SDK 的最新稳定版本。

    英特尔处理器   Apple 芯片
    (正在加载…)   (正在加载…)

    对于其他发布渠道和较旧版本，请查看 SDK 存档。

    Flutter SDK 应下载到 macOS 默认下载目录：~/Downloads/。

  2. 创建一个可以安装 Flutter 的文件夹。

    考虑在 ~/development/ 创建一个目录。

  3. 将 zip 文件解压到您希望存储 Flutter SDK 的目录中。

    $ unzip ~/Downloads/flutter_sdk_v1.0.0.zip -d ~/development/

    完成后，Flutter SDK 应位于 ~/development/flutter 目录中。

将 Flutter 添加到您的 PATH

要在终端中运行 Flutter 命令，请将 Flutter 添加到 PATH 环境变量。本指南假设您的 Mac 运行最新的默认 shell zsh。Zsh 使用 .zshenv 文件作为 环境变量。

  1. 启动您首选的文本编辑器。

  2. 如果存在，请在文本编辑器中打开 Zsh 环境变量文件 ~/.zshenv。如果不存在，请创建 ~/.zshenv。

  3. 复制以下行并将其粘贴到 ~/.zshenv 文件末尾。

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

  4. 保存您的 ~/.zshenv 文件。

  5. 要应用此更改，请重新启动所有打开的终端会话。

如果您使用其他 shell，请查看此教程，了解如何设置 PATH。

配置 iOS 开发

配置 Xcode

要开发适用于 iOS 的 Flutter 应用，请安装 Xcode 以编译为本机字节码。

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

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

    要使用最新版本的 Xcode，请使用此路径。如果您需要使用其他版本，请指定该路径。

  2. 签署 Xcode 许可协议。

     $ sudo xcodebuild -license

尽量使用当前版本的 Xcode。

配置目标 iOS 设备

使用 Xcode，您可以在 iOS 设备或模拟器上运行 Flutter 应用。

配置 iOS 模拟器

要准备在 iOS 模拟器上运行和测试 Flutter 应用，请按照此步骤操作。

  1. 要安装 iOS 模拟器，请运行以下命令。

     $ xcodebuild -downloadPlatform iOS

  2. 要启动模拟器，请运行以下命令

     $ open -a Simulator

  3. 将模拟器设置为使用 64 位设备。这涵盖了 iPhone 5s 或更高版本。

    • 从Xcode中，选择一个模拟器设备类型。

      1. 转到窗口>设备和模拟器。

        您还可以按Cmd + Shift + 2。

      2. 设备和模拟器对话框打开后，单击模拟器。

      3. 从左侧列表中选择一个模拟器或按+创建新的模拟器。

    • 从模拟器应用中，转到文件>打开模拟器>选择目标 iOS 设备。

    • 要在模拟器中查看设备版本，请打开设置应用>通用>关于。

  4. 模拟的高屏幕密度 iOS 设备可能会超出屏幕范围。如果在 Mac 上确实如此，请在模拟器应用中更改显示大小。

    显示大小 菜单命令 键盘快捷键
    小 窗口>物理大小 Cmd + 1
    中等 窗口>点精确 Cmd + 2
    高清准确 窗口 > 像素准确 Cmd + 3
    适合屏幕 窗口 > 适合屏幕 Cmd + 4

设置目标物理 iOS 设备

要将 Flutter 应用部署到物理 iPhone 或 iPad，您需要执行以下操作

  • 创建一个 Apple Developer 帐户。
  • 在 Xcode 中设置物理设备部署。
  • 创建开发供应配置文件以自签名证书。
  • 如果您的应用使用 Flutter 插件，请安装第三方 CocoaPods 依赖项管理器。
创建您的 Apple ID 和 Apple Developer 帐户

要测试部署到物理 iOS 设备，您需要一个 Apple ID。

要将您的应用分发到 App Store，您必须注册 Apple Developer Program。

如果您只需要测试部署您的应用，请完成第一步并继续进行下一部分。

  1. 如果您没有 Apple ID，请创建一个。

  2. 如果您尚未注册 Apple Developer 计划，请立即注册。

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

将您的物理 iOS 设备连接到您的 Mac

配置您的物理 iOS 设备以连接到 Xcode。

  1. 将您的 iOS 设备连接到 Mac 上的 USB 端口。

  2. 在首次将 iOS 设备连接到 Mac 时，您的 iOS 设备会显示信任此电脑？对话框。

  3. 单击信任。

    Trust Mac

  4. 出现提示时，解锁您的 iOS 设备。

在 iOS 16 或更高版本上启用开发者模式

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

  1. 轻触设置 > 隐私和安全性 > 开发者模式。

  2. 轻触以将开发者模式切换为开启。

  3. 轻触重启。

  4. iOS 设备重启后，解锁您的 iOS 设备。

  5. 当启用开发者模式？对话框出现时，轻触启用。

    该对话框解释说开发者模式需要降低 iOS 设备的安全性。

  6. 解锁您的 iOS 设备。

启用开发者代码签名证书

要在物理 iOS 设备上部署，您需要与您的 Mac 和 iOS 设备建立信任。这要求您将已签名的开发者证书加载到您的 iOS 设备。要在 Xcode 中签名应用程序，您需要创建一个开发供应配置文件。

按照 Xcode 签名流程为您的项目配置供应。

  1. 打开 Xcode。

  2. 使用您的 Apple ID 登录 Xcode。

    1. 转到Xcode > *设置…
    2. 单击帐户。单击+。选择Apple ID，然后单击继续。当提示时，输入您的Apple ID和密码。关闭设置对话框。开发和测试支持任何 Apple ID。

  3. 转到文件 > 打开…

    您还可以按 Cmd + O。

  4. 导航到您的 Flutter 项目目录。

  5. 在您的项目中打开默认的 Xcode 工作空间：ios/Runner.xcworkspace。

  6. 在运行按钮右侧的下拉菜单中选择您打算部署到的物理 iOS 设备。

    它应显示在iOS 设备标题下。

  7. 在目标下的左侧导航面板中，选择Runner。

  8. 在Runner设置窗格中，单击签名和功能。

  9. 在顶部选择全部。

  10. 选择自动管理签名。

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

    团队在您的Apple 开发者帐户页面的App Store Connect部分中创建。如果您尚未创建团队，则可以选择个人团队。

    团队下拉菜单将该选项显示为您的姓名（个人团队）。

    Xcode account add

    在您选择一个团队后，Xcode 将执行以下任务

    1. 创建并下载开发证书
    2. 将您的设备注册到您的帐户，
    3. 在需要时创建并下载供应配置文件如果 Xcode 中的自动签名失败，请验证项目的常规 > 身份 > 包标识符值是唯一的。

Check the app's Bundle ID

启用对 Mac 和 iOS 设备的信任

当您首次连接物理 iOS 设备时，请为 Mac 和 iOS 设备上的开发证书启用信任。

当您将设备连接到 Mac时，您应该在 iOS 设备上启用对 Mac 的信任。

为您的 iOS 设备启用开发者证书

启用证书因 iOS 版本的不同而异。

  1. 在 iOS 设备上打开设置应用。

  2. 依次轻点通用>描述文件和设备管理。

  3. 轻点以将证书切换为启用

  1. 在 iOS 设备上打开设置应用。

  2. 依次轻点通用>VPN 和设备管理。

  3. 轻点以将证书切换为启用。

  1. 在 iOS 设备上打开设置应用。

  2. 依次轻点通用>VPN 和设备管理。

  3. 您应该在开发者应用标题下找到您的证书。

  4. 轻点您的证书。

  5. 轻点信任“<certificate>“。

  6. 当对话框显示时，轻点信任。

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

在您的 iOS 设备上设置无线调试（可选）

要使用 Wi-Fi 连接调试您的设备，请按照此过程操作。

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

  2. 为您的 iOS 设备设置密码。

  3. 打开Xcode。

  4. 转到窗口>设备和模拟器。

    您还可以按 Shift + Cmd + 2。

  5. 选择您的 iOS 设备。

  6. 选择通过网络连接。

  7. 当设备名称旁边出现网络图标时，从 Mac 上拔下您的 iOS 设备。

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

$ flutter run --device-timeout 60

安装 CocoaPods

如果您的应用依赖于带有原生 iOS 代码的Flutter 插件，请安装CocoaPods。此程序捆绑了 Flutter 和 iOS 代码中的各种依赖项。

要安装和设置 CocoaPods，请运行以下命令

  1. 按照 CocoaPods 安装指南 安装 cocoapods。

    $ sudo gem install cocoapods

  2. 启动您首选的文本编辑器。

  3. 在文本编辑器中打开 Zsh 环境变量文件 ~/.zshenv。

  4. 复制以下行并将其粘贴到 ~/.zshenv 文件末尾。

    export PATH=$HOME/.gem/bin:$PATH

  5. 保存您的 ~/.zshenv 文件。

  6. 要应用此更改，请重新启动所有打开的终端会话。

检查你的开发设置

help 帮助

运行 Flutter doctor

flutter doctor 命令会验证 macOS 的完整 Flutter 开发环境的所有组件。

  1. 打开你的终端。

  2. 要验证你对所有组件的安装，请运行以下命令。

    $ flutter doctor

由于你选择为 iOS 开发，因此你不需要所有组件。如果你按照本指南进行操作，你的命令结果应类似于

Running flutter doctor...
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.19.3, on macOS 14.4.0 23E214 darwin-arm64, locale en)
[!] Android toolchain - develop for Android devices
[!] Chrome - develop for the web
[✓] Xcode - develop for iOS and macOS (Xcode 15)
[!] Android Studio (not installed)
[✓] VS Code (version 1.86)
[✓] Connected device (1 available)
[✓] Network resources


! Doctor found issues in 3 categories.

解决 Flutter doctor 问题

当 flutter doctor 命令返回错误时，可能是由于 Flutter、VS Code、Xcode、连接的设备或网络资源。

如果 flutter doctor 命令返回任何这些组件的错误，请使用详细标志再次运行它。

$ flutter doctor -v

检查输出以了解你可能需要安装的其他软件或要执行的其他任务。

如果你更改了 Flutter SDK 或其相关组件的配置，请再次运行 flutter doctor 以验证安装。

使用 Flutter 开始在 macOS 上开发 iOS 应用

恭喜！现在你已经安装了所有先决条件和 Flutter SDK，你应该能够开始在 macOS 上为 iOS 开发 Flutter 应用了。

管理你的 Flutter SDK

要了解有关管理 Flutter SDK 安装的更多信息，请参阅以下资源。