Flutter 跨平台开发环境搭建指南

概述

本文档记录了在 macOS 系统上完整搭建 Flutter 跨平台开发环境的过程，支持 iOS、Android、Web、macOS、Linux、Windows 和鸿蒙等多个平台的应用开发。

系统环境

• 操作系统: macOS 15.5 (Darwin Kernel Version 24.5.0)
• 架构: ARM64 (Apple Silicon)
• Shell: Zsh (/bin/zsh)

安装步骤

1. 安装 Homebrew（如果未安装）

# 检查是否已安装 Homebrew
which brew

# 如果未安装，执行以下命令
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装 Dart SDK

# 添加 Dart 官方 tap
brew tap dart-lang/dart

# 安装 Dart
brew install dart

# 验证安装
dart --version

预期输出:

Dart SDK version: 3.9.2 (stable) (Wed Aug 27 03:49:40 2025 -0700) on "macos_arm64"

3. 安装 Flutter SDK

# 安装 Flutter
brew install --cask flutter

# 验证安装
flutter --version

预期输出:

Flutter 3.35.2 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 05db968908 (5 days ago) • 2025-08-25 10:21:35 -0700
Engine • hash abb725c9a5211af2a862b83f74b7eaf2652db083 (revision a8bfdfc394)
Tools • Dart 3.9.0 • DevTools 2.48.0

4. 配置环境变量

# 解决 .zshrc 权限问题（如果遇到）
sudo chown $(whoami):staff ~/.zshrc

# 添加 Flutter 到 PATH
echo 'export PATH="/opt/homebrew/share/flutter/bin:$PATH"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

5. 检查开发环境

# 运行 Flutter 医生检查
flutter doctor

典型输出:

Doctor summary (to see all details run flutter doctor -v):
[✓] Flutter (Channel stable 3.35.2 on macOS 15.5 24F74 darwin-arm64)
[!] Android toolchain - develop for Android devices
[✗] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Android Studio
[✓] IntelliJ IDEA Ultimate Edition
[✓] VS Code
[✓] Connected device (3 available)
[✓] Network resources

6. 查看支持的设备

# 查看可用设备
flutter devices

预期输出:

Found 3 connected devices:
DCO AL00 (mobile) • ARH0223118011127 • android-arm64  • Android 12 (API 31)
macOS (desktop)   • macos            • darwin-arm64   • macOS 15.5 24F74
Chrome (web)      • chrome           • web-javascript • Google Chrome 139.0.7258.155

创建和运行第一个项目

1. 创建新项目

# 创建 Flutter 项目
flutter create hello_flutter

# 进入项目目录
cd hello_flutter

2. 查看项目结构

ls -la

项目结构:

├── android/          # Android 平台代码
├── ios/              # iOS 平台代码
├── web/              # Web 平台代码
├── macos/            # macOS 平台代码
├── linux/            # Linux 平台代码
├── windows/          # Windows 平台代码
├── lib/              # Dart 源代码
├── test/             # 测试代码
├── pubspec.yaml      # 项目配置文件
└── README.md         # 项目说明

3. 运行 Web 应用

# 在 Chrome 中运行
flutter run -d chrome

成功运行后会显示:

Launching lib/main.dart on Chrome in debug mode...
This app is linked to the debug service: ws://127.0.0.1:58229/xxx/ws
Debug service listening on ws://127.0.0.1:58229/xxx/ws

Flutter run key commands:
r Hot reload. 🔥🔥🔥
R Hot restart.
h List all available interactive commands.
d Detach (terminate "flutter run" but leave application running).
c Clear the screen
q Quit (terminate the application on the device).

A Dart VM Service on Chrome is available at: http://127.0.0.1:58229/xxx
The Flutter DevTools debugger and profiler on Chrome is available at: http://127.0.0.1:9100?uri=http://127.0.0.1:58229/xxx

跨平台支持情况

✅ 完全支持的平台

🔧 需要额外配置的平台

Android 开发

# 安装 Android Studio
# 配置 Android SDK
# 接受许可协议
flutter doctor --android-licenses

iOS 开发（仅 macOS）

# 安装 Xcode
# 配置 Xcode 命令行工具
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

# 安装 CocoaPods
sudo gem install cocoapods

常见问题和解决方案

1. 权限问题

问题: zsh: permission denied: /Users/xxx/.zshrc

解决方案:

sudo chown $(whoami):staff ~/.zshrc
chmod 644 ~/.zshrc

2. PATH 配置问题

问题: zsh: command not found: flutter

解决方案:

# 临时设置
export PATH="/opt/homebrew/share/flutter/bin:$PATH"

# 永久设置
echo 'export PATH="/opt/homebrew/share/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. Dart 版本冲突

问题: Flutter 检测到不匹配的 Dart 版本

解决方案:

# 确保 Flutter 的 Dart 版本优先
export PATH="/opt/homebrew/share/flutter/bin:$PATH:/opt/homebrew/bin"

4. Web 运行时的 DebugService 错误

现象: 大量 “DebugService: Error serving requests” 错误

说明: 这是开发模式下的已知问题，不影响应用正常运行。

开发工具推荐

IDE 选择

• VS Code: 轻量级，插件丰富
• Android Studio: 功能完整，Google 官方支持
• IntelliJ IDEA: JetBrains 出品，功能强大

必装插件

• Flutter
• Dart
• Flutter Widget Snippets
• Awesome Flutter Snippets

性能优化建议

1. 开发环境优化

# 启用 Web 渲染器优化
flutter run -d chrome --web-renderer html

# 启用热重载
# 在运行时按 'r' 键进行热重载

2. 构建优化

# Web 生产构建
flutter build web

# Android 生产构建
flutter build apk --release

# iOS 生产构建
flutter build ios --release

总结

通过以上步骤，你已经成功搭建了一个完整的 Flutter 跨平台开发环境，具备以下能力：

1. 一套代码，多端运行: 支持 7+ 个平台
2. 热重载: 快速开发调试
3. 丰富的生态: 大量第三方包支持
4. 原生性能: 接近原生应用的性能表现
5. 统一开发体验: 降低学习和维护成本

下一步学习建议

1. 学习 Dart 语言基础
2. 掌握 Flutter Widget 系统
3. 了解状态管理方案（Provider, Riverpod, Bloc 等）
4. 学习平台特定功能集成
5. 掌握应用发布流程

文档版本: v1.0
更新时间: 2025年8月30日
适用系统: macOS (ARM64)
Flutter 版本: 3.35.2
Dart 版本: 3.9.2