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

本文基于DevEco Studio 6.0 + OpenHarmony SDK 20，先讲解Flutter鸿蒙开发核心基础、三方库适配原理，再带你从零完成一个可直接运行的Flutter鸿蒙实战案例，集成鸿蒙适配版三方库，包含设备信息获取、网络请求、界面展示，新手可一步步跟着操作，全程无复杂操作，快速入门Flutter+三方库+鸿蒙应用开发。

一、前置教学：核心基础入门

1.1 核心概念讲解

• Flutter-OH：并非官方Flutter，是开源鸿蒙社区适配的版本，支持将Flutter代码编译为鸿蒙HAP安装包，兼容OpenHarmony SDK，本文使用的是适配SDK20的稳定版本。

• 鸿蒙适配版三方库：普通Flutter三方库无法直接在鸿蒙设备上运行，需使用OpenHarmony-TPC社区适配后的版本，这类库已解决鸿蒙平台兼容性问题，可直接集成（本文选用最常用的设备信息和网络请求库）。

• DevEco Studio 6.0 + SDK20：DevEco 6.0是鸿蒙开发最新IDE，完美兼容Flutter-OH开发，SDK20是本文指定的目标API版本，所有操作均围绕此版本展开，不可替换为其他版本。

• 鸿蒙权限机制：鸿蒙应用获取设备信息、网络访问等功能，必须在配置文件中声明对应权限，否则应用会崩溃或功能失效，这是与普通Flutter开发最大的区别之一。

1.2 关键区别：Flutter鸿蒙开发 vs 普通Flutter开发

对比维度	普通Flutter开发	Flutter鸿蒙开发（SDK20）
Flutter版本	官方原版Flutter	社区适配版Flutter-OH
IDE	Android Studio/VS Code	DevEco Studio 6.0
三方库	普通Flutter三方库	鸿蒙适配版三方库（OpenHarmony-TPC）
配置文件	AndroidManifest.xml	module.json5（声明权限、应用信息）
打包产物	APK文件	HAP文件（鸿蒙应用标准格式）

1.3 三方库集成核心原则

1. 优先选择OpenHarmony-TPC社区维护的适配版三方库，避免使用未适配的库（会导致编译失败）；

2. 集成三方库时，需指定对应SDK20的适配分支，不可随意使用默认分支；

3. 集成后必须执行flutter pub get，确保依赖下载完整，若出现冲突，需检查三方库版本兼容性。

二、环境准备

2.1 所需软件与固定版本

• DevEco Studio 6.0（最新正式版，官网可直接下载）

• OpenHarmony SDK：API 20（必须此版本，适配Flutter-OH）

• Flutter-OH：鸿蒙适配版（3.35.7-dev分支，社区稳定版）

• 系统：Windows 10/11 或 macOS（macOS适配更流畅，Windows需注意环境变量配置）

2.2 安装DevEco Studio 6.0并配置SDK20

1. 下载DevEco Studio 6.0：访问鸿蒙官网，下载对应系统的安装包，双击安装（安装路径建议不要有中文、空格）；

2. 首次启动IDE：启动后会提示“配置SDK”，点击“Settings”进入设置界面；

3. 配置SDK：依次点击 System Settings → OpenHarmony SDK，在弹出的界面中，勾选“API 20”（取消其他API版本勾选，避免冲突），点击“Apply”开始下载安装，等待下载完成（约10-20分钟，取决于网络）；

4. 配置环境变量：

   • 新建系统环境变量：DEVECO_SDK_HOME，值为你的SDK安装路径（例：Windows路径：D:\DevEco\sdk；macOS路径：/Users/用户名/DevEco/sdk）；

   • 编辑Path环境变量，添加SDK工具链路径：Windows添加 %DEVECO_SDK_HOME%\default\openharmony\toolchains；macOS添加 $DEVECO_SDK_HOME/default/openharmony/toolchains；

   • 配置完成后，关闭IDE，重新启动（确保环境变量生效）。

