​
**欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

正如标题所言，本篇文章主要是围绕着在做鸿蒙跨平台开发前的一些必备的东西的部署。

注：本文出现的图片全是以windows系统为例。

首先先简单介绍几个必要准备的东西。一是要装Git，二是要装JAVA（推荐安装JDK 11+），三是要安装DevEco Studio，四是要进行Flutter-OH环境搭建。接下来会一一讲解这四个安装与操作过程中会出现的问题，以及如何解决。再做完这些之后就可以到DevEco Studio上用虚拟机或者用实机测试了。

·Git 安装

Git 安装指南

📥 各操作系统安装方法

Windows

1. 访问 Git官网

Git 的官网地址是：https://git-scm.com/

📥 各平台下载指引

2. 运行 .exe 文件，按向导安装，关键配置项注意：
   · 选择默认编辑器：建议选 VS Code 或 Notepad（新手别用 Vim）
   · PATH 环境变量：选 “Git from the command line and also from 3rd-party software”（才能在 CMD/PowerShell 里用）
   · 换行符转换：Windows 开发选第一个，跨平台开发选 “as-is”
3. 验证：打开 CMD，输入 git --version，显示版本号即成功

macOS

· 推荐 Homebrew：brew install git
· 官方安装包：下载 .dmg 文件安装
· 验证：git --version

Linux

发行版 命令
Debian/Ubuntu sudo apt update && sudo apt install git
CentOS/RHEL 7- sudo yum install git
Fedora 22+ sudo dnf install git
Arch Linux pacman -S git

验证：git --version

⚙️ 安装后必做配置

# 配置用户信息（必须，标识代码作者）
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

# 推荐配置
git config --global init.defaultBranch main        # 默认分支名
git config --global color.ui auto                  # 彩色输出

配置后可用 git config --global --list 查看所有设置。

🔑 配置 SSH 密钥（连接远程仓库）

1. 生成密钥：ssh-keygen -t ed25519 -C “你的邮箱”（一路回车）
2. 复制公钥：cat ~/.ssh/id_ed25519.pub（Linux/macOS）或 type %userprofile%.ssh\id_ed25519.pub（Windows）
3. 添加到 GitHub/Gitee/GitLab：个人设置 → SSH Keys → 粘贴保存
4. 测试：ssh -T git@github.com（或其他平台地址）

💡 常见问题速查

· git commit 卡在编辑器界面：未配置编辑器，执行 git config --global core.editor “notepad”（Windows）或 “code --wait”（VS Code）
· git push 报 “Permission denied”：SSH 密钥未添加到远程仓库
· git clone 速度慢：可用 Gitee 镜像源

📚 延伸阅读：Pro Git Book（官方推荐免费书籍）

出现以下图片则说明git能够成功运行，Git 的验证图片如下所示：

2.JAVA安装

好的，明白了。那我们把上面的内容，专门为新手整理成一份更简单、更详细的 “傻瓜式”安装指南。

我们就以 Windows 系统、安装 JDK 17（目前最稳定、最推荐的版本）为例，一步步来。

---

第一步：下载 JDK

1. 打开浏览器，访问 Oracle 官网下载页。
   链接：https://www.oracle.com/java/technologies/downloads/
2. 页面会显示当前最新版本（如 JDK 24），你需要找的是 Java 17。
   往下滚动，找到 Java 17 这一栏。
3. 在 Java 17 下面，根据你的操作系统选择：
   · Windows → 选择 Windows x64 Installer
   （文件名类似 jdk-17_windows-x64_bin.exe）
4. 点击下载，可能需要登录 Oracle 账号（免费注册一个就行，或者可以搜索“jdk 17 华为镜像”等国内镜像更快）。

---

第二步：安装 JDK

1. 找到下载好的 .exe 文件，双击运行。
2. 欢迎界面点 Next。
3. 最关键的一步：修改安装路径
   · 默认会安装到 C:\Program Files\Java\jdk-17
   · 强烈建议改成 D:\Java\jdk-17（如果没有 D 盘，就记住你装在哪里）
   · 点 Next 继续。
4. 等待进度条走完，出现 “Successfully Installed” 之类提示，点 Close 关闭。

---

第三步：配置环境变量（新手最容易卡住的地方）

环境变量的作用：让系统在任何一个位置都能找到 Java 命令。

1. 打开设置界面
   · 右键点击桌面上 “此电脑” 或 “我的电脑”
   · 选择 属性
   · 点击左侧 高级系统设置
   · 点击右下角 环境变量
2. 新建 JAVA_HOME（在“系统变量”区域）
   · 点 新建
   · 变量名：JAVA_HOME
   · 变量值：填写你刚才的安装路径，比如 D:\Java\jdk-17
   · 点 确定
3. 编辑 Path 变量
   · 在“系统变量”里找到 Path，双击
   · 点右侧 新建
   · 输入：%JAVA_HOME%\bin
   · 点 确定 关闭所有窗口

---

