在HarmonyOS电脑上设置Flutter工具链的分步指南

使用HiSH在HarmonyOS上设置Flutter工具链

本指南提供了在HarmonyOS PC、平板甚至手机上为OpenHarmony设置原生Flutter开发环境的完整分步操作说明。按照这些说明，您将能够直接在HarmonyOS设备上构建和运行Flutter应用程序，而无需单独的macOS、Windows或Linux机器。关键使能工具是HiSH，这是一个专为HarmonyOS设计的Linux模拟器和shell工具，允许您运行完整的Linux环境，将您的设备转变为便携式Linux开发终端。

在HarmonyOS上使用HiSH的类Unix哲学

此处描述的方法遵循您所引用的经典“类Unix原则”，类似于工具链在macOS和Linux上的运作方式。HiSH在HarmonyOS之上提供了完整的arm64 Linux内核和可选的用户空间环境（Alpine Linux、Ubuntu 24.04或Debian 12）。这创建了一个稳定的、基于Linux的命令行界面，您可以在其中执行git、bash、curl等标准工具，最重要的是Flutter SDK（软件开发工具包）。虽然HarmonyOS有自己的原生终端（HiShell），但它缺少Flutter工具链所需的完整Linux用户空间。HiSH完全填补了这一空白，使您的HarmonyOS设备成为一流的开发主机。

在HarmonyOS上设置Flutter工具链的分步指南

此过程分为四个逻辑阶段：安装HiSH和必要的IDE、配置HiSH内的Linux环境、创建或迁移您的Flutter项目，最后签名并部署您的应用。

阶段1：环境准备（基础）

在编写任何代码之前，您必须安装构成开发环境基础的三个核心组件。

步骤1.1：安装HiSH（Linux环境） HiSH是此设置中不可协商的核心。它是一个专为HarmonyOS设计的Linux模拟器和shell工具。基于qemu-ohos，它支持二合一PC、平板和手机。

• 操作：您有三种获取HiSH的选项：最简单：直接从AppGallery安装（注意此版本不支持JIT，因此运行较慢）。开发者推荐：从HiSH Releases页面下载HAP文件，自行签名（使用DevEco Studio的签名工具），然后使用hap_installer安装或通过DevEco Studio IDE本身部署。此版本支持JIT，运行速度更快。从源码构建：克隆HiSH仓库并在DevEco Studio中构建，以获得最大程度的定制。

• 为什么选择HiSH：OpenHarmony-SIG Flutter SDK依赖于为类Unix系统设计的工具链。HiSH通过提供完整的虚拟化Linux内核和根文件系统来满足这一依赖，具有网络、端口转发和共享文件夹功能，便于在HarmonyOS和Linux环境之间交换文件。

步骤1.2：安装DevEco Studio（原生IDE和SDK管理器）

DevEco Studio 是面向 HarmonyOS 的基于 Rust 的原生 IDE。它不是 JetBrains 的产品，而是一个用 Rust 编写的自定义高性能环境，并使用华为自研的 Bifeng 框架。

• 操作：从华为开发者官网下载并安装 DevEco Studio。

• 原因：DevEco Studio 在此工作流中承担两项关键功能：它管理 OpenHarmony/HarmonyOS SDK（软件开发工具包），其中包含构建和部署应用所需的原生工具（hdc、ohpm、hvigor）。它负责将 .hap（HarmonyOS Ability Package）文件最终签名并部署到你的设备。它还提供“自动签名”功能以生成安全证书。

步骤 1.3：安装 BiSheng JDK 17（缺失的一环）Flutter 的内部工具需要 Java 运行时才能运行。在 HarmonyOS 上，这由 BiSheng JDK 提供。

• 操作：从 AppGallery 安装 BiSheng JDK 17-OH。此过程会自动将 Java 环境注册到系统的工具链配置中，并将其链接到 CodeArts IDE 和 DevEco Studio。

• 关键说明：如果没有这个特定的 JDK，flutter 命令将在 HiSH 中失败，因为它找不到有效的 Java 运行时。

阶段 2：SDK 与环境配置（在 HiSH 内）

安装核心应用后，你现在启动 HiSH 并配置 Linux 环境，使其识别 Flutter SDK 和 BiSheng JDK。

步骤 2.1：启动 HiSH 并设置共享文件夹 在 HarmonyOS 设备上打开 HiSH 应用。一旦 Linux 内核启动并出现 shell 提示符（可能来自包含的 Alpine Linux rootfs），你需要找到共享文件夹。此文件夹是一个双向桥梁：放置在此处的文件在 HarmonyOS 和 HiSH Linux 环境中都可见。

