作者：爱吃大芒果

个人主页  爱吃大芒果

本文所属专栏 Flutter

更多专栏

• Ascend C 算子开发教程（进阶）
• 鸿蒙集成
• 从0到1自学C++

  ---

  本指南将详细介绍 Windows 系统下 Flutter 开发环境的完整搭建流程，从前期准备、工具安装、环境配置到最终验证，帮助零基础开发者快速完成环境搭建，顺利开启 Flutter 开发之旅。

一、前期准备

1.1 了解 Flutter 环境依赖

Flutter 是跨平台开发框架，其环境搭建需要依赖以下核心工具和组件：

• Flutter SDK：核心开发包，包含 Flutter 命令行工具、框架代码等；

• Dart SDK：Flutter 的底层编程语言 SDK（Flutter SDK 已内置，无需单独安装）；

• 开发工具：推荐 DevEco Studio（支持 HarmonyOS 及 Flutter 开发，内置模拟器和相关插件）或 VS Code（轻量型编辑器，需安装插件）；

• 模拟器/真机：用于运行和调试 Flutter 应用（模拟器或真实手机）；

• 相关依赖：如 Git（用于获取 Flutter 资源）、DevEco Studio 内置相关工具链（无需单独安装额外开发包）。

1.2 系统要求

系统	最低配置要求
Windows	1. 操作系统：Windows 10 或更高版本（64 位）；2. 内存：至少 4GB RAM，推荐 8GB 及以上；3. 存储：至少 15GB 可用磁盘空间（用于安装 DevEco Studio、Flutter SDK、HarmonyOS SDK 及模拟器镜像）；4. 其他：需开启硬件虚拟化（在 BIOS/UEFI 中设置，用于 HarmonyOS 模拟器运行）

二、Windows 系统 Flutter 环境搭建步骤

2.1 安装 Git

Git 是获取 Flutter SDK 的必需工具，需先完成安装：

1. 下载 Git 安装包：访问 Git 官方下载页，选择对应 Windows 版本（64 位推荐），下载后双击运行安装程序；

2. 安装配置：全程可默认下一步，建议在“选择组件”步骤勾选“Add Git to PATH”（自动配置环境变量，避免后续手动配置）；若未勾选，需后续手动将 Git 安装目录下的 bin 文件夹路径添加到系统环境变量的 Path 中；

3. 验证安装：按下 Win+R 键输入 cmd 打开命令提示符，输入

    git --version

   若显示版本信息，则安装成功。

2.2 下载并配置适配 HarmonyOS 的 Flutter SDK

Flutter SDK 是开发的核心，由于需适配 DevEco Studio 及 HarmonyOS，需使用 OpenHarmony 社区维护的 Flutter SDK，步骤如下：

1. 创建 SDK 存放目录：在非中文、无空格路径下新建文件夹（如 D:\Flutter\HarmonyOS），用于存放适配 HarmonyOS 的 Flutter SDK；

2. 拉取社区维护的 Flutter SDK：打开命令提示符，进入上述新建目录，执行以下命令克隆 SDK（需先完成 Git 安装）：

   git clone -b oh-3.27.4-dev

   https://gitcode.com/openharmony-tpc/flutter_flutter.git

   （oh-3.27.4-dev 为适配 HarmonyOS 6 的稳定分支，可根据最新版本调整分支名）；

3. 配置 Flutter 环境变量：右键“此电脑” → “属性” → “高级系统设置” → “环境变量”；在“系统变量”中找到“Path”，点击“编辑” → “新建”，将克隆得到的 flutter_flutter 目录下的 bin 文件夹路径（如 D:\Flutter\HarmonyOS\flutter_flutter\bin）添加进去，点击“确定”保存；

4. （可选）配置 Flutter 镜像源：由于国内网络原因，可配置国内镜像加速资源获取，在“系统变量”中新建两个变量：

变量名：

FLUTTER_STORAGE_BASE_URL

变量值：

https://storage.flutter-io.cn

变量名：

PUB_HOSTED_URL

变量值：

https://pub.flutter-io.cn

验证 Flutter 配置：打开新的命令提示符（环境变量配置后需重启命令行生效），输入

flutter --version

若显示 Flutter 和 Dart 的版本信息，则 SDK 配置成功。

2.3 安装开发工具（DevEco Studio）

DevEco Studio 是适配 HarmonyOS 开发的官方 IDE，支持 Flutter 插件集成，内置 HarmonyOS 模拟器和工具链，步骤如下：

1. 下载 DevEco Studio：访问 DevEco Studio 官方下载页，下载最新稳定版（推荐6.0.0 版本，适配 HarmonyOS 6），勾选许可协议后完成下载；

2. 安装 DevEco Studio：双击安装程序，点击“Next”，勾选所有默认组件（含 HarmonyOS 模拟器、工具链等），点击“Next”；选择安装目录（建议避免中文路径，如 D:\DevEco Studio），点击“Next”，等待安装完成；首次启动 DevEco Studio 时，选择“Do not import settings”，点击“OK”；进入初始化向导，选择“Standard”标准安装模式，点击“Next”，选择界面主题后点击“Finish”，等待内置组件下载配置完成（需联网，耗时较长）；

3. 安装 Flutter 和 Dart 插件：打开 DevEco Studio，点击“File” → “Settings” → “Plugins”；点击右上角齿轮图标，选择“Install Plugin from Disk...”，若有本地 Flutter 插件包可直接导入，若无则在插件市场搜索“Flutter”和“Dart”（需提前配置插件市场镜像），点击“Install”安装；安装完成后点击“Restart IDE”重启 DevEco Studio，使插件生效；