第四步：验证是否安装成功

1. 按键盘 Win + R，输入 cmd，回车打开命令行窗口。
2. 在黑色窗口里输入以下命令，按回车：

   java -version
   

3. 如果出现类似这样的文字，就表示成功：

   java version "17.0.x" ...
   ​
   

4. 如果提示：

   'java' 不是内部或外部命令...
   

   说明环境变量没配好，可以：
   · 检查 JAVA_HOME 路径是否正确
   · 检查 Path 里是否有 %JAVA_HOME%\bin
   · 关掉 cmd 窗口，重新打开一个再试

---

常见新手问题

问题 原因 解决办法
安装时没有改路径，找不到了 默认装到 C 盘 Program Files 里 可以去 C:\Program Files\Java 查看
输入 java -version 没反应 环境变量没配置或没生效 重启 cmd 窗口，或重新检查 Path
分不清 JDK 和 JRE 只装了 JRE 无法编译代码 确保你装的是 JDK（下载时选 JDK）

如图所示为最后的验证后的结果：

·DevEco Studio安装及配置

DevEco Studio 的安装配置已大幅简化，官方安装包将 HarmonyOS SDK、Node.js 等关键组件进行了合一打包，基本实现了“开箱即用”。以下是Windows和macOS环境下的安装配置流程。

📥 下载与安装

1. 下载
   · 官方地址：华为开发者联盟官网：https://developer.huawei.com/cn/
   · 版本选择：推荐下载 Release（稳定版） 。
2. 系统要求
   · Windows：Win10/11（64位），16GB 内存（推荐），100GB 硬盘。
   · macOS：macOS 11（X86）或 12（ARM）及以上，8GB 内存，100GB 硬盘。
3. 安装步骤
   · Windows：双击 .exe 文件，选择安装路径（避免中文/空格），按向导完成即可。
   · macOS：双击 .dmg，将 DevEco-Studio.app 拖入 Applications 文件夹。
   · 首次启动：若弹出导入设置弹窗，选择 Do not import settings。

⚙️ 环境配置

新版安装包已集成 SDK 和 Node.js，通常无需手动配置。建议完成以下检查：

1. SDK 管理
   HarmonyOS SDK 已内置于安装目录，通常无需额外下载。如需特定API版本，可前往 File > Settings > HarmonyOS SDK 勾选下载。
2. 诊断环境（推荐）
   在欢迎页点击 Diagnose，工具会自动检查电脑配置、网络连通性等，并给出修复建议。
3. 汉化（可选）
   从 6.0.0 版本开始，中文插件默认启用。可在 File > Settings > Appearance & Behavior > System Settings > Language 中切换为 Chinese。

✅ 验证安装

1. 创建项目：点击 Create Project，选择 Empty Ability 模板，填写项目名（避免中文/空格），点击 Finish。
2. 运行项目：
   · 预览器：打开 Index.ets，点击右侧 Previewer 实时查看UI。
   · 模拟器：如需更完整测试，通过 Tools > Device Manager 下载安装模拟器后启动运行。

🚨 常见问题与避坑

常见问题 解决建议
安装/编译失败 检查路径：确保安装、SDK和项目路径均无中文或空格（如 D:\Dev…）。
模拟器无法启动 开启虚拟化：进入BIOS开启 VT-x/AMD-V，并在Windows功能中开启 Hyper-V（若支持）。
SDK下载缓慢 检查网络，可尝试更换网络环境或配置代理后重试。
真机调试失败 在设备上开启 开发者模式 和 USB调试，并授权电脑调试权限。

•Flutter-OH的环境搭建

Flutter-OH 的环境搭建本质上是在标准 Flutter 环境基础上，将 Flutter SDK 替换为鸿蒙适配版本，并配置好 DevEco Studio 的工具链路径。以下是 Windows 和 macOS 环境的详细步骤：

---

📦 第一步：安装基础工具

工具 版本要求 说明
DevEco Studio 5.0+ / 6.x 鸿蒙官方 IDE，提供 SDK 和工具链
JDK JDK 17 必须 17 版本，低版本不兼容
Git 最新版 用于克隆 Flutter-OH SDK
Node.js DevEco 自带 无需单独安装（具体步骤见上文）

路径要求：所有安装路径禁止包含中文、空格或特殊字符

---

📥 第二步：下载 Flutter-OH SDK

Flutter-OH SDK 有稳定版和尝鲜版两种选择：

版本类型 分支名 适用场景
生产推荐 oh-3.27.0-release 稳定可靠，适合正式项目
学习尝鲜 oh-3.35.7-dev 体验新特性，适合学习

# 克隆仓库（以 3.35.7-dev 为例）
git clone -b oh-3.35.7-dev https://gitcode.com/openharmony-tpc/flutter_flutter.git

---

⚙️ 第三步：配置环境变量

Windows 系统

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 新增以下系统变量：