• 操作：HiSH 通常会创建一个共享目录。你可以通过查找已挂载的目录（通常是 /mnt/shared 或类似路径）或查看 HiSH 文档来找到其位置。将所有开发项目放在此共享文件夹中，以便你可以从 HiSH（用于命令行构建）和 DevEco Studio（用于签名和部署）访问它们。

步骤 2.2：安装必要的 Linux 软件包 在 HiSH 终端中，更新包管理器并安装 git 和 curl，因为 Alpine Linux rootfs 非常精简。

• 操作：在 HiSH 终端中运行以下命令：bash

apk update
apk add git curl bash

步骤 2.3：克隆 OpenHarmony Flutter SDK 现在，将 OpenHarmony 的 Flutter SDK 特定分支直接克隆到你的共享文件夹中。

• 操作：导航到你的共享文件夹（例如 cd /mnt/shared）并运行以下命令以获取当前稳定版本（3.27.x 分支）：bash

git clone -b br_3.27.4-ohos-1.0.4 https://gitcode.com/openharmony-tpc/flutter_flutter.git

步骤 2.4：为 Linux Shell 配置环境变量 你必须告诉 HiSH 内的系统在哪里找到 Flutter 和 BiSheng JDK 二进制文件。由于 BiSheng JDK 安装在 HarmonyOS 主机上，你需要从 HiSH 内部定位其安装路径。它通常可以通过共享文件夹或特定挂载点访问。在本指南中，我们假设你已将 JDK 复制或链接到 HiSH 内的某个路径，例如 /home/openharmony/libs/bisheng-jdk17-oh 。

• 操作：编辑 HiSH Linux 环境中的 .bashrc 文件（或直接在会话中运行这些命令）以设置必要的路径。如果安装了 nano，请使用 nano ~/.bashrc，或使用 vi ~/.bashrc 。添加以下行，并调整路径以匹配 HiSH 内的实际目录：bash

# Flutter OH SDK Path
export FLUTTER_HOME=/mnt/shared/flutter_flutter
export PATH=”$FLUTTER_HOME/bin:$PATH”

# BiSheng JDK 17 Path (inside the HiSH Linux environment)
export JAVA_HOME=/home/openharmony/libs/bisheng-jdk17-oh
export PATH=”$JAVA_HOME/bin:$PATH”

# Optional but recommended: Use Chinese mirrors for faster package downloads
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
export PUB_HOSTED_URL=https://pub.flutter-io.cn

• 加载配置：运行 source ~/.bashrc 以应用更改。

步骤 2.5：将 BiSheng JDK 链接到 Flutter 工具链 这是最重要的命令。你必须明确告诉 Flutter 工具链在哪里找到 BiSheng JDK。

• 操作：在 HiSH 终端中，运行以下命令：bash

flutter config --jdk-dir=$JAVA_HOME

步骤 2.6：在 HiSH 内验证你的设置 运行验证命令，以确保 Linux 模拟器内的一切都已正确配置。

• 操作：在 HiSH 终端中执行 flutter doctor -v。

• 预期结果：你应该会在 Java 二进制路径旁看到一个绿色对勾，确认它正在使用 BiSheng 版本。输出还应表明 OpenHarmony 工具链可用。你可能会看到关于其他平台（Android、iOS）的警告，但关键是 OpenHarmony 环境没有错误。

阶段 3：项目创建与迁移（代码）

你的 Linux 环境（HiSH）现在已准备就绪。你可以创建一个新的 Flutter 项目或引入现有代码库。

步骤 3.1：在 HiSH 内生成项目“桥接” Flutter 工具链需要创建 DevEco Studio 能够识别的原生 HarmonyOS 项目文件（ohos 文件夹）。

• 操作：在 HiSH 终端中，导航到共享文件夹内你期望的项目目录（例如 cd /mnt/shared/my_flutter_app ）。然后运行：bash

flutter create --platforms ohos .

• 此命令会生成 ohos 文件夹，它充当 Flutter 代码的原生包装器。关键的是，此文件夹生成在共享文件夹内，使其立即可被 HarmonyOS 文件系统和 DevEco Studio 看到。

步骤 3.2：导入您现有的 Flutter 代码（可选）

如果您已有 Flutter 项目，可以轻松将其迁移到 HarmonyOS 环境。

