Flutter For OpenHarmony 鸿蒙 PC 开发入门：环境搭建 + 工程初始化（附 PC 端专属配置）

在鸿蒙PC生态开发中，Flutter凭借跨端一致性UI、高性能渲染优势，成为主流开发框架之一。本文基于鸿蒙PC开发官网规范（API Version 11+，适配鸿蒙PC 3.0及以上系统），从环境依赖准备、搭建流程、工程初始化、PC端专属配置到运行验证，全程拆解真实开发步骤，附可直接复用的配置代码与避坑指南。

一、核心前提与依赖清单

鸿蒙PC开发需满足特定软硬件与版本依赖，以下清单完全参照鸿蒙官网与Flutter For OpenHarmony官方适配文档整理，避免版本不兼容问题。

依赖项	版本要求	用途	官网获取路径
DevEco Studio	4.0及以上（稳定版）	鸿蒙应用开发主IDE，支持Flutter工程创建与调试	鸿蒙DevEco Studio官网
HarmonyOS SDK	API Version 11+（PC端最低支持版本）	提供鸿蒙PC端系统API、组件能力	DevEco Studio内直接下载（下文步骤详解）
Flutter SDK	3.13.0+（适配OpenHarmony专用版本）	Flutter核心框架，提供跨端UI渲染能力	Flutter官网 + 鸿蒙适配插件
Node.js	16.x ~ 18.x（LTS版）	Flutter工程构建依赖，处理npm包管理	Node.js官网
鸿蒙PC设备/模拟器	鸿蒙OS 3.0及以上	应用运行与调试载体	模拟器：DevEco Studio内创建；真机：开启开发者模式

关键提醒：Flutter For OpenHarmony需使用鸿蒙适配专用Flutter SDK，普通Flutter SDK无法对接鸿蒙PC端API，需通过DevEco Studio插件自动关联适配。

二、环境搭建完整流程（附官网适配步骤）

2.1 安装DevEco Studio并配置鸿蒙PC SDK

1. 安装DevEco Studio：下载后双击安装，勾选"OpenHarmony SDK""Flutter Plugin"组件（默认勾选，若未勾选需后续在插件市场补充安装），安装路径建议无中文、无空格（如：D:\DevEcoStudio）。

2. 下载鸿蒙PC SDK：

   1. 启动DevEco Studio，进入「File > Settings > Appearance & Behavior > System Settings > HarmonyOS SDK」。

   2. 切换至「Platforms」标签，勾选「OpenHarmony 11」（对应API 11），展开后需勾选「PC」相关组件（含PC端框架、API、工具链），点击「Apply」下载。

   3. 下载完成后，确认SDK路径（如：D:\DevEcoStudio\sdk\ohos），后续配置环境变量需用到。

3. 配置鸿蒙环境变量（Windows系统为例）：

   1. 右键「此电脑」>「属性」>「高级系统设置」>「环境变量」。

   2. 系统变量中新增「OHOS_SDK_HOME」，值为鸿蒙SDK路径（如上述D:\DevEcoStudio\sdk\ohos）。

   3. 编辑「Path」变量，添加「%OHOS_SDK_HOME%\toolchains」「%OHOS_SDK_HOME%\platforms\ohos-11\toolkit」，保存生效。

2.2 安装Flutter SDK并关联鸿蒙适配

1. 安装Flutter SDK：

   1. 从Flutter官网下载对应系统的SDK（3.13.0+），解压至无中文路径（如：D:\Flutter）。

   2. 配置Flutter环境变量：系统变量新增「FLUTTER_HOME」，值为SDK解压路径；Path变量添加「%FLUTTER_HOME%\bin」。

   3. 打开命令提示符（CMD），执行「flutter --version」，若输出Flutter版本信息则安装成功。

2. 安装Flutter For OpenHarmony适配插件：

   1. 启动DevEco Studio，进入「File > Settings > Plugins」，搜索「Flutter For OpenHarmony」，点击安装并重启IDE。

   2. 重启后，IDE会自动关联已安装的Flutter SDK与鸿蒙SDK，若未自动关联，可在「Settings > Languages & Frameworks > Flutter」中手动指定Flutter SDK路径。

2.3 安装Node.js并验证

下载Node.js 16.x ~ 18.x LTS版，默认安装（勾选"Add to PATH"），安装完成后打开CMD，执行以下命令验证：

# 验证Node.js版本 node -v # 验证npm版本 npm -v

若均输出对应版本号，说明安装成功。

2.4 环境校验（关键步骤）

打开CMD，执行鸿蒙PC开发专属校验命令（参照官网文档），确保所有依赖适配正常：

