Harmony PC 版从安装到首个应用开发全教程（附完整代码）

m0_59315734

2350人浏览 · 2026-02-07 20:17:58

m0_59315734 · 2026-02-07 20:17:58 发布

随着 OpenHarmony 生态的持续完善，基于 x86/ARM 架构的 PC 版 OpenHarmony 已实现基础桌面环境、多窗口支持等核心能力，成为国产操作系统在 PC 端的重要探索方向。本文将从OpenHarmony PC 版安装部署到首个原生应用开发、运行进行全流程教学，包含虚拟机 / 实体机安装步骤、开发环境配置及完整的 UI 应用代码，让新手也能快速上手鸿蒙 PC 开发。

一、OpenHarmony PC 版基础认知与安装准备

1.1 核心特性与适用设备

当前 OpenHarmony PC 版（基于 4.0 Release 及以上）已实现基础桌面环境、多窗口拖动、任务栏管理等 PC 端核心功能，同时支持 x86_64/ARM 架构，适配三类设备：

老旧 Intel/AMD 台式机 / 笔记本（Core i3/AMD 同等级及以上）
虚拟机（VirtualBox、VMware，适合快速试用）
开发板（树莓派、RK3568，适合嵌入式 + PC 跨端开发）

1.2 硬件与软件准备

硬件要求（x86 平台，最低 / 推荐）

硬件	最低配置	推荐配置
CPU	Intel i3/AMD 同等级	Intel i5/AMD Ryzen 5+
内存	4GB	8GB+
存储	16GB 可用空间	64GB SSD+
网络	RJ45 网口 / USB WiFi 网卡	千兆网口 + 双频 WiFi

软件准备

OpenHarmony 镜像：OpenHarmony 4.0 Release - x86_64（官网 / Gitee 下载，含openharmony-x86_64.img）
烧录工具：balenaEtcher（可视化）/dd 命令（命令行，适合 Linux/macOS）
虚拟机工具（可选）：VirtualBox 7.0+/VMware Workstation
开发工具：DevEco Studio 4.1+（鸿蒙官方开发 IDE，支持 PC 端应用开发）

二、OpenHarmony PC 版安装部署（两种方法）

方法一：虚拟机安装（推荐新手，无硬件风险）

适合快速试用、开发测试，资源开销小，可随时删除 / 切换系统，步骤以 VirtualBox 为例：

安装 VirtualBox 后，新建虚拟机：类型选择Linux，版本选择Other Linux (64-bit)；
配置资源：内存分配 4096MB（最低）/8192MB（推荐），虚拟硬盘 20GB（VDI 格式，动态分配）；
挂载镜像：虚拟机设置→存储→光驱，挂载下载的openharmony-x86_64.img，勾选「启动时连接」；
启动虚拟机：选择「Live 镜像模式」直接进入桌面（无需安装），或选择「安装模式」将系统部署到虚拟硬盘；
首次启动：默认进入图形化桌面，支持鼠标拖动、窗口缩放，基础任务栏 / 文件管理器可用。

方法二：实体机安装（适合正式部署，老旧电脑复活）

适合将 OpenHarmony 安装到物理电脑 / 开发板，步骤如下：

制作启动盘：将 U 盘（8GB+）格式化，用 balenaEtcher 选择openharmony-x86_64.img和目标 U 盘，一键烧录（Linux/macOS 可使用 dd 命令：sudo dd if=openharmony-x86_64.img of=/dev/sdX bs=4M status=progress，/dev/sdX为 U 盘实际路径）；
BIOS 设置 U 盘启动：启动电脑，按 F2/Del/F12 进入 BIOS，将「Boot Order」设置为 USB 启动优先，保存并重启；
系统安装：从 U 盘启动后，选择「安装模式」，按提示将 OpenHarmony 安装到硬盘分区（建议单独分区，避免覆盖原有系统）；
完成配置：设置用户名、密码，等待安装完成后重启，拔掉 U 盘即可进入 OpenHarmony PC 桌面。

安装常见问题解决

问题现象	解决方法
无法启动安装界面	检查镜像完整性，BIOS 切换为 UEFI 启动模式，关闭安全启动
键盘 / 鼠标无响应	切换 USB2.0/3.0 端口，或使用 PS/2 接口外设
网卡不识别	外接 USB 转 RJ45 千兆网卡，或手动编译对应网卡驱动
分辨率异常	修改启动参数开启高分辨率，或切换 VESA 兼容模式

三、鸿蒙 PC 开发环境配置（DevEco Studio）

安装完 OpenHarmony PC 版后，需配置 DevEco Studio 开发环境，支持鸿蒙 PC 原生应用的编写、编译、调试，核心步骤如下：