• 复制代码：使用 HarmonyOS 文件管理器或 HiSH 内的命令行，将现有的 lib/ 文件夹、assets/ 文件夹和 pubspec.yaml 文件复制到您刚初始化的项目根目录中（即包含 ohos 文件夹的那个项目）。

• 合并依赖：打开 pubspec.yaml 文件，确保添加了所有 OpenHarmony 专用插件（例如 flutter_ohos）。对于支持 OpenHarmony 的插件，您可能需要添加特定的 git 依赖。

• 解析依赖：在项目目录下的 HiSH 终端中运行 flutter pub get。这将下载您的包并更新 ohos 文件夹内的桥接文件，使其指向您现有的 Dart 逻辑。

阶段 4：签名、构建与部署（使用 DevEco Studio）

此阶段使用 HarmonyOS 上的原生 DevEco Studio IDE 来处理最终的签名和部署。由于您的项目位于共享文件夹中，HiSH 和 DevEco Studio 都可以无缝访问它。

步骤 4.1：将项目导入 DevEco Studio

• 操作：在您的 HarmonyOS PC 上打开 DevEco Studio。选择“Open Project”，导航到 Flutter 项目根目录下的 ohos 子文件夹（即您刚在共享文件夹中创建的那个）。点击“Open”。

步骤 4.2：执行“自动签名”握手 要使应用在真实设备上运行（您的 HarmonyOS PC 本身也算作设备），必须使用数字证书对其进行签名。

• 操作：在 DevEco Studio 中：转到 File > Project Structure > Project > Signing Configs。勾选“Automatically Generate Signature”复选框。在提示时使用您的华为开发者账号登录。点击“Apply”，然后点击“OK”。

• 工作原理：基于 Rust 的 IDE 将与 HarmonyOS 内核安全通信，为您的应用生成必要的安全证书和配置文件。

步骤 4.3：构建并运行您的 Flutter 应用 现在您已准备好在 HarmonyOS 设备上查看应用的运行效果。

• 操作：在 DevEco Studio 中，点击绿色的“Run”按钮。或者，您可以在 HiSH 终端的项目目录中运行 flutter run 命令。

• 完整流程说明：编译：如果您在 DevEco Studio 中点击“Run”，它将调用 Flutter 工具链。该工具链在 HiSH Linux 环境中运行，使用 BiSheng JDK 编译您的 Dart 代码并构建 .hap（HarmonyOS Ability Package）文件。检测与签名：DevEco Studio 检测共享项目文件夹中新构建的 .hap 文件。然后它将自动生成的签名配置文件应用到该包。部署与执行：最后，DevEco Studio 使用 HarmonyOS hdc 工具将已签名的 .hap 文件推送到您连接的 HarmonyOS PC（或手机/平板），并启动应用。

在日常工作流程中各组件如何协同工作

为了获得流畅的开发体验，你会像在传统操作系统上一样，针对不同任务使用不同的工具：

• CodeArts IDE（你的日常编码主力）：这是一个轻量级、受云原生启发的 IDE（类似于 VS Code）。你可以用它来完成编写所有 Dart 代码、管理项目文件夹结构以及编辑 UI 逻辑这些“重活”。由于你的项目位于共享文件夹中，CodeArts 可以直接打开并编辑它。

• DevEco Studio（部署与签名专家）：你主要会使用这个 IDE 来完成两个特定任务：生成应用的安全签名（每个项目一次），以及点击“Run”按钮将应用部署到你的设备上。你不需要在其中编写代码。

• HiSH（Linux 构建环境）：这是你运行所有 Flutter 命令行操作的地方：flutter pub get 用于获取依赖，flutter build hap 用于创建发布包，如果你更喜欢终端，甚至可以用 flutter run。HiSH 提供了 Flutter 工具链所需的必要类 Unix CLI 和完整的 Linux 内核。

• BiSheng JDK（构建引擎）：这是驱动 Flutter 内部构建工具的必要 Java 运行时，并且必须通过 flutter config --jdk-dir 正确链接。

按照这份修正后的指南，你可以使用 HiSH 在 OpenHarmony 上为 Flutter 建立一个自包含的原生开发环境。现在，你可以完全在 HarmonyOS PC、平板或手机上开发、构建和部署 Flutter 应用，而无需第二台机器或虚拟机。这是在现代非 Linux 操作系统上，遵循经典 Unix 哲学的真正原生开发。

关于本文的讨论

准备好了解更多了吗？

转载声明：本文为转载整理，原文版权归原作者及原站点所有。

原文来源：Harmony Developers Feed

原创地址：https://www.harmony-developers.com/p/setting-up-native-flutter-harmonyos