# 校验鸿蒙环境 ohos build -h # 校验Flutter与鸿蒙关联 flutter ohos doctor

若输出"All checks passed!"，则环境搭建完成；若存在报错，根据提示补充依赖（如缺失工具链则重新下载SDK组件）。

三、鸿蒙PC工程初始化（两种方式）

支持「DevEco Studio图形化创建」和「Flutter命令行创建」两种方式，前者适合零基础开发者，后者适合习惯命令行操作的开发者，均为官网推荐流程。

3.1 方式一：DevEco Studio图形化创建（推荐）

1. 启动DevEco Studio，点击「Create Project」，选择「Flutter For OpenHarmony」模板，点击「Next」。

2. 配置项目基础信息（严格遵循鸿蒙命名规范）：

   1. Project Name：项目名称（如：flutter_ohos_pc_demo，小写字母+下划线）。

   2. Package Name：应用包名（如：com.example.flutterohospcdemo，需唯一，遵循反向域名规则）。

   3. Save Location：项目保存路径（无中文、无空格）。

   4. Flutter SDK Path：自动填充已配置的路径，无需修改。

   5. Minimum API Level：选择11（鸿蒙PC端最低支持版本）。

   6. Device Type：勾选「PC」（核心！区别于移动端，仅勾选PC即可）。

3. 点击「Finish」，IDE自动初始化工程，下载依赖包（首次创建需等待几分钟，取决于网络速度）。

3.2 方式二：Flutter命令行创建

# 进入目标目录 
cd D:\Projects 
# 创建Flutter For OpenHarmony PC工程 
flutter create --template=ohos --device-type=pc flutter_ohos_pc_demo 
# 进入工程目录 
cd flutter_ohos_pc_demo 
# 用DevEco Studio打开工程 devecostudio .

命令说明：「--device-type=pc」指定工程为鸿蒙PC端，若不指定则默认创建移动端工程，无法适配PC端窗口与组件。

四、鸿蒙PC端专属配置（核心区别于移动端）

鸿蒙PC端与移动端在窗口尺寸、交互方式（键鼠为主）、组件适配等方面差异显著，需针对性配置，以下配置均参照鸿蒙PC开发官网规范编写。

4.1 工程配置文件（config.json）PC专属设置

路径：entry > src > main > config.json，该文件是鸿蒙应用核心配置文件，PC端需修改以下关键节点：