4. 配置 HarmonyOS SDK：打开 DevEco Studio，点击“File” → “Settings” → “HarmonyOS SDK”；勾选“HarmonyOS 6.0（API Version 10+）”及对应的系统镜像（如“OpenHarmony 6.0 System Image”），点击“Apply”下载安装；记录 SDK 安装路径（默认如 D:\DevEco Studio\sdk），后续配置环境变量使用；

5. 配置 DevEco 相关环境变量：回到“环境变量”设置，在“系统变量”中新建 DEVECO_SDK_HOME 变量，变量值为上述 HarmonyOS SDK 安装路径；在“系统变量”的“Path”中添加以下路径（根据实际安装目录调整）：

   D:\DevEco Studio\sdk\default\openharmony\toolchains

   D:\DevEco Studio\tools\ohpm\bin

   D:\DevEco Studio\tools\node

   D:\DevEco Studio\tools\hvigor\bin

   点击“确定”保存配置

6. 创建并启动 HarmonyOS 模拟器：打开 DevEco Studio，点击顶部工具栏“Tools” → “Device Manager”；点击“Create Device”，选择 HarmonyOS 设备型号（如“Pixel 6 适配版”），点击“Next”；选择已下载的 HarmonyOS 6.0 系统镜像，点击“Next”，设置模拟器名称后点击“Finish”；在设备列表中点击模拟器后的“启动”按钮，等待初始化完成（确保已开启硬件虚拟化）；

7. 运行 Flutter 环境检查：打开新的命令提示符，输入

    flutter doctor

   （该命令会检查 Flutter 开发所需的所有依赖是否配置完成）；

8. 查看检查结果，针对报错信息逐一解决：若提示“HarmonyOS toolchain - develop for HarmonyOS devices”存在问题，检查 DEVECO_SDK_HOME 配置及 HarmonyOS SDK 安装情况；若提示“Flutter plugin not installed”或“Dart plugin not installed”，重新检查 DevEco Studio 插件安装情况；若提示“hdc not recognized”，确认 DevEco 工具链路径已添加到环境变量；

9. 直至 flutter doctor 命令无严重错误（警告可暂时忽略），环境检查完成。

2.4 创建并运行第一个 Flutter 项目

环境配置完成后，创建一个默认项目验证是否能正常运行：

1. 创建 Flutter 项目：打开命令提示符，进入项目存放目录（非中文路径），执行创建命令：

   flutter create --platforms ohos D:\Projects\first_flutter_ohos_app

   （--platforms ohos 指定适配 HarmonyOS，路径为项目保存位置）；

2. 在 DevEco Studio 中打开项目：启动 DevEco Studio，点击“Open Project”，导航至上述创建的项目目录，选择 ohos 子目录并打开；

3. 统一 API 版本号：项目加载完成后，点击“File” → “Settings” → “HarmonyOS SDK”，记录当前 Compile SDK Version（如 6.0.0）；在项目中全局搜索默认版本号（如 5.0.0），将 build-profile.json5、oh-package.json5 等文件中的版本号替换为记录的 Compile SDK Version；

4. 运行项目：确保 HarmonyOS 模拟器已启动，或已连接 HarmonyOS 真机（需开启开发者模式和 USB 调试）；在 DevEco Studio 工具栏中选择对应的运行设备；点击工具栏中的“Run”按钮（绿色三角形），等待项目编译和运行；若模拟器/真机中出现 Flutter 默认的计数器应用界面（显示“0”和“+”“-”按钮），则说明环境搭建成功，可正常进行 Flutter 开发。

三、常见问题解决

3.1 命令提示符中输入 flutter 提示“不是内部或外部命令”

原因：Flutter 环境变量未配置正确或未重启命令行。解决方法：

• 重新检查系统变量 Path 中是否添加了 Flutter SDK 的 bin 目录路径，确保路径正确且无拼写错误；

• 配置完成后需关闭当前命令提示符，重新打开新的命令行再尝试。

3.2 模拟器无法启动，提示“VT-x is disabled in BIOS/UEFI”

原因：未开启硬件虚拟化（VT-x/AMD-V）。解决方法：

• 重启电脑，在开机时按对应的快捷键（如 Del、F2、F10，不同品牌主板快捷键不同）进入 BIOS/UEFI 设置；

• 找到“虚拟化技术”（VT-x/AMD-V）选项，设置为“Enabled”；

• 保存设置并重启电脑，重新启动模拟器即可。

3.3 提示“hdc not recognized”

原因：DevEco Studio 工具链路径未添加到环境变量。解决方法：

• 重新检查系统变量 Path 中是否添加了 DevEco Studio 的 toolchains、ohpm/bin 等路径（具体路径参考 2.3.5 步骤）；

• 确认路径配置正确后，重启命令提示符和 DevEco Studio 即可。

3.4 项目编译失败，提示“版本不匹配”

原因：Flutter 项目默认 API 版本与 DevEco Studio 配置的 HarmonyOS SDK 版本不一致。解决方法：

• 打开 DevEco Studio 的“File” → “Settings” → “HarmonyOS SDK”，记录 Compile SDK Version（如 6.0.0）；

• 在项目中全局搜索默认版本号（如 5.0.0），将 build-profile.json5、oh-package.json5 等文件中的版本号统一替换为记录的 Compile SDK Version；

• 点击 DevEco Studio 菜单栏“Build” → “Clean Project”清理项目，重新编译运行即可。