环境安装

本页介绍如何在你的系统上搭建 Flutter 开发环境，提供两种方案：

方案	适用场景	目标平台
方案一：Flutter 官方版	通用开发，Android / iOS / Web / 桌面	Android、iOS、Web、Windows、macOS、Linux
方案二：Flutter-Ohos 鸿蒙定制版	需要适配鸿蒙（HarmonyOS NEXT）平台	Android、iOS、Web、HarmonyOS NEXT

如何选择？

如果你只需要开发 Android / iOS / Web / 桌面应用，选择 方案一 即可。
如果你需要同时支持鸿蒙平台，或专门为鸿蒙设备开发应用，选择 方案二。
两种方案可以在同一台机器上共存，但 不能同时使用同一个 Flutter SDK 目录。

通用前置条件

无论选择哪种方案，你都需要先完成以下准备：

系统要求

平台	最低要求
Windows	Windows 10+ (64-bit)，磁盘 2.8 GB+
macOS	macOS 10.15+，磁盘 2.8 GB+
Linux	64-bit 发行版，磁盘 2.8 GB+

安装 Git

Flutter SDK 通过 Git 获取，请确保已安装 Git：

bash

# 检查是否已安装
git --version

如未安装，访问 git-scm.com 下载安装。

安装 IDE

推荐使用 VS Code 或 Android Studio，两者都需要安装 Flutter 和 Dart 插件：

IDE	必装插件
VS Code	`Flutter`（会自动安装 Dart 插件）
Android Studio	`Flutter` 和 `Dart`（通过 Plugins 设置安装）

方案一：Flutter 官方版环境搭建

1. 下载 Flutter SDK

从 Flutter 官网下载最新稳定版 SDK（当前稳定版为 Flutter 3.41.x）：

平台	下载地址
Windows	flutter_windows_xxx-stable.zip
macOS	flutter_macos_xxx-stable.zip
Linux	flutter_linux_xxx-stable.tar.xz

中国大陆镜像加速

如果下载缓慢，可使用清华镜像：https://mirrors.tuna.tsinghua.edu.cn/flutter/flutter_infra/releases/stable/

2. 解压 SDK

将下载的压缩包解压到你想要的安装目录（路径中不要包含中文或空格）：

bash

# macOS / Linux 示例
cd ~/development
unzip ~/Downloads/flutter_macos_3.41.0-stable.zip

# Windows 示例
# 将压缩包解压到 C:\src\flutter（不要放在 C:\Program Files\ 下）

3. 配置环境变量

将 Flutter 的 bin 目录添加到系统 PATH：

bash

# Linux / macOS — 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$PATH:$HOME/development/flutter/bin"
# 保存后执行
source ~/.bashrc   # 或 source ~/.zshrc

# Windows — 通过「系统属性 → 高级 → 环境变量 → Path → 编辑 → 新建」
# 添加：C:\src\flutter\bin

4. 配置国内镜像源（中国大陆用户必做）

Flutter 的 Pub 包管理器和 SDK 资源下载依赖 Google 服务器，在国内需要配置镜像：

bash

# 添加到 ~/.bashrc 或 ~/.zshrc（Linux / macOS）
# 添加到系统环境变量（Windows）

# 腾讯云镜像（推荐）
export PUB_HOSTED_URL=https://mirrors.cloud.tencent.com/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.cloud.tencent.com/flutter

# 或者使用 Flutter 中国镜像
# export PUB_HOSTED_URL=https://pub.flutter-io.cn
# export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

保存后执行 source ~/.bashrc（或重启终端）使配置生效。

5. 安装 Android SDK

Flutter 开发 Android 应用需要 Android SDK，有两种方式获取：

方式 A：通过 Android Studio 安装（推荐）

下载安装 Android Studio
打开 Android Studio → More Actions → SDK Manager
安装 Android SDK（API 35+）、Android SDK Command-line Tools、Android SDK Build-Tools

方式 B：仅安装命令行工具

bash

# 下载 Android Command Line Tools
# https://developer.android.com/studio#command-line-tools-only