安装 DevEco Studio：OpenHarmony PC 版部分镜像已集成 DevEco Studio，若未集成可从官网下载并安装（兼容 x86_64 架构）；
配置 SDK：打开 DevEco Studio，进入 Setting→Appearance & Behavior→System Settings→HarmonyOS SDK，下载API 11（OpenHarmony 4.0） 及以上版本的 SDK，勾选PC/2in1设备支持；
配置模拟器 / 真机：
- 模拟器：在 DevEco Studio 中创建 OpenHarmony PC 模拟器（x86_64，内存 4GB+）；
- 真机：将 OpenHarmony PC 与电脑连接同一局域网，开启开发者模式（设置→关于本机→连续点击版本号 7 次），开启「USB 调试 / 网络调试」；
验证环境：新建项目后，若能正常编译并显示「BUILD SUCCESS」，则开发环境配置完成。

四、鸿蒙 PC 版首个原生应用开发（附完整代码）

本次开发一个基础桌面问候应用，基于 ArkTS 语言（鸿蒙主流开发语言），实现窗口布局、文字显示、按钮交互核心功能，适配 OpenHarmony PC 端的窗口特性，步骤从新建项目到运行全解析。

4.1 新建项目

打开 DevEco Studio，选择Create New Project；
模板选择Empty Ability（空应用），点击 Next；
项目配置：
- Project Name：OHPCFirstApp（自定义）；
- Bundle Name：com.ohpc.demo（反向域名格式）；
- Save Location：选择项目保存路径；
- Language：ArkTS；
- API Level：选择11（兼容 OpenHarmony 4.0 PC 版）；
- Device Type：勾选PC/2in1；
点击 Finish，等待项目初始化完成（自动下载依赖、生成目录结构）。

4.2 项目核心目录说明

OHPCFirstApp/
├── entry/                # 应用主模块
│   ├── src/main/
│   │   ├── arkts/        # ArkTS代码目录（核心开发目录）
│   │   │   ├── MainAbility/  # 应用能力入口
│   │   │   └── pages/        # 页面目录（编写UI和业务逻辑）
│   │   │       └── Index.ets # 首页（本次开发核心文件）
│   │   └── module.json5  # 应用配置文件（设备、权限、页面路由）
└── build-profile.json5   # 项目编译配置文件

4.3 编写核心代码（Index.ets）

修改pages/Index.ets文件，实现PC 端窗口适配、文字展示、按钮点击弹窗功能，代码带详细注释，适合新手理解：

// 导入鸿蒙核心API：弹窗、窗口管理（适配PC端）
import promptAction from '@ohos.promptAction';
import window from '@ohos.window';

// 入口组件：@Entry标记为应用入口，@Component为自定义组件
@Entry
@Component
struct Index {
  // 定义状态变量：用于存储问候语，支持双向绑定
  @State message: string = 'Hello OpenHarmony PC!';
  // 定义状态变量：记录按钮点击次数
  @State clickCount: number = 0;

  // 组件生命周期：页面加载完成后执行（PC端窗口适配核心）
  async aboutToAppear() {
    // 获取当前窗口实例，适配PC端窗口默认大小
    const win = await window.getCurrentWindow();
    // 设置PC端应用窗口默认尺寸（宽800px，高600px，符合PC使用习惯）
    win.resize(800, 600);
    // 设置窗口标题（PC端窗口标题栏显示）
    win.setTitle('我的首个鸿蒙PC应用');
  }

  // 自定义点击事件：按钮点击后执行
  onButtonClick() {
    // 状态变量自增，更新点击次数
    this.clickCount++;
    // 修改问候语，动态更新页面
    this.message = `你已点击${this.clickCount}次 | OpenHarmony PC开发`;
    // 弹出提示框（PC端原生弹窗，适配鸿蒙系统）
    promptAction.showToast({
      message: '点击成功！欢迎入坑鸿蒙PC开发',
      duration: 2000, // 弹窗显示2秒
      position: 'middle' // 弹窗居中显示（PC端推荐）
    });
  }

  // 构建UI布局：@Build标记为布局构建函数
  build() {
    // 根布局：Column垂直布局，适配PC端窗口100%宽高
    Column() {
      // 标题文字：适配PC端大屏显示
      Text(this.message)
        .fontSize(28) // 大字体，适合PC屏幕
        .fontWeight(FontWeight.Bold) // 文字加粗
        .margin({ top: 100, bottom: 50 }) // 上下边距，避免紧贴窗口
        .textAlign(TextAlign.Center) // 文字居中

      // 交互按钮：PC端适配鼠标悬浮、点击效果
      Button('点击我体验交互')
        .width(240) // 按钮宽度，适合PC鼠标点击
        .height(60) // 按钮高度
        .fontSize(20) // 按钮文字大小
        .backgroundColor('#007DFF') // 鸿蒙官方主色调
        .borderRadius(30) // 圆角按钮，提升美观度
        .hoverEffect(HoverEffect.Scale) // PC端鼠标悬浮缩放效果（核心适配）
        .onClick(() => this.onButtonClick()) // 绑定点击事件

      // 说明文字：辅助提示
      Text('OpenHarmony 4.0 PC版 | ArkTS开发')
        .fontSize(16)
        .color('#666666')
        .margin({ top: 80 })
    }
    // 根布局样式：占满整个PC窗口，内容居中
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#F5F7FA') // 浅灰色背景，符合PC端视觉体验
  }
}