2.3 获取并配置Flutter-OH

普通Flutter无法兼容鸿蒙SDK20，必须使用社区适配的Flutter-OH，步骤如下：

1. 打开终端（Windows：CMD/PowerShell；macOS：终端），执行以下命令，克隆Flutter-OH代码：

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

2. 进入克隆后的文件夹，切换到适配SDK20的稳定分支：

     cd flutter_flutter 
     git checkout 3.35.7-dev
   

3. 配置Flutter-OH环境变量：

   • 新建系统环境变量：FLUTTER_HOME，值为克隆后的flutter_flutter文件夹路径（例：Windows：D:\flutter_flutter；macOS：/Users/用户名/flutter_flutter）；

   • 编辑Path环境变量，添加 %FLUTTER_HOME%\bin（Windows）或 $FLUTTER_HOME/bin（macOS）；

4. 验证环境是否配置成功：

        `flutter doctor
flutter config --enable-harmonyos
flutter config --harmonyos-sdk-version 20

执行完成后，终端出现“HarmonyOS (API 20)”字样，且无报错，即为配置成功；若出现报错，检查环境变量路径是否正确，或重新启动终端。

三、实战案例：Flutter+三方库+鸿蒙SDK20 设备信息+网络请求Demo

本实战案例将集成两个最常用的鸿蒙适配版三方库：device_info_plus（获取鸿蒙设备信息）和 dio（发起网络请求），完成一个简单且实用的Demo，可直接运行在鸿蒙设备/模拟器上，全程手把手操作。

3.1 创建Flutter鸿蒙项目

1. 打开终端，执行以下命令，创建Flutter鸿蒙项目（项目名：flutter_oh_demo，可自定义，但建议保持一致，避免后续操作出错）：

        `flutter create --platforms ohos flutter_oh_demo`

3. 进入项目目录：cd flutter_oh_demo

4. 用DevEco Studio 6.0打开项目：打开DevEco Studio，点击“Open Project”，选择刚刚创建的flutter_oh_demo文件夹，等待IDE加载完成（首次加载会下载相关依赖，耐心等待）。

3.2 引入鸿蒙适配版三方库

本文选用的两个三方库均为OpenHarmony-TPC社区适配的SDK20版本，无需手动修改代码，直接集成即可，步骤如下：

1. 在DevEco Studio中，找到项目根目录下的 pubspec.yaml 文件，双击打开；

2. 在 dependencies 节点下，添加以下依赖（替换原有默认依赖，确保格式正确，缩进一致）：
   `dependencies:
   flutter:
   sdk: flutter

鸿蒙适配版设备信息库

device_info_plus:
  git:
    url: https://gitcode.com/openharmony-tpc/flutter_packages.git
    path: packages/device_info_plus/device_info_plus
    ref: br_device_info_plus-v9.0.1_ohos

鸿蒙适配版网络请求库

dio:
  git:
    url: https://gitcode.com/openharmony-tpc/flutter_packages.git
    path: packages/dio/dio
    ref: br_dio-v5.4.3+1_ohos`

3. 保存 pubspec.yaml 文件，然后在终端执行以下命令，下载依赖：
   flutter pub get若出现“pub get succeeded”，说明依赖下载成功；若出现冲突，检查依赖格式是否正确，或重新执行命令。

3.3 编写实战代码

本案例代码会实现两个核心功能：1. 启动应用自动获取鸿蒙设备信息（型号、系统版本等）；2. 点击按钮发起网络请求，展示请求结果。我们将替换 lib/main.dart 的全部内容，步骤如下：

1. 在DevEco Studio中，找到 lib 文件夹下的 main.dart 文件，双击打开；

2. 删除文件中的所有原有代码，复制粘贴以下完整代码：

`import 'package:flutter/material.dart';
import 'package:device_info_plus/device_info_plus.dart'; // 引入设备信息库
import 'package:dio/dio.dart'; // 引入网络请求库