# 解压后安装必要组件
sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"

配置 Android SDK 环境变量：

bash

# Linux / macOS
export ANDROID_HOME=$HOME/Android/Sdk    # 或你的实际安装路径
export PATH="$PATH:$ANDROID_HOME/platform-tools"

# Windows
# ANDROID_HOME = C:\Users\你的用户名\AppData\Local\Android\Sdk

6. 接受 Android 许可证

bash

flutter doctor --android-licenses

按提示逐一输入 y 接受。

7. 运行 flutter doctor 检查环境

bash

flutter doctor

正常输出类似：

[✓] Flutter (Channel stable, 3.41.x)
[✓] Android toolchain (develop for Android devices)
[✓] Xcode (develop for iOS devices)       // 仅 macOS
[✓] Chrome (develop for the web)
[✓] VS Code
[!] Android Studio (version 2024.x)        // 非必需，但推荐安装

带 [!] 的项目表示需要手动处理，带 [✓] 表示已就绪。

8. 验证安装

bash

flutter --version

正常输出类似：

Flutter 3.41.x on linux_x64
Dart 3.6.x

方案二：Flutter-Ohos 鸿蒙定制版环境搭建

Flutter-Ohos 是基于 Flutter 官方版本的鸿蒙适配定制版，由 OpenHarmony-SIG 社区维护。它在官方 Flutter 基础上增加了 HarmonyOS NEXT 平台支持，使你能够使用 Flutter 开发运行在鸿蒙设备上的应用。

重要提示

Flutter-Ohos 与官方 Flutter 版本 不能共用同一个 SDK 目录，需要独立安装。
Flutter-Ohos 当前基于 Flutter 3.35.x 版本适配，功能可能略落后于官方最新版。
建议对鸿蒙开发有需求的开发者使用此方案。

1. 安装 JDK 17

鸿蒙 SDK 和构建工具依赖 JDK 17，需要先安装：

bash

# macOS（使用 Homebrew）
brew install openjdk@17

# Linux（Ubuntu / Debian）— 使用 Adoptium Temurin
sudo apt-get update
sudo apt-get install -y wget gpg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor -o /etc/apt/trusted.gpg.d/adoptium.gpg
echo "deb [signed-by=/etc/apt/trusted.gpg.d/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt-get update
sudo apt-get install -y temurin-17-jdk

# Windows — 访问 https://adoptium.net/ 下载安装

配置 JDK 环境变量：

bash

# Linux / macOS — 添加到 ~/.bashrc 或 ~/.zshrc
export JAVA_HOME=/usr/lib/jvm/temurin-17-jdk-amd64   # Linux 示例
# export JAVA_HOME=$(/usr/libexec/java_home -v 17)    # macOS 示例
export PATH="$PATH:$JAVA_HOME/bin"

# Windows — 系统环境变量
# JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-17.x.x-hotspot
# Path 中添加 %JAVA_HOME%\bin

验证安装：

bash

java -version
# 应显示 openjdk version "17.x.x"

2. 安装 OpenHarmony Command Line Tools

鸿蒙开发需要安装命令行工具，包含 ohpm（包管理器）、hvigor（构建工具）和鸿蒙 SDK。

下载方式：

访问 HarmonyOS 开发者官网
下载 Command Line Tools（命令行工具）
当前推荐版本：commandline-tools-linux-x64-6.1.0.818（Linux）/ 对应平台版本

安装步骤：

bash

# 解压到指定目录
mkdir -p /opt/commandline-tools
unzip commandline-tools-*.zip -d /opt/commandline-tools

# 解压后的目录结构
# /opt/commandline-tools/command-line-tools/
#   ├── ohpm/          # 鸿蒙包管理器
#   ├── hvigor/        # 鸿蒙构建工具
#   ├── tool/node/     # 内置 Node.js
#   └── sdk/           # 鸿蒙 SDK

配置环境变量：

bash