4.4 配置应用模块（module.json5）

确保module.json5中开启PC/2in1设备支持，无需额外修改，默认配置如下（关键部分已标注）：

{
  "module": {
    "name": "entry",
    "type": "ability",
    "description": "$string:module_desc",
    "mainElement": "MainAbility",
    "deviceTypes": [
      "pc", // 开启PC设备支持
      "2in1" // 开启2in1设备支持
    ],
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/MainAbility/MainAbility.ts",
        "description": "$string:MainAbility_desc",
        "icon": "$media:icon",
        "label": "$string:MainAbility_label",
        "type": "page",
        "launchType": "standard"
      }
    ]
  }
}

五、应用编译与运行（PC 端）

5.1 编译项目

点击 DevEco Studio 顶部工具栏的Build→Build Project，等待编译完成，控制台显示BUILD SUCCESS即表示编译成功（若有报错，检查代码语法或 SDK 配置）。

5.2 运行到 OpenHarmony PC（两种方式）

方式 1：运行到 OpenHarmony PC 模拟器

点击 DevEco Studio 顶部「设备选择框」，选择Create Emulator；
模拟器配置：选择PC/2in1，API Level 11，内存 4GB+，创建并启动模拟器；
点击工具栏Run按钮，选择创建的 PC 模拟器，等待应用安装并运行。

方式 2：运行到 OpenHarmony PC 真机

将 OpenHarmony PC 真机与开发电脑连接同一局域网，获取真机 IP（设置→网络→WLAN→详情）；
在 DevEco Studio 中，点击「设备选择框」→Add Device→选择Network Device，输入真机 IP，完成设备连接；
点击Run按钮，选择连接的 PC 真机，应用将自动安装到 OpenHarmony PC 桌面并运行。

5.3 运行效果

应用将在 OpenHarmony PC 端以独立窗口形式显示，支持：

窗口拖动、缩放、最小化 / 最大化（符合 PC 端操作习惯）；
鼠标悬浮按钮时的缩放效果，点击按钮后动态更新文字并弹出原生弹窗；
窗口标题栏显示自定义标题「我的首个鸿蒙 PC 应用」。

六、进阶开发：PC 端核心特性适配（附代码片段）

本次开发的基础应用已适配 PC 端核心特性，若需进一步开发，可重点关注PC 端键鼠交互、多窗口、大屏布局，以下提供核心适配代码片段，直接复用即可：

6.1 PC 端鼠标悬浮效果（所有交互组件必加）

// 按钮、文本、卡片等组件添加hoverEffect，支持Scale/Opacity两种效果
Button('PC端悬浮按钮')
  .hoverEffect(HoverEffect.Scale) // 悬浮缩放
  // .hoverEffect(HoverEffect.Opacity) // 悬浮透明

6.2 PC 端键盘快捷键适配

// 给根布局绑定键盘事件，实现Ctrl+S快捷键触发保存
Column() {
  // 页面内容
}
.onKeyEvent((event) => {
  // 监听Ctrl+S按键
  if (event.keyCode === KeyCode.KEY_S && event.ctrlKey) {
    promptAction.showToast({ message: '触发Ctrl+S保存' });
    return true;
  }
  return false;
})

6.3 PC 端多列大屏布局（适配宽屏）

// 使用Grid实现PC端多列布局，适配大屏显示更多内容
Grid() {
  ForEach([1,2,3,4,5,6], (item) => {
    GridItem() {
      Text(`卡片${item}`)
        .width('100%')
        .height(120)
        .backgroundColor('#FFFFFF')
        .textAlign(TextAlign.Center)
        .fontSize(20)
        .borderRadius(8)
    }
  })
}
.columnsTemplate('1fr 1fr 1fr') // PC端3列布局
.columnGap(20) // 列间距
.rowGap(20) // 行间距
.padding(40)
.width('100%')

七、OpenHarmony PC 版开发常见问题与优化建议

7.1 常见开发问题

应用窗口无法缩放：在aboutToAppear中通过window.getCurrentWindow()获取窗口实例，开启窗口可缩放（默认支持）；
键鼠交互无响应：确保组件添加hoverEffect、focusable属性，PC 端默认支持键鼠焦点；
编译报错提示设备不支持：检查module.json5中deviceTypes是否勾选pc/2in1。