开始在 macOS 上构建 Flutter iOS 应用
软件要求
#要为 iOS 编写和编译 Flutter 代码,请安装以下软件包。
操作系统
#Flutter 支持在 macOS 12 (Monterey) 或更高版本上开发。本指南假定你的 Mac 默认运行 zsh
shell。
有些 Flutter 组件需要通过 Rosetta 2 来转换适配(详情)。如果你在 Apple silicon (ARM) Mac 上进行开发,请运行以下指令来安装 Rosetta 2。
sudo softwareupdate --install-rosetta --agree-to-license
开发工具
#下载并安装以下软件包。
-
Xcode:调试和编译原生 Swift 或 ObjectiveC 原生代码。 Xcode 安装会包含 Git,用于管理 Flutter 版本和你的源代码。
-
CocoaPods:在原生应用中编译并启用 Flutter 插件。
上述软件的开发商为这些产品提供支持。如果需要排除安装的问题,请查阅该产品的文档。
文本编辑器或集成开发环境 (IDE)
#你可以使用任意文本编辑器或集成开发环境 (IDE),并结合 Flutter 的命令行工具,来使用 Flutter 构建应用程序。
使用带有 Flutter 扩展或插件的 IDE 会提供代码自动补全、语法高亮、widget 编写辅助、调试以及其他功能。
以下是热门的扩展插件:
安装 Flutter SDK
#你可以使用 VS Code Flutter 扩展或自行下载安装 Flutter 压缩包,来安装 Flutter SDK。
使用 VS Code 安装 Flutter
#在使用以下流程来安装 Flutter 前,请确保你已经安装 Visual Studio Code 以及 Flutter extension for VS Code。
根据 VS Code 的提示,安装 Flutter
#-
启动 VS Code。
-
打开 命令面板 (Command Palette),按下快捷键 Command + Shift + P。
-
在 命令面板 (Command Palette) 中输入
flutter
。 -
选择 Flutter: New Project。
-
VS Code 会提示你在计算机上找到 Flutter SDK。
-
如果你已经安装 Flutter SDK,请单击 Locate SDK。
-
如果你没有安装 Flutter SDK, 请单击 Download SDK。
如果你没有按照 开发工具的必要条件 安装 Git ,单击该按钮后会导航至 Flutter 安装页面。
-
-
当提示 Which Flutter template? 的时候,请忽略它。可以按下 Esc。你可以在检查完开发配置后创建初始测试项目。
下载 Flutter SDK
#-
当对话框 Select Folder for Flutter SDK 显示时,选择你想要安装 Flutter 的位置。
VS Code 会打开你默认的位置。你可以选择其他位置。
请考虑
~/development/
这样的位置 -
单击 Clone Flutter。
在下载 Flutter 时,VS Code 会弹出这些通知:
Downloading the Flutter SDK. This may take a few minutes.
Initializing the Flutter SDK. This may take a few minutes.
下载和安装需要一些时间。如果你怀疑下载被挂起,请单击 Cancel 取消下载后,再重新尝试安装。
Flutter 安装成功后,VS Code 会弹出该通知:
Do you want to add the Flutter SDK to PATH so it's accessible in external terminals?
-
单击 Add SDK to PATH。
成功后会显示通知:
The Flutter SDK was added to your PATH
-
VS Code 可能会显示一则 Google Analytics 的通知。
如果你同意,请单击 OK。
-
在所有 Terminal 窗口中启用
flutter
:-
关闭,然后重新打开所有 Terminal 窗口。
-
重新启动 VS Code。
-
下载并安装 Flutter
#从归档列表中下载 Flutter SDK 压缩包,将压缩包移动到你想要的位置,然后解压 SDK,以此来安装 Flutter。
-
下载以下 Flutter SDK 最新 stable 版本的压缩包。
Intel 处理器 Apple Silicon 处理器 (loading...) (loading...) 关于其他发布渠道和旧版本,请查阅 Flutter SDK 归档列表。
Flutter SDK 应该会下载至 macOS 默认下载目录:
~/Downloads/
。 -
创建一个文件夹,用于安装 Flutter。
可以考虑在
~/development/
中创建一个目录。 -
将 Flutter SDK 压缩文件 (zip) 解压到你想要存储的目录中。可以使用以下指令进行解压。
unzip ~/Downloads/flutter_sdk_v1.0.0.zip \ -d ~/development/
完成后,Flutter SDK 应该会位于
~/development/flutter
目录中。
将 Flutter 添加至 PATH
#
要在 terminal 中运行 Flutter 命令,请将 Flutter 添加到 PATH
环境变量中。本指南假定你的 Mac 运行的是最新的默认 shell,zsh
。
Zsh 使用 .zshenv
文件来处理 环境变量。
-
启动你喜欢的文本编辑器。
-
如果
~/.zshenv
文件存在,请在文本编辑器中打开 Zsh 环境变量文件~/.zshenv
。如果不存在,请创建~/.zshenv
。 -
复制以下内容并粘贴到
~/.zshenv
文件内的末尾。bashexport PATH=$HOME/development/flutter/bin:$PATH
-
保存
~/.zshenv
文件。 -
请重新启动所有打开的终端会话窗口,来应用此更改。
如果你使用其他 shell,请查阅 设置 PATH 的教程。
配置 iOS 开发
#安装并配置 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
请尽量使用最新版本的 Xcode。
配置目标 iOS 设备
#通过使用 Xcode,你可以在 iOS 真机设备或模拟器上运行 Flutter 应用。
配置 iOS 模拟器
#请按照以下步骤操作,来准备在 iOS 模拟器上运行和测试 Flutter 应用。
-
请运行以下命令,来安装 iOS 模拟器。
xcodebuild -downloadPlatform iOS
-
请运行以下命令,来启动模拟器:
open -a Simulator
配置目标 iOS 设备
#你需要执行以下操作,将 Flutter 应用程序部署到 iPhone 或 iPad 真机上:
-
创建一个 Apple Developer 账户。
-
在 Xcode 中配置真机设备部署。
-
创建开发配置文件 (Provisioning Profile),并自行签名证书 (Signing Certificate)。
-
如果你的应用程序使用 Flutter 插件,请安装第三方 CocoaPods 依赖管理器。
创建 Apple ID 和 Apple Developer 账户
#你可以暂时跳过这一步。实际上,你在准备向 App Store 发布应用之前,并不需要 Apple Developer 账户。
如果你只需要 测试 部署应用程序,请完成第 1 步后继续下一节。
-
如果你没有 Apple ID,请创建一个。
-
如果你未注册 Apple Developer program,请立即注册。
了解有关会员类型的更多信息,请查阅 选择会员资格。
将 iOS 真机连接到 Mac
#配置你的 iOS 真机连接到 Xcode。
-
将 iOS 设备连接到 Mac 的 USB 端口。
-
首次将 iOS 设备连接到 Mac 时,你的 iOS 设备会显示 信任这台电脑吗? 的对话框。
-
点击 信任。
-
出现提示时,解锁你的 iOS 设备。
在 iOS 16 或更高版本上启用开发者模式
#从 iOS 16 开始,Apple 要求你启用 开发者模式,以防止恶意软件。在部署到 iOS 16 或更高版本的设备之前,请启用开发者模式。
-
点击 设置 > 隐私与安全性 > 开发者模式。
-
将 开发者模式 切换为 打开。
-
点击 重新启动。
-
重新启动 iOS 设备后,解锁 iOS 设备。
-
当出现 打开开发者模式吗? 对话框时,点击 打开。
对话框会提示开发者模式会降低 iOS 设备的安全性。
-
解锁你的 iOS 设备。
启用开发者代码签名证书 (signing certificates)
#在部署到 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 值是否唯一。
启用 Mac 和 iOS 设备之间的信任
#首次连接 iOS 真机时,为你的 Mac 和 iOS 设备上的开发证书启用信任。
当 设备连接到 Mac 时,你应该启用 iOS 对 Mac 的信任。
为 iOS 设备启用开发者证书
#在不同版本的 iOS 中,启用证书的方式也不尽相同。
-
打开 iOS 设备上的 设置。
-
点击 通用 > 设备管理。
-
点击你的证书切换为 启用。
-
打开 iOS 设备上的 设置。
-
点击 通用 > VPN 与设备管理。
-
点击你的证书切换为 启用。
-
打开 iOS 设备上的 设置。
-
点击 通用 > VPN 与设备管理。
-
在 开发者应用 标题下,你需要找到你的证书。
-
点击你的证书。
-
点击 信任 "<certificate>"。
-
显示对话框时,点击 信任。
如果出现 codesign 想要访问密钥... 的提示对话框:
-
输入你的 macOS 密码。
-
点击 始终允许。
在 iOS 设备上设置无线调试(可选)
#请按照以下步骤来使用 Wi-Fi 连接调试设备。
-
将 iOS 设备连接到与 macOS 设备相同的网络。
-
为 iOS 设备设置密码。
-
打开 Xcode。
-
选择 Window > Devices and Simulators。
你还可以使用快捷键:Shift + Cmd + 2
-
选择你的 iOS 设备。
-
选择 Connect via Network。
-
一旦设备名称旁边出现网络图标,请将 iOS 设备从 Mac 拔下。
如果在使用 flutter run
时没有看到设备列表,请延长超时时间。超时默认为 10 秒。要延长超时时间,请将值改为大于 10 的整数。
flutter run --device-timeout 60
安装 CocoaPods
#如果你的应用程序依赖于带有原生 iOS 代码的 Flutter 插件,请安装 CocoaPods。该程序会捆绑 Flutter 和 iOS 代码之间的各种依赖关系。
请运行以下步骤,安装并设置 CocoaPods:
-
按照 CocoaPods 安装指南 安装
cocoapods
。sudo gem install cocoapods
-
启动你喜欢的文本编辑器。
-
在文本编辑器中打开 Zsh 环境变量文件
~/.zshenv
。 -
复制以下内容并粘贴到
~/.zshenv
文件内的末尾。bashexport PATH=$HOME/.gem/bin:$PATH
-
保存
~/.zshenv
文件。 -
请重新启动所有打开的终端会话窗口,来应用此更改。
检查你的开发配置
#运行 Flutter doctor
#flutter doctor
指令将检查 macOS 完整的
Flutter 开发环境的所有组件。
-
打开 Terminal。
-
要检查所有组件的安装情况,请运行以下指令。
flutter doctor
由于你选择为 iOS 进行开发,因此不需要 所有 组件。如果你遵循本指南,该指令会将你设置完成的工具和平台输出 [✓]
。
解决 Flutter doctor 的问题
#当 flutter doctor
指令返回错误时,可能是 Flutter、VS Code、Xcode、连接的设备或者网络资源出错。
如果 flutter doctor
指令返回这些组件中的任何一个错误,请使用 verbose 标志再次运行。
flutter doctor -v
查看输出结果,了解可能需要安装的其他软件或者需要执行的其他任务。
如果你更改了 Flutter SDK 或其他相关组件的配置,请 再次运行 flutter doctor
来检查安装。
开始使用 Flutter 开发 macOS 上的 iOS 应用
#恭喜你。 在安装完成所有必要条件和 Flutter SDK 后,你就可以开始开发适用于 macOS 上的 iOS 的 Flutter 应用了。
如果你要继续学习之旅,请参考以下指南:
管理 Flutter SDK
#想要了解管理 Flutter SDK 安装的更多信息,请查阅以下内容。
除非另有说明,本文档之所提及适用于 Flutter 的最新稳定版本,本页面最后更新时间: 2025-06-10。 查看文档源码 或者 为本页面内容提出建议.