# 添加到 ~/.bashrc 或 ~/.zshrc
export TOOL_HOME=/opt/commandline-tools/command-line-tools
export DEVECO_SDK_HOME=$TOOL_HOME/sdk
export OHOS_SDK_HOME=$TOOL_HOME/sdk
export HDC_HOME=$TOOL_HOME/sdk/default/openharmony/toolchains

export PATH="$PATH:$TOOL_HOME/ohpm/bin"
export PATH="$PATH:$TOOL_HOME/hvigor/bin"
export PATH="$PATH:$TOOL_HOME/tool/node/bin"
export PATH="$PATH:$HDC_HOME"

关于 DevEco Studio

如果你安装了 DevEco Studio（鸿蒙官方 IDE），SDK 也会随 IDE 安装。此时 DEVECO_SDK_HOME 应指向 DevEco Studio 的 SDK 目录，例如：

macOS：~/Library/Huawei/Sdk
Windows：C:\Users\你的用户名\AppData\Local\Huawei\Sdk
Linux：~/Huawei/Sdk

3. 安装 Android SDK

Flutter-Ohos 同样需要 Android SDK 来开发 Android 平台应用，安装方式与方案一相同。

如果你已经安装了方案一的 Android SDK，可以直接复用，只需确保环境变量正确：

bash

export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"

如未安装，请参考方案一的第 5 步。

4. 获取 Flutter-Ohos SDK

Flutter-Ohos SDK 通过 Git 从社区仓库获取：

bash

# 克隆 Flutter-Ohos 仓库（指定版本分支）
git clone --depth 1 -b 3.35.8-ohos-0.0.3 https://gitcode.com/openharmony-tpc/flutter_flutter.git /opt/flutter_flutter

# 添加 Git 安全目录
git config --global --add safe.directory /opt/flutter_flutter

版本说明

3.35.8-ohos-0.0.3 是当前推荐的 Release 版本，稳定可靠。
更多版本和更新日志，请访问 flutter_flutter 仓库查看。

5. 配置 Flutter-Ohos 环境变量

bash

# 添加到 ~/.bashrc 或 ~/.zshrc

# Flutter-Ohos SDK 路径
export FLUTTER_HOME=/opt/flutter_flutter
export PATH="$PATH:$FLUTTER_HOME/bin"

# JDK 路径
export JAVA_HOME=/usr/lib/jvm/temurin-17-jdk-amd64
export PATH="$PATH:$JAVA_HOME/bin"

# 国内镜像源（腾讯云推荐）
export PUB_HOSTED_URL=https://mirrors.cloud.tencent.com/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.cloud.tencent.com/flutter
export FLUTTER_GIT_URL=https://gitcode.com/openharmony-tpc/flutter_flutter.git

# 鸿蒙工具链（如第 2 步已配置，此处可省略）
export DEVECO_SDK_HOME=/opt/commandline-tools/command-line-tools/sdk
export OHOS_SDK_HOME=$DEVECO_SDK_HOME
export HDC_HOME=$DEVECO_SDK_HOME/default/openharmony/toolchains
export PATH="$PATH:$HDC_HOME"

# Android SDK
export ANDROID_HOME=$HOME/Android/Sdk
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"

保存后执行 source ~/.bashrc 使配置生效。

6. 配置 Gradle 镜像（中国大陆用户必做）

Flutter 构建 Android 应用时使用 Gradle，国内访问 Maven 仓库可能失败。创建全局 Gradle 初始化脚本：

bash

mkdir -p ~/.gradle
cat > ~/.gradle/init.gradle << 'EOF'
// 全局配置国内镜像仓库，解决 Maven Central / Gradle Plugin Portal 403 问题

def mirrorUrls = [
    'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/',
    'https://mirrors.cloud.tencent.com/nexus/repository/gradle-plugins/',
    'https://mirrors.cloud.tencent.com/nexus/repository/google/'
]

// 在 settings 脚本执行前注入镜像
gradle.beforeSettings { settings ->
    settings.pluginManagement {
        repositories {
            mirrorUrls.each { url ->
                maven { it.url = uri(url) }
            }
        }
    }
    if (settings.settingsDir.absolutePath.contains('flutter_tools')) {
        settings.dependencyResolutionManagement {
            repositories {
                mirrorUrls.each { url ->
                    maven { it.url = uri(url) }
                }
            }
        }
    }
}