{
  "app": {
    "bundleName": "com.example.flutterohospcdemo",
    "vendor": "example",
    "version": {
      "code": 1000000,
      "name": "1.0.0"
    }
  },
  "module": {
    "name": "entry",
    "type": "entry",
    "srcPath": "./src/main/ets",
    "deviceType": ["pc"], // 仅保留PC，移除mobile、tv等其他设备类型
    "minAPIVersion": 11,
    "abilities": [
      {
        "name": ".MainAbility",
        "type": "page",
        "launchType": "standard",
        "orientation": "unspecified", // PC端支持横竖屏自适应
        "windowMode": "windowed", // PC端默认窗口模式（可切换为fullscreen）
        "defaultWidth": 1280, // PC端默认窗口宽度（适配2K屏）
        "defaultHeight": 720, // PC端默认窗口高度
        "resizable": true, // 允许窗口缩放（PC端必备）
        "icon": "$media:icon",
        "label": "$string:app_name"
      }
    ],
    // PC端权限配置（示例：文件读写权限）
    "reqPermissions": [
      {
        "name": "ohos.permission.READ_USER_STORAGE",
        "reason": "读取本地文件",
        "usedScene": {
          "ability": [".MainAbility"],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.WRITE_USER_STORAGE",
        "reason": "写入本地文件",
        "usedScene": {
          "ability": [".MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

关键说明：

• 「deviceType」仅保留「pc」，避免适配其他设备导致冲突。

• 「defaultWidth/defaultHeight」建议设置为1280x720（PC端主流基础分辨率），支持窗口缩放后自适应。

• 「resizable」设为true，允许用户拖动窗口边缘调整大小（PC端核心交互需求）。

4.2 Flutter层PC端布局适配（大屏适配）

鸿蒙PC端为大屏设备，需避免移动端小屏布局拉伸变形，采用Flutter响应式布局适配，示例代码（路径：lib > main.dart）：

import 'package:flutter/material.dart';
import 'package:flutter_ohos/flutter_ohos.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter OHOS PC Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyHomePage(),
      // PC端鼠标悬停支持（开启后组件可响应鼠标悬停事件）
      scrollBehavior: const MaterialScrollBehavior().copyWith(
        dragDevices: {PointerDeviceKind.mouse, PointerDeviceKind.touch},
      ),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    // 适配PC大屏：通过MediaQuery获取窗口尺寸，动态调整布局
    final screenWidth = MediaQuery.of(context).size.width;
    final screenHeight = MediaQuery.of(context).size.height;

    return Scaffold(
      appBar: AppBar(
        title: const Text('鸿蒙PC Flutter Demo'),
        // PC端标题栏高度适配（比移动端略高）
        toolbarHeight: 48,
      ),
      body: LayoutBuilder(
        builder: (context, constraints) {
          // 大屏布局：宽度足够时采用左右分栏，不足时垂直排列
          if (constraints.maxWidth > 800) {
            return Row(
              children: [
                // 左侧导航栏（占比25%）
                Container(
                  width: constraints.maxWidth * 0.25,
                  color: Colors.grey[200],
                  child: const Center(child: Text('PC端左侧导航')),
                ),
                // 右侧内容区（占比75%）
                Container(
                  width: constraints.maxWidth * 0.75,
                  child: const Center(child: Text('PC端右侧内容区')),
                ),
              ],
            );
          } else {
            return Column(
              children: [
                Container(
                  height: 60,
                  color: Colors.grey[200],
                  child: const Center(child: Text('PC端顶部导航')),
                ),
                Expanded(
                  child: Container(
                    child: const Center(child: Text('PC端内容区')),
                  ),
                ),
              ],
            );
          }
        },
      ),
    );
  }
}
      

适配要点：

• 开启鼠标悬停支持：通过「scrollBehavior」配置，让Flutter组件响应PC端鼠标事件。

• 响应式布局：用「LayoutBuilder」「MediaQuery」动态调整布局结构，适配不同PC分辨率（2K/4K屏）。

• 组件尺寸适配：PC端控件（按钮、字体）尺寸需比移动端略大，提升大屏操作体验。

五、应用运行与调试（PC端专属流程）

5.1 启动鸿蒙PC模拟器/连接真机

1. 模拟器启动：

   1. 在DevEco Studio工具栏，点击「Device Manager」（设备管理器）。

   2. 点击「Create Device」，选择「OpenHarmony」>「PC」，选择分辨率（推荐1280x720），点击「Finish」创建。

   3. 选中创建的PC模拟器，点击「Start」启动（首次启动需等待几分钟，占用内存较大，建议电脑内存≥16G）。

2. 真机连接：

   1. 将鸿蒙PC设备通过USB线连接电脑，开启设备「开发者模式」（设置 > 关于本机 > 连续点击版本号7次）。

   2. 在设备开发者选项中，开启「USB调试」「允许USB安装应用」。

   3. DevEco Studio自动识别设备，在工具栏设备列表中选择对应PC设备。

5.2 运行应用

1. 在DevEco Studio工具栏，点击「Run 'entry'」（绿色三角按钮），或使用快捷键「Shift+F10」。

2. IDE自动编译工程，生成HAP安装包并安装到PC模拟器/真机，编译成功后自动启动应用。

3. 验证效果：应用启动后显示默认窗口（1280x720），可拖动边缘缩放窗口，布局自动适配；鼠标悬停时组件响应正常。

六、常见问题与避坑指南（基于官网FAQ）

问题现象	原因分析	解决方案
工程创建失败，提示"Flutter SDK not found"	Flutter SDK路径未正确配置，或DevEco Studio未关联	1. 重新配置FLUTTER_HOME环境变量；2. 在DevEco Studio「Settings > Flutter」中手动指定SDK路径
PC模拟器启动失败，提示"内存不足"	模拟器默认内存配置过高（建议2G），电脑剩余内存不足	在设备管理器中，编辑模拟器配置，将内存调整为1.5G，关闭其他占用内存的程序
应用运行后无窗口显示，仅在任务栏出现图标	config.json中「defaultWidth/defaultHeight」配置为0，或窗口模式错误	检查config.json，设置合理的默认宽高，确保「windowMode」为「windowed」
鼠标悬停无响应，滚动异常	Flutter层未开启鼠标设备支持	在MaterialApp中配置scrollBehavior，添加PointerDeviceKind.mouse支持（参照4.2节代码）

七、后续学习方向（官网推荐路径）

1. 深入学习鸿蒙PC端API：重点掌握窗口管理、键鼠交互、文件系统等PC专属能力（参考鸿蒙PC API文档）。

2. Flutter与鸿蒙原生交互：通过MethodChannel调用鸿蒙PC端原生服务（如系统通知、打印机适配）。

3. PC端性能优化：针对Flutter渲染、窗口缩放、大数据列表加载等场景优化性能。

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

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/