flutter-setting-up-on-macos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setting Up a macOS Environment for Flutter Development

为Flutter开发搭建macOS环境

Prerequisites

前提条件

Ensure the following baseline requirements are met before configuring the macOS-specific toolchain:

macOS operating system.
Flutter SDK installed and added to the system
```
PATH
```
.
Active internet connection for downloading toolchains and dependencies.

在配置macOS专属工具链之前，请确保满足以下基础要求：

macOS操作系统。
已安装Flutter SDK并将其添加至系统
```
PATH
```
环境变量。
可用的互联网连接，用于下载工具链及依赖项。

Tooling Configuration

工具配置

macOS desktop development requires specific Apple toolchains to compile and debug native Swift and Objective-C code.

Xcode: Required for compiling macOS desktop applications.
CocoaPods: Required for managing native dependencies used by Flutter plugins.

macOS桌面开发需要特定的Apple工具链来编译和调试原生Swift与Objective-C代码。

Xcode：编译macOS桌面应用程序的必备工具。
CocoaPods：用于管理Flutter插件所使用的原生依赖项的必备工具。

Workflow: Configuring macOS Tooling

工作流：配置macOS工具

Copy and follow this checklist to configure the macOS build environment.

Install Xcode: Install the latest version of Xcode from the Mac App Store or the Apple Developer portal.
Configure Command-Line Tools: Link the Xcode command-line tools to the installed Xcode version. Run the following command in the terminal:
bash
```
sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
```
Conditional: If Xcode is installed in a custom directory, replace
```
/Applications/Xcode.app
```
with the correct absolute path.
Accept Xcode Licenses: Accept the required developer licenses by running:
bash
```
sudo xcodebuild -license
```
Read and agree to the prompts.
Install CocoaPods: Install CocoaPods to handle native macOS plugin dependencies.
bash
```
sudo gem install cocoapods
```
Conditional: If CocoaPods is already installed, ensure it is updated to the latest version (
```
sudo gem update cocoapods
```
).

复制并遵循以下检查清单来配置macOS构建环境。

安装Xcode：从Mac App Store或Apple开发者门户安装最新版本的Xcode。
配置命令行工具：将Xcode命令行工具链接至已安装的Xcode版本。在终端中运行以下命令：
bash
```
sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
```
注意：如果Xcode安装在自定义目录，请将
```
/Applications/Xcode.app
```
替换为正确的绝对路径。
接受Xcode许可证：运行以下命令以接受所需的开发者许可证：
bash
```
sudo xcodebuild -license
```
阅读并同意提示内容。
安装CocoaPods：安装CocoaPods以处理macOS原生插件依赖项。
bash
```
sudo gem install cocoapods
```
注意：如果已安装CocoaPods，请确保将其更新至最新版本（
```
sudo gem update cocoapods
```
）。

Workflow: Validating the Environment

工作流：验证环境

Execute this feedback loop to ensure the environment is correctly configured for macOS desktop development.

Run Validator: Execute the Flutter diagnostic tool with verbose output:
bash
```
flutter doctor -v
```
Review Errors: Check the
```
Xcode
```
section in the output.
Fix & Retry: If errors or missing components are reported under the Xcode section, resolve them according to the output instructions, then re-run
```
flutter doctor -v
```
until the Xcode section passes.
Verify Device Availability: Confirm that Flutter recognizes the macOS desktop as a valid deployment target:
bash
```
flutter devices
```
Success Criteria: The output must contain at least one entry with
```
macos
```
listed as the platform.

执行以下步骤以确保环境已正确配置，可用于macOS桌面开发。

运行验证工具：执行Flutter诊断工具并查看详细输出：
bash
```
flutter doctor -v
```
检查错误：查看输出中的
```
Xcode
```
部分。
修复并重试：如果Xcode部分报告错误或缺少组件，请根据输出说明解决问题，然后重新运行
```
flutter doctor -v
```
直到Xcode部分验证通过。
验证设备可用性：确认Flutter已将macOS桌面识别为有效的部署目标：
bash
```
flutter devices
```
成功标准：输出中必须至少包含一项平台为
```
macos
```
的条目。

Troubleshooting

故障排除

If the validation workflow fails, apply the following resolutions:

Missing Command-Line Tools: If
```
flutter doctor
```
reports missing tools, ensure the
```
xcode-select
```
command was run with
```
sudo
```
and points to the correct
```
.app
```
directory.
CocoaPods Not Found: If CocoaPods is installed but not detected, verify that your Ruby
```
gem
```
binary path is included in your shell's
```
PATH
```
environment variable.
Device Not Listed: If
```
flutter devices
```
does not list
```
macos
```
, ensure desktop support is enabled in your Flutter configuration:
bash
```
flutter config --enable-macos-desktop
```

如果验证工作流失败，请尝试以下解决方法：

缺少命令行工具：如果
```
flutter doctor
```
报告缺少工具，请确保已使用
```
sudo
```
运行
```
xcode-select
```
命令，且路径指向正确的
```
.app
```
目录。
未找到CocoaPods：如果已安装CocoaPods但未被检测到，请确认Ruby的
```
gem
```
二进制路径已包含在shell的
```
PATH
```
环境变量中。
设备未列出：如果
```
flutter devices
```
未列出
```
macos
```
，请确保已在Flutter配置中启用桌面支持：
bash
```
flutter config --enable-macos-desktop
```