allprojects {
    buildscript {
        repositories {
            mirrorUrls.each { url ->
                maven { it.url = uri(url) }
            }
        }
    }
    if (rootProject.name != 'gradle') {
        repositories {
            mirrorUrls.each { url ->
                maven { it.url = uri(url) }
            }
        }
    }
}
EOF

7. 初始化 Flutter-Ohos

bash

# 配置鸿蒙 SDK 路径
flutter config --ohos-sdk $DEVECO_SDK_HOME

# 禁用遥测数据
flutter config --no-analytics

# 预下载工具链（包含鸿蒙平台支持）
flutter precache --universal --android --ohos
# 如果你还需要 Linux 桌面支持，添加 --linux：
# flutter precache --universal --android --linux --ohos

8. 接受 Android 许可证

bash

flutter doctor --android-licenses

9. 运行 flutter doctor 检查环境

bash

flutter doctor

正常输出类似：

[✓] Flutter (Channel ohos, 3.35.8-ohos-0.0.3)
[✓] Android toolchain (develop for Android devices)
[✓] OpenHarmony toolchain (develop for HarmonyOS devices)
[✓] Chrome (develop for the web)
[✓] VS Code

10. 验证鸿蒙设备连接

bash

# 查看已连接设备
flutter devices

# 如果鸿蒙设备已通过 USB 连接，应能看到类似输出：
# HarmonyOS (mobile) • xxxxxx • ohos-arm64

运行鸿蒙应用：

bash

flutter run -d ohos

两种方案共存

如果你需要同时使用官方版和鸿蒙定制版，可以通过以下方式管理：

方式 A：通过 Shell 别名切换

bash

# 在 ~/.bashrc 或 ~/.zshrc 中添加别名
alias flutter-official='$HOME/development/flutter/bin/flutter'
alias flutter-ohos='/opt/flutter_flutter/bin/flutter'

方式 B：通过脚本切换 PATH

bash

# 创建切换脚本
cat > ~/switch-flutter.sh << 'EOF'
#!/bin/bash
if [ "$1" = "official" ]; then
    export FLUTTER_HOME=$HOME/development/flutter
    echo "切换到 Flutter 官方版"
elif [ "$1" = "ohos" ]; then
    export FLUTTER_HOME=/opt/flutter_flutter
    echo "切换到 Flutter-Ohos 鸿蒙定制版"
else
    echo "用法: source switch-flutter.sh [official|ohos]"
fi
export PATH="$FLUTTER_HOME/bin:$PATH"
flutter --version
EOF

# 使用方式
source ~/switch-flutter.sh official   # 切换到官方版
source ~/switch-flutter.sh ohos      # 切换到鸿蒙定制版

注意

切换环境后，需要重新执行 flutter pub get 确保依赖与当前 SDK 版本兼容。

环境变量速查表

方案一：官方版必配环境变量

变量名	值	说明
`PATH`	`.../flutter/bin`	Flutter CLI
`PUB_HOSTED_URL`	`https://mirrors.cloud.tencent.com/dart-pub`	Pub 包镜像
`FLUTTER_STORAGE_BASE_URL`	`https://mirrors.cloud.tencent.com/flutter`	Flutter 资源镜像
`ANDROID_HOME`	Android SDK 路径	Android SDK

方案二：鸿蒙定制版必配环境变量