void main() {
  // 启动应用
  runApp(const MyApp());
}

// 应用根组件
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter+三方库+鸿蒙SDK20 Demo',
      theme: ThemeData(primarySwatch: Colors.blue), // 应用主题色
      home: const MyHomePage(), // 应用首页
    );
  }
}

// 应用首页（带状态组件，可更新界面）
class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  // 初始化设备信息插件
  final DeviceInfoPlugin _deviceInfo = DeviceInfoPlugin();
  // 初始化dio网络请求实例
  final Dio _dio = Dio();

  // 存储设备信息（键值对形式）
  Map<String, dynamic> _deviceData = {};
  // 存储网络请求结果
  String _networkData = '';
  // 加载状态（控制加载动画显示/隐藏）
  bool _isLoading = false;

  // 方法：获取鸿蒙设备信息
  Future<void> _getDeviceInfo() async {
    try {
      // 调用设备信息插件，获取鸿蒙设备信息
      final deviceInfo = await _deviceInfo.deviceInfo;
      // 更新状态，刷新界面，展示设备信息
      setState(() {
        _deviceData = Map<String, dynamic>.from(deviceInfo.data);
      });
    } catch (e) {
      // 捕获异常，展示错误信息
      setState(() {
        _deviceData['error'] = e.toString();
      });
    }
  }

  // 方法：发起网络请求（测试接口：GitHub官网接口）
  Future<void> _requestNetwork() async {
    // 开始请求，显示加载动画
    setState(() => _isLoading = true);
    try {
      // 发起GET请求
      final response = await _dio.get('https://api.github.com');
      // 请求成功，存储状态码和响应数据
      setState(() {
        _networkData = '请求成功，状态码：' + response.statusCode.toString() + '\n' + '响应数据：' + response.data.toString();
      });
    } catch (e) {
      // 请求失败，存储错误信息
      setState(() {
        _networkData = '请求失败：$e';
      });
    } finally {
      // 请求结束，隐藏加载动画
      setState(() => _isLoading = false);
    }
  }

  // 组件初始化时，自动调用获取设备信息方法
  @override
  void initState() {
    super.initState();
    _getDeviceInfo();
  }

  // 构建界面（核心UI）
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      // 顶部导航栏
      appBar: AppBar(
        title: const Text('Flutter+三方库+鸿蒙SDK20'),
        centerTitle: true, // 标题居中
      ),
      // 主体内容（可滚动，避免内容溢出）
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16), // 内边距
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // 设备信息标题
            const Text(
              '鸿蒙设备信息（device_info_plus）',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 8), // 间距
            // 展示设备信息（循环遍历设备信息键值对）
            ..._deviceData.entries.map((e) => Padding(
              padding: const EdgeInsets.symmetric(vertical: 2),
              child: Text('${e.key}: ${e.value}'),
            )),
            const SizedBox(height: 20), // 间距
            // 网络请求标题
            const Text(
              '网络请求（dio）',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 8), // 间距
            // 发起网络请求按钮
            ElevatedButton(
              onPressed: _requestNetwork, // 点击触发请求方法
              child: const Text('发起网络请求（测试GitHub接口）'),
              style: ElevatedButton.styleFrom(
                padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 12),
                fontSize: 16,
              ),
            ),
            const SizedBox(height: 8), // 间距
            // 加载动画/请求结果展示
            _isLoading
                ? const CircularProgressIndicator() // 加载中，显示圆形动画
                : Text(
                    _networkData,
                    style: const TextStyle(fontSize: 14, color: Colors.grey[800]),
                  ),
          ],
        ),
      ),
    );
  }
}

3. 保存 main.dart 文件，此时IDE会自动检查代码格式，若出现红色报错，点击报错提示的“Fix”按钮，或重启IDE，即可解决（一般是依赖未加载完成导致）。

3.4 配置鸿蒙权限（关键步骤，缺一不可）

