欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net
零基础入门实战教：Flutter 入门、三方库实战与鸿蒙开发全流程实战

文档前言

本文档为从零到一的完整实战教程，聚焦 Flutter 跨平台开发核心场景，涵盖环境搭建、基础项目开发、常用三方库落地、Flutter 项目适配鸿蒙（HarmonyOS）设备全流程。文档所有步骤均附带具体操作指令、代码示例、注意事项，读者可直接跟随步骤完成项目实践，最终实现一个可运行在鸿蒙设备上的 Flutter 跨端应用。
一、Flutter 开发环境搭建（Windows 系统）

1.1 前置依赖软件安装

1.1.1 安装 Git

1. 下载地址：Git 官网 Windows 版

2. 安装步骤：双击安装包，全程点击「下一步」，保持默认配置无需修改

3. 验证安装：按下 Win+R 输入 cmd 打开命令提示符，执行命令：
   git --version
   若输出 Git 版本号（如 git version 2.43.0.windows.1），即为安装成功。

1.1.2 安装 Android Studio

1. 下载地址：Android 官方开发者平台

2. 安装核心配置：

◦ 安装界面勾选 Android Studio、Android SDK、Android Virtual Device 三个选项

◦ 安装路径选择非系统盘（如 D:\Android\Android Studio），避免中文和空格

3. 初始化配置：

◦ 打开 Android Studio，跟随向导完成下载最新版 Android SDK 组件

◦ 确保 SDK 版本包含 API 33 及以上（Flutter 稳定兼容版本）

4. 验证：安装完成后，软件可正常启动且无报错提示，即为安装成功。

1.1.3 配置 JDK 环境

1. 版本要求：JDK 11 或 JDK 17（Flutter 3.13+ 稳定兼容版本）

2. 下载地址：Oracle 官方 JDK 下载页

3. 环境变量配置步骤：

◦ 右键「此电脑」→ 选择「属性」→ 点击「高级系统设置」→ 打开「环境变量」

◦ 新建系统变量：变量名 JAVA_HOME，变量值为 JDK 安装根路径（如 C:\Program Files\Java\jdk-17.0.10）

◦ 编辑系统变量 Path，新增路径：%JAVA_HOME%\bin

4. 验证：重新打开 CMD 窗口，执行命令：
   java -version
   输出 JDK 版本号即为配置成功。

1.2 安装 Flutter SDK 并配置环境

1.2.1 下载并解压 Flutter SDK

1. 下载地址：Flutter 官方 Windows 安装指南

2. 解压要求：将压缩包解压至无中文、无空格的路径（如 D:\flutter），严禁解压到 C 盘系统目录

3. 路径注意事项：避免出现类似 D:\flutter 开发\sdk 这类含空格或中文的路径，防止编译报错。

1.2.2 配置系统环境变量

1. 打开「系统环境变量」配置面板，找到系统变量 Path

2. 新增路径：D:\flutter\bin（替换为你的 Flutter 解压路径）

3. 生效配置：关闭所有已打开的 CMD、PowerShell 窗口，重新打开以加载环境变量。

1.2.3 验证 Flutter 环境完整性

1. 执行版本验证命令：
   flutter --version
   输出 Flutter 版本、Dart 版本信息即为 SDK 配置成功。

2. 执行环境检测命令（核心步骤）：
   flutter doctor

3. 报错修复指南：

◦ 若提示 Android license status unknown：执行命令 flutter doctor --android-licenses，全程输入 y 同意许可

◦ 若提示缺失模拟器组件：打开 Android Studio → 进入 Settings -> Appearance & Behavior -> System Settings -> Android SDK，勾选对应 SDK 平台并下载

◦ 直到所有检测项显示「✓」，环境搭建完成。
二、创建并运行第一个 Flutter 项目

2.1 创建 Flutter 基础项目

1. 新建项目工作目录：例如 D:\flutter_projects（路径无中文、无空格）

2. 打开 CMD，切换至工作目录：
   cd D:\flutter_projects

3. 执行项目创建命令：
   flutter create flutter_harmony_demo

4. 等待命令执行完成，CMD 输出 Created project flutter_harmony_demo 即为项目创建成功

5. 进入项目目录：
   cd flutter_harmony_demo
   2.2 运行项目（安卓/鸿蒙真机调试）