变量名	值	说明
`PATH`	`.../flutter_flutter/bin` + 鸿蒙工具链路径	Flutter CLI + 鸿蒙工具
`PUB_HOSTED_URL`	`https://mirrors.cloud.tencent.com/dart-pub`	Pub 包镜像
`FLUTTER_STORAGE_BASE_URL`	`https://mirrors.cloud.tencent.com/flutter`	Flutter 资源镜像
`FLUTTER_GIT_URL`	`https://gitcode.com/openharmony-tpc/flutter_flutter.git`	Flutter Git 仓库镜像
`JAVA_HOME`	JDK 17 安装路径	鸿蒙构建依赖
`DEVECO_SDK_HOME`	鸿蒙 SDK 路径	鸿蒙 SDK
`OHOS_SDK_HOME`	鸿蒙 SDK 路径	鸿蒙 SDK（备用）
`HDC_HOME`	hdc 工具路径	鸿蒙设备连接工具
`ANDROID_HOME`	Android SDK 路径	Android SDK

常见问题

Android license 未接受

bash

flutter doctor --android-licenses
# 逐一输入 y 接受

下载慢 / 镜像配置

Flutter 开发涉及多个包管理器和仓库，国内直连通常较慢。以下列出常用国内镜像及更换方法。

1. Flutter / Dart Pub 镜像

用于加速 flutter pub get 和 SDK 资源下载，通过环境变量配置：

镜像源	`PUB_HOSTED_URL`	`FLUTTER_STORAGE_BASE_URL`	说明
腾讯云	`https://mirrors.cloud.tencent.com/dart-pub`	`https://mirrors.cloud.tencent.com/flutter`	稳定快速，推荐
清华大学	`https://mirrors.tuna.tsinghua.edu.cn/dart-pub`	`https://mirrors.tuna.tsinghua.edu.cn/flutter`	教育网速度极佳
Flutter 中国	`https://pub.flutter-io.cn`	`https://storage.flutter-io.cn`	Flutter 社区维护
上海交大	`https://mirror.sjtu.edu.cn/dart-pub`	`https://mirror.sjtu.edu.cn/flutter`	教育网镜像

更换方法： 修改 ~/.bashrc 或 ~/.zshrc 中的环境变量，保存后执行 source ~/.bashrc：

bash

# 示例：切换为清华源
export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter

Windows 用户通过「系统属性 → 高级 → 环境变量」修改对应的用户变量即可。

2. Gradle / Maven 镜像

用于加速 Android 构建时 Gradle 下载依赖（build.gradle 中的仓库地址），通过 ~/.gradle/init.gradle 配置：

镜像源	Maven Central	Google Maven	Gradle Plugin	说明
腾讯云	`mirrors.cloud.tencent.com/nexus/repository/maven-public/`	`mirrors.cloud.tencent.com/nexus/repository/google/`	`mirrors.cloud.tencent.com/nexus/repository/gradle-plugins/`	稳定快速，推荐
阿里云	`maven.aliyun.com/repository/central`	`maven.aliyun.com/repository/google`	`maven.aliyun.com/repository/gradle-plugin`	阿里云公共仓库
华为云	`repo.huaweicloud.com/repository/maven/`	`repo.huaweicloud.com/repository/google/`	`repo.huaweicloud.com/repository/gradle-plugins/`	华为云镜像

更换方法： 编辑 ~/.gradle/init.gradle，将 mirrorUrls 数组替换为对应镜像地址。例如切换为阿里云：

groovy

def mirrorUrls = [
    'https://maven.aliyun.com/repository/central',
    'https://maven.aliyun.com/repository/google',
    'https://maven.aliyun.com/repository/gradle-plugin',
    'https://maven.aliyun.com/repository/public'      // 阿里云公共仓库（聚合多个源）
]

阿里云 Maven 仓库说明

阿里云提供了多个仓库地址，其中 public 是聚合仓库，包含了 central、jcenter、google 等，建议优先使用：

central：Maven Central
google：Google Android 仓库
gradle-plugin：Gradle 插件仓库
public：聚合仓库（推荐，覆盖面最广）
jcenter：JCenter（已停止服务，可不配）

镜像切换后记得刷新

每次修改环境变量后，务必执行 source ~/.bashrc（或 source ~/.zshrc）或重新打开终端，才能使新配置生效。修改 init.gradle 后，需要重新运行 flutter build 或 flutter run 才会使用新镜像。

flutter 命令找不到

确认 flutter/bin 已加入 PATH
执行 source ~/.bashrc 或重新打开终端
检查路径是否包含中文或空格