变量名 变量值（示例，请替换为实际路径）
JAVA_HOME C:\Program Files\Java\jdk-17
DEVECO_SDK_HOME D:\DevEco-Studio\sdk
PUB_HOSTED_URL https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL https://storage.flutter-io.cn

1. 在 Path 变量中追加：
   · %JAVA_HOME%\bin
   · D:\flutter_flutter\bin（你的 Flutter-OH 路径）
   · D:\DevEco-Studio\tools\ohpm\bin
   · D:\DevEco-Studio\tools\hvigor\bin
   · D:\DevEco-Studio\tools\node\bin

macOS / Linux 系统

编辑 ~/.zshrc 或 ~/.bash_profile，添加以下配置：

# JDK 17 配置
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# DevEco Studio 工具链
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=$TOOL_HOME/sdk
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$TOOL_HOME/tools/node/bin:$PATH

# Flutter-OH 配置（替换为实际路径）
export PATH=/Users/你的用户名/flutter_flutter/bin:$PATH

# 国内镜像（加速依赖下载）

ort PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

执行 source ~/.zshrc 使配置生效。

---

✅ 第四步：配置 SDK 路径并验证

# 1. 清空旧配置（如有）
flutter config --ohos-sdk=""

# 2. 设置鸿蒙 SDK 路径（替换为你的 DevEco SDK 实际路径）
flutter config --ohos-sdk="D:/DevEco-Studio/sdk"   # Windows
flutter config --ohos-sdk="/Applications/DevEco-Studio.app/Contents/sdk"  # macOS

# 3. 验证环境
flutter doctor -v

期望输出：

[✓] Flutter (Channel xxx, 3.35.8-ohos-..., ...)
[✓] HarmonyOS toolchain – develop for HarmonyOS devices

注意：Android toolchain、Xcode 等显示 [!] 可忽略，仅鸿蒙开发无需处理。

---

如下图所示：

🚀 第五步：创建并运行项目

# 创建仅支持鸿蒙的项目
flutter create --platforms ohos my_ohos_app
cd my_ohos_app

# 编译调试版 HAP 包
flutter build hap --debug

运行到真机/模拟器：

# 查看已连接设备
flutter devices

# 一键运行（自动编译+安装+启动）
flutter run --debug -d <device-id>

产物路径：my_ohos_app/ohos/entry/build/default/outputs/default/entry-default-signed.hap

---

如果出现乱码则说明你这个运行有问题，这会直接影响后续的开发的。我再次建议，重新运行下。
直到出现如下图所示:

如果依旧不行的话，建议回溯查找有什么地方做错了。

🛠️ 可选：使用 FVM 管理多版本 SDK

如需同时维护官方 Flutter 和 Flutter-OH，推荐使用 FVM：

# 安装 FVM（macOS）
brew tap leoafarias/fvm
brew install fvm

# 安装 Flutter-OH 到 FVM 管理目录
cd ~/fvm/versions
git clone -b oh-3.35.7-dev https://gitcode.com/openharmony-tpc/flutter_flutter.git
mv flutter_flutter custom_3.35.7_ohos

# 切换使用
fvm global custom_3.35.7_ohos
fvm flutter doctor

—如下三图为上述需要添加的必要变量的实际图，供参考：

🚨 常见问题与解决

问题 解决方案
flutter doctor 显示 HarmonyOS toolchain 为 [!] 重新执行 flutter config --ohos-sdk 检查路径是否正确
编译时提示 JDK 版本错误 确认 java -version 输出为 17，检查 JAVA_HOME 环境变量
模拟器无法启动 进入 BIOS 开启 VT-x/AMD-V，Windows 需开启 Hyper-V
真机安装失败 DevEco Studio 中配置签名：File → Project Structure → Signing Configs → Automatically generate signature
环境变量不生效 重启终端或执行 source ~/.zshrc（macOS）/重新打开 CMD（Windows）

---

接下来进入到DevEco studio中验证。在验证过程中可能会出现如下情况：
!

​​

这个问题有可能是在添加错误的变量TOOL_HOME的值，这里的值一定是为DevEco Studio的实际安装路径。建议从一方面排查问题。同时也有可能是DevEco Studio本身出现了问题，如果可以的话，建议重新安装DevEco Studio。

如果这个问题解决了，记得先退出保存设置，不然会影响后续的验证的。一般验证大概需要几分钟的等待，之后若出现报错现象，如图：

有Sync Now的出现，第一步就先点这个，然后再一步步反过去调查有什么地方没有做到位。这个问题可以，重新进入软件，然后再通过重新反复测试，最后会取得成功的。

最后通过验证后出现如下面所示的界面时，则会说明你已经成功实现flutter与鸿蒙的跨平台开发的前奏。
​​

​​

这里强烈推荐这篇文章，希望能给大家更多的帮助
​​​​​​https://blog.csdn.net/zl392321162/article/details/156203074
如果这几个步骤全部做完了，那么就可以开始使用DevEco Studio进行开发了。下一篇则围绕着在DevEco开发中遇到的一些问题。
​
​