鸿蒙应用获取设备信息、访问网络，必须在配置文件中声明对应权限，否则应用启动后会崩溃，步骤如下：

1. 在DevEco Studio中，找到 ohos/entry/src/main 文件夹下的 module.json5 文件，双击打开；

2. 找到 module 节点下的 requestPermissions（若没有，手动添加），添加以下权限配置：
   "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, // 网络访问权限 { "name": "ohos.permission.GET_DEVICE_INFO" } // 获取设备信息权限 ]完整的 module 节点示例（参考）：
   "module": { "name": "entry", "type": "entry", "srcPath": "./src/main", "deviceTypes": ["phone", "tablet"], "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_DEVICE_INFO" } ] }

3. 保存 module.json5 文件，权限配置完成。

3.5 运行到鸿蒙设备/模拟器（最终验证）

配置完成后，即可将项目运行到鸿蒙设备或模拟器上，查看效果，步骤如下：

1. 准备运行环境：

   • 真机运行：打开鸿蒙手机/平板，进入“设置 → 关于手机”，连续点击“版本号”7次，开启开发者选项；然后进入“系统和更新 → 开发者选项”，开启“USB调试”和“USB安装”；用USB数据线将设备连接到电脑，电脑会自动安装设备驱动。

   • 模拟器运行：打开DevEco Studio，点击顶部“Tools → Device Manager”，创建API 20的鸿蒙模拟器（选择“Phone”类型，其他默认），启动模拟器。

2. 查看设备ID：打开终端，执行以下命令，查看已连接的鸿蒙设备/模拟器ID：
   flutter devices终端会显示设备名称和ID，例如：HarmonyOS Device (mobile) • 12345678 • ohos • HarmonyOS 4.0 (API 20)，其中“12345678”就是设备ID。

3. 运行项目：在终端执行以下命令（替换“你的设备ID”为实际获取的设备ID）：
   flutter run -d 你的设备ID执行命令后，会开始编译项目（首次编译时间较长，约5-10分钟，耐心等待），编译完成后，设备/模拟器上会自动安装并启动应用。

4. 查看运行效果：

   • 应用启动后，会自动获取并展示鸿蒙设备的型号、系统版本、设备ID等信息；

   • 点击“发起网络请求”按钮，会显示加载动画，请求成功后，展示请求状态码和响应数据；若请求失败，会显示错误信息。

3.6 编译生成鸿蒙HAP安装包

若需要将应用打包成鸿蒙HAP安装包，用于安装到其他鸿蒙设备，执行以下命令：

flutter build hap --release

打包完成后，HAP安装包的路径为：ohos/entry/build/default/outputs/default/entry-default-signed.hap，将此文件复制到鸿蒙设备，即可安装使用。

四、常见问题排查（新手必看）

• 问题1：编译失败，提示“找不到HarmonyOS SDK 20” → 检查环境变量 DEVECO_SDK_HOME 路径是否正确，重新配置后重启IDE。

• 问题2：运行后无法获取设备信息/网络请求失败 → 检查 module.json5 中是否添加了对应权限，或权限名称是否正确。

• 问题3：flutter pub get 失败 → 检查网络是否正常，或三方库的git地址是否正确，重新执行命令。

• 问题4：设备连接失败 → 检查USB调试是否开启，数据线是否支持数据传输，或重新连接设备。

五、核心知识点总结

1. Flutter鸿蒙开发必须使用 Flutter-OH（鸿蒙适配版），官方Flutter不支持鸿蒙SDK20；

2. 三方库必须选用 OpenHarmony-TPC社区适配版，并指定对应SDK20的分支；

3. 鸿蒙应用的权限配置是重点，必须在 module.json5 中声明所需权限；

4. DevEco Studio 6.0 + SDK20 是本文的固定版本，不可替换为其他版本，否则会出现兼容性问题；

5. 本案例的核心是“三方库集成+权限配置+基础UI编写”，掌握这三点，可快速上手其他Flutter鸿蒙项目。