6. 设备准备：

◦ 安卓/鸿蒙手机打开「设置」→ 找到「关于手机」→ 连续点击「版本号」7 次开启「开发者选项」

◦ 进入「开发者选项」，开启 USB 调试、USB 安装权限；鸿蒙设备额外开启「调试（安全设置）」权限

2. 连接设备：用原装数据线连接电脑与手机，手机端选择「文件传输模式（MTP）」

3. 执行运行命令：
   flutter run

4. 成功验证：

◦ CMD 输出 Running flutter_harmony_demo on 小米 2210132C（设备名）

◦ 手机自动安装 Flutter Demo 应用，页面显示「计数器」功能，即为项目运行成功。
三、Flutter 常用三方库实战落地

3.1 三方库通用使用规则

所有 Flutter 三方库均遵循统一使用流程，步骤如下：

1. 打开项目根目录下的 pubspec.yaml 配置文件

2. 在 dependencies 节点下添加库名称 + 版本号（YAML 格式严格遵守缩进，2 空格为一级）

3. 保存 pubspec.yaml，执行命令拉取依赖：
   flutter pub get

4. 在 Dart 代码文件中通过 import ‘包名’; 引入库，即可调用相关功能。

3.2 高频三方库详细实战（4 类核心库）

3.2.1 网络请求库：dio（替代原生 http）

适用场景：接口请求、数据获取、文件下载，是 Flutter 开发最常用的网络库。

1. 配置 pubspec.yaml：
   dependencies:
   flutter:
   sdk: flutter

网络请求库 dio，指定最新稳定版本

dio: ^5.7.0
2. 执行拉取依赖：
flutter pub get
3. 实战代码示例（在 lib/main.dart 中替换原有内容）：
import ‘package:flutter/material.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 Dio 实战’,
theme: ThemeData(primarySwatch: Colors.blue),
home: const NetRequestPage(),
);
}
}

class NetRequestPage extends StatefulWidget {
const NetRequestPage({super.key});

@override
State createState() => _NetRequestPageState();
}

class _NetRequestPageState extends State {
String _result = “点击按钮请求数据”;
final Dio _dio = Dio();

// 发起 GET 请求
Future fetchData() async {
try {
final response = await _dio.get(‘https://jsonplaceholder.typicode.com/todos/1’);
setState(() {
_result = “请求成功：\nKaTeX parse error: Expected 'EOF', got '}' at position 36: …ing()}"; }̲); } catch …e”;
});
}
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text(“Dio 网络请求”)),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text(_result),
const SizedBox(height: 20),
ElevatedButton(
onPressed: fetchData,
child: const Text(“发起网络请求”),
),
],
),
),
);
}
}
4. 运行验证：点击按钮，页面显示接口返回数据，即为三方库使用成功。

3.2.2 本地存储库：shared_preferences（轻量级存储）

适用场景：存储用户登录信息、配置项、缓存数据，支持 String/Int/Bool 等类型。

1. 配置 pubspec.yaml：
   dependencies:
   flutter:
   sdk: flutter
   shared_preferences: ^2.3.2
2. 实战代码示例（新增页面 StoragePage 并在主页面跳转）：
   // 在 main.dart 中添加存储页面
   class StoragePage extends StatefulWidget {
   const StoragePage({super.key});

@override
State createState() => _StoragePageState();
}

class _StoragePageState extends State {
final TextEditingController _nameController = TextEditingController();
String _storedName = “未存储”;

// 存储数据
Future saveData() async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(‘user_name’, _nameController.text);
_nameController.clear();
readData(); // 存储后刷新显示
}

// 读取数据
Future readData() async {
final prefs = await SharedPreferences.getInstance();
String? name = prefs.getString(‘user_name’);
setState(() {
_storedName = name ?? “未存储”;
});
}

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text(“本地存储实战”)),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
children: [
TextField(
controller: _nameController,
decoration: const InputDecoration(labelText: “输入用户名”),
),
const SizedBox(height: 10),
ElevatedButton(onPressed: saveData, child: const Text(“存储数据”)),
const SizedBox(height: 10),
Text(“已存储用户名：$_storedName”),
],
),
),
);
}
}
3. 集成至主页面：在 MyApp 的 home 改为包含两个按钮的主页，分别跳转网络请求和存储页面。