Gradle 下载依赖失败（403 错误）

确保已配置 ~/.gradle/init.gradle 文件（见方案二第 6 步），此配置对两种方案均有效。

鸿蒙设备无法识别

确认 HDC_HOME 环境变量已正确配置
确认设备已开启开发者模式和 USB 调试
运行 hdc list targets 检查设备是否连接

flutter doctor 提示 OpenHarmony toolchain 不可用

确认 DEVECO_SDK_HOME 指向正确的 SDK 目录
确认已运行 flutter config --ohos-sdk $DEVECO_SDK_HOME
确认已运行 flutter precache --ohos

两个版本冲突

两种方案使用不同的 SDK 目录，只要 PATH 中只包含一个版本的路径，就不会冲突。使用上方的切换脚本来管理。

环境安装 ​

通用前置条件 ​

系统要求 ​

安装 Git ​

安装 IDE ​

方案一：Flutter 官方版环境搭建 ​

1. 下载 Flutter SDK ​

2. 解压 SDK ​

3. 配置环境变量 ​

4. 配置国内镜像源（中国大陆用户必做） ​

5. 安装 Android SDK ​

6. 接受 Android 许可证 ​

7. 运行 flutter doctor 检查环境 ​

8. 验证安装 ​

方案二：Flutter-Ohos 鸿蒙定制版环境搭建 ​

1. 安装 JDK 17 ​

2. 安装 OpenHarmony Command Line Tools ​

3. 安装 Android SDK ​

4. 获取 Flutter-Ohos SDK ​

5. 配置 Flutter-Ohos 环境变量 ​

6. 配置 Gradle 镜像（中国大陆用户必做） ​

7. 初始化 Flutter-Ohos ​

8. 接受 Android 许可证 ​

9. 运行 flutter doctor 检查环境 ​

10. 验证鸿蒙设备连接 ​

两种方案共存 ​

方式 A：通过 Shell 别名切换 ​

方式 B：通过脚本切换 PATH ​

环境变量速查表 ​

方案一：官方版必配环境变量 ​

方案二：鸿蒙定制版必配环境变量 ​

常见问题 ​

Android license 未接受 ​

下载慢 / 镜像配置 ​

1. Flutter / Dart Pub 镜像 ​

2. Gradle / Maven 镜像 ​

flutter 命令找不到 ​

Gradle 下载依赖失败（403 错误） ​

鸿蒙设备无法识别 ​

flutter doctor 提示 OpenHarmony toolchain 不可用 ​

两个版本冲突 ​

环境安装

通用前置条件

系统要求

安装 Git

安装 IDE

方案一：Flutter 官方版环境搭建

1. 下载 Flutter SDK

2. 解压 SDK

3. 配置环境变量

4. 配置国内镜像源（中国大陆用户必做）

5. 安装 Android SDK

6. 接受 Android 许可证

7. 运行 flutter doctor 检查环境

8. 验证安装

方案二：Flutter-Ohos 鸿蒙定制版环境搭建

1. 安装 JDK 17

2. 安装 OpenHarmony Command Line Tools

3. 安装 Android SDK

4. 获取 Flutter-Ohos SDK

5. 配置 Flutter-Ohos 环境变量

6. 配置 Gradle 镜像（中国大陆用户必做）

7. 初始化 Flutter-Ohos

8. 接受 Android 许可证

9. 运行 flutter doctor 检查环境

10. 验证鸿蒙设备连接

两种方案共存

方式 A：通过 Shell 别名切换

方式 B：通过脚本切换 PATH

环境变量速查表

方案一：官方版必配环境变量

方案二：鸿蒙定制版必配环境变量

常见问题

Android license 未接受

下载慢 / 镜像配置

1. Flutter / Dart Pub 镜像

2. Gradle / Maven 镜像

flutter 命令找不到

Gradle 下载依赖失败（403 错误）

鸿蒙设备无法识别

flutter doctor 提示 OpenHarmony toolchain 不可用

两个版本冲突