3.2.3 网络图片缓存库：cached_network_image（优化图片加载）

适用场景：列表图片、详情页图片，支持缓存、占位图、失败占位图，避免重复加载。

1. 配置 pubspec.yaml：
   dependencies:
   flutter:
   sdk: flutter
   cached_network_image: ^3.4.1
2. 实战代码示例：
   class ImagePage extends StatelessWidget {
   const ImagePage({super.key});

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text(“图片缓存实战”)),
body: Center(
child: CachedNetworkImage(
imageUrl: “https://picsum.photos/300/400”, // 测试图片地址
width: 300,
height: 400,
fit: BoxFit.cover,
// 加载中占位符
placeholder: (context, url) => const CircularProgressIndicator(color: Colors.blue),
// 加载失败占位符
errorWidget: (context, url, error) => const Icon(Icons.broken_image, size: 50, color: Colors.grey),
),
),
);
}
}
3.2.4 屏幕适配库：flutter_screenutil（多端兼容）

适用场景：解决不同分辨率手机/平板的布局错乱问题，支持宽高、字体自适应。

1. 配置 pubspec.yaml：
   dependencies:
   flutter:
   sdk: flutter
   flutter_screenutil: ^5.9.3
2. 入口初始化（修改 main.dart 的 main 函数）：
   void main() {
   runApp(
   ScreenUtilInit(
   // 设计稿尺寸（按 UI 设计图填写，常用 375*812）
   designSize: const Size(375, 812),
   minTextAdapt: true,
   splitScreenMode: true,
   builder: (context, child) {
   return MaterialApp(
   title: ‘Flutter 屏幕适配’,
   theme: ThemeData(primarySwatch: Colors.blue),
   home: const AdaptPage(),
   );
   },
   ),
   );
   }
3. 实战使用（新增 AdaptPage）：
   class AdaptPage extends StatelessWidget {
   const AdaptPage({super.key});

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text(“屏幕适配实战”)),
body: Center(
child: Container(
width: 200.w, // 适配宽度
height: 100.h, // 适配高度
color: Colors.blue,
child: Center(
text: Text(
“适配文字”,
style: TextStyle(fontSize: 16.sp), // 适配字体
),
),
),
),
);
}
}
四、Flutter 项目适配鸿蒙（HarmonyOS）开发全流程

4.1 安装鸿蒙开发环境

1. 下载 DevEco Studio：华为 DevEco Studio 官网

2. 安装步骤：全程点击「下一步」，保持默认配置

3. 初始化配置：

◦ 打开 DevEco Studio，跟随向导下载 HarmonyOS SDK（API 9 及以上版本）

◦ 确保安装「HarmonyOS SDK Platform」和「HarmonyOS SDK Tools」核心组件。

4.2 开启 Flutter 鸿蒙支持

1. 关闭已打开的 Flutter 项目，打开 CMD 执行命令：
   flutter config --enable-harmonyos
2. 验证鸿蒙支持：执行命令：
   flutter devices
   若输出 Huawei Device (oh) 或 PHH-AL00 (oh)，即为鸿蒙支持开启成功。

4.3 适配现有 Flutter 项目并运行到鸿蒙真机

1. 进入之前创建的 Flutter 项目目录：
   cd D:\flutter_projects\flutter_harmony_demo

2. 生成鸿蒙工程配置文件：
   flutter create .
   命令执行完成后，项目根目录会生成 ohos 文件夹，包含鸿蒙工程配置。

3. 鸿蒙真机准备：

◦ 确保鸿蒙手机已开启 USB 调试、USB 安装权限

◦ 连接电脑，选择「文件传输模式」

4. 运行到鸿蒙设备：
   flutter run -d oh
5. 成功验证：

◦ CMD 输出 Running flutter_harmony_demo on PHH-AL00 (oh)

◦ 鸿蒙手机自动安装应用并启动，页面显示 Flutter 计数器，即为适配成功。

4.4 鸿蒙应用打包（Release 正式包）

1. 执行打包命令：
   flutter build ohos --release
2. 打包结果：

◦ 生成的 .hap 安装包路径为：项目根目录\build\ohos\outputs\hap\release\entry-hap.hap

3. 安装验证：将 .hap 包拷贝至鸿蒙手机，点击安装即可运行正式版