Min Browser 迁移适配鸿蒙 PC 平台完整教程

Min Browser 迁移适配鸿蒙 PC 平台完整教程

📖 前言

Min Browser 是一个在 GitHub 上拥有 20,000+ Stars 的开源项目，以其快速、最小化的设计和强大的隐私保护功能而广受开发者喜爱。作为一个专注于隐私保护的浏览器，Min Browser 不仅是一个优秀的应用，更是学习 Electron 开发和浏览器架构的绝佳案例。

随着鸿蒙 PC 作为新一代操作系统的崛起，我们看到了将 Min Browser 迁移到鸿蒙平台的机会。这不仅是一次技术迁移，更是对跨平台开发理念的深入实践。

先来看一下效果

image-20251120135317755

🌟 项目背景

Min Browser 简介

Min Browser 是一个基于 Electron 构建的快速、最小化浏览器，专注于保护用户隐私。项目在 GitHub 上获得了大量关注：

• ⭐ 20,000+ Stars - 深受开发者社区喜爱
• 🍴 1,500+ Forks - 大量开发者学习和贡献
• 📦 活跃维护 - 持续更新和优化
• 🌍 跨平台支持 - Windows、macOS、Linux

为什么选择 Min Browser？

1. 优秀的代码质量
   • 清晰的架构设计
   • 完善的文档和注释
   • 遵循最佳实践
2. 丰富的功能特性
   • 全文搜索
   • 广告拦截
   • 阅读模式
   • 任务管理（标签分组）
   • 书签标签
   • 密码管理器集成
3. 学习价值高
   • Electron 应用开发的最佳实践
   • 浏览器架构设计
   • 跨平台开发经验

项目地址

• GitHub: https://github.com/minbrowser/min[1]
• 官方网站: https://minbrowser.org/[2]

🚀 鸿蒙 PC 的优势

1. 新兴操作系统生态

鸿蒙 PC 作为华为推出的新一代操作系统，具有以下优势：

• 统一生态：与手机、平板、智能设备无缝协同
• 分布式能力：支持多设备协同工作
• 性能优化：针对 ARM 架构深度优化
• 安全可靠：企业级安全保障

2. 开发者友好

• 现代化开发工具：DevEco Studio 提供完整的开发体验
• ArkTS 语言：TypeScript 的超集，易于上手
• 丰富的 API：提供丰富的系统能力接口
• 活跃的社区：华为官方和开发者社区支持

3. 市场机遇

• 快速增长：鸿蒙设备数量快速增长
• 企业需求：越来越多的企业选择鸿蒙生态
• 开发者机会：早期进入者可以获得更多机会

💡 迁移适配的动机

1. 技术探索

将成熟的 Electron 应用迁移到新平台，是一次深入理解跨平台开发的机会：

• 架构理解：深入理解 Electron 的架构设计
• 平台差异：学习不同操作系统之间的差异
• 适配技巧：掌握跨平台适配的方法和技巧

2. 生态建设

• 丰富应用生态：为鸿蒙 PC 带来优秀的浏览器应用
• 技术积累：为后续项目积累经验
• 社区贡献：回馈开源社区

3. 学习价值

• 最佳实践：学习 Min Browser 的优秀设计
• 问题解决：在迁移过程中解决各种技术挑战
• 知识沉淀：形成完整的技术文档和教程

🏗️ 项目架构设计

双模块架构

项目采用了清晰的双模块架构：

ohos_hap/
├── electron/              # Electron 应用主模块
│   ├── libs/             # 原生 C++ 库
│   │   ├── libelectron.so    # Electron 核心库
│   │   ├── libadapter.so     # 适配器桥接库
│   │   ├── libffmpeg.so      # 多媒体支持
│   │   └── libc++_shared.so
│   └── src/main/ets/     # ArkTS 代码
│       ├── entryability/ # 各种 Ability 入口
│       └── pages/        # UI 页面
│
└── web_engine/           # Web 引擎适配层（HAR 库）
    └── src/main/ets/
        ├── adapter/      # 40+ 系统适配器
        ├── jsbindings/   # JS 绑定层
        ├── components/   # UI 组件
        └── ability/      # 基础 Ability 类

适配器模式

核心创新在于使用适配器模式来桥接 Electron API 和鸿蒙系统能力：

• 40+ 适配器：覆盖 Electron 应用所需的各种系统能力
• 统一接口：所有适配器继承 BaseAdapter
• 依赖注入：通过 InversifyJS 管理依赖关系

🐛 迁移过程中遇到的主要问题

问题 1：白屏问题

问题描述

应用启动后窗口正常打开，但内容为空白（白屏）。

根本原因

1. 缺少构建产物
   • 应用加载 dist/index.html
   • 需要通过 npm run build 生成
   • 没有构建就没有 dist/ 目录 → 白屏
2. 路径配置错误
   • Electron 应用代码路径不正确
   • main.js 中的路径配置有误

解决方案

# 1. 确保构建产物存在
cd web_engine/src/main/resources/resfile/resources/app
npm run build

# 2. 检查 main.js 中的路径配置
# 确保路径相对于应用根目录正确
win.loadFile('dist/index.html')  // ✅ 正确
win.loadFile('./dist/index.html') // ✅ 也可以

问题 2：窗口无法调整大小

问题描述

在鸿蒙 PC 上，某些 Electron 应用的窗口无法调整大小。

根本原因

缺少 webPreferences 配置：

// ❌ 问题代码：缺少 webPreferences
const win = new BrowserWindow({
width: 800,
height: 600,
});

// ✅ 正确代码：包含 webPreferences
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true,
    nodeIntegration: false
  }
});

技术原理

1. 适配层判断逻辑：libadapter.so 通过检查 webPreferences 来决定窗口特性
2. 默认值问题：缺少配置时，可能触发更严格的限制
3. 安全限制：缺少明确的安全配置可能触发额外的安全检查

解决方案

**始终配置 webPreferences**：

const { BrowserWindow } = require('electron');
const path = require('path');

function createWindow() {
const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
      enableRemoteModule: false
    }
  });

  win.loadFile('index.html');
}

问题 3：Dock 栏显示"打开新窗口"

问题描述

在鸿蒙 PC 的 dock 栏右键菜单中，会显示"打开新窗口"选项，对于单实例应用来说是不期望的行为。

根本原因

1. 系统默认行为：系统根据应用的 launchType 自动生成菜单项
2. 快捷方式配置：应用在 shortcuts_config.json 中定义的快捷方式

解决方案

多层配置 + 代码拦截：

应用级别配置（AppScope/app.json5）：

{
  "multiAppMode": {
    "multiAppModeType": "appClone",
    "maxCount": 1
  }
}

Ability 级别配置（electron/src/main/module.json5）：

{
  "launchType": "singleton"
}

清空快捷方式配置（shortcuts_config.json）：

{
  "shortcuts": []
}

代码层面拦截：

• WebAbilityStage.onAcceptWant() - 拦截窗口创建请求
• WebAbility.onNewWant() - 拦截新启动请求
• WebBaseAbility.onCreate() - 拦截创建请求

问题 4：菜单栏平台差异

问题描述

不同平台（macOS、Windows、Linux、鸿蒙）的菜单栏显示不一致，代码中大量平台判断逻辑。

根本原因

• 平台特性差异：不同平台的菜单栏行为不同
• 代码组织混乱：平台判断逻辑分散在各处
• 维护困难：添加新功能需要修改多处代码

解决方案

菜单栏重构：

模块化设计：

menu.js          # 主入口
menuConfig.js    # 配置集中管理
menuBuilder.js   # 构建逻辑

统一菜单结构：

• 所有平台使用相同的菜单结构
• 通过 role 属性或 click 处理器实现平台差异

配置与逻辑分离：

• 菜单项定义独立于构建逻辑
• 易于维护和扩展

重构效果：

• 代码量减少 90%
• 平台判断次数从 20+ 处减少到 0 处
• 可维护性大幅提升

问题 5：HAP 包体积过大

问题描述

构建的 HAP 包体积过大（超过 600MB），影响安装和分发。

根本原因

1. node_modules 目录：包含大量开发依赖（635MB+）
2. 源代码文件：未编译的源代码文件
3. 缓存文件：构建缓存和临时文件
4. 平台特定文件：不需要的文件被包含

解决方案

自动化清理脚本：

#!/bin/bash
# cleanup.sh

# 1. 删除 node_modules（最大问题）
rm -rf node_modules

# 2. 删除源代码目录
rm -rf src

# 3. 删除缓存文件
rm -rf .cache .parcel-cache

# 4. 删除测试文件
rm -rf test

# 5. 删除文档文件
rm -rf README.md CONTRIBUTING.md

**配置 .hvigorignore**：

# 排除不需要的文件
node_modules/
app/src/
app/package-lock.json
.cache/
.parcel-cache/
test/

优化效果：

• 包体积从 635MB+ 减少到 200MB 左右
• 减少 68% 的体积

问题 6：硬件加速问题

问题描述

在某些鸿蒙设备上，应用可能出现渲染问题或性能问题。

解决方案

在 main.js 中禁用硬件加速：

const { app } = require('electron');

// 禁用硬件加速
app.disableHardwareAcceleration();

// 在 Chromium 层面追加命令行开关
app.commandLine.appendSwitch('disable-gpu');

🔧 核心技术实现

1. 原生桥接层

libadapter.so 负责 ArkTS/ETS 代码与 C++ Electron 引擎之间的通信：

// JsBindingUtils.ets
import adapter from'libadapter.so';

exportdefaultclass JsBindingUtils {
static getNativeContext(contextType: number): NativeContext {
    return adapter.getNativeContext(contextType);
  }

static bindFunction(name: string, func: Function) {
    this.currentContext.JSBind.bindFunction(name, func);
  }
}

2. XComponent 渲染管道

Electron 的渲染输出通过鸿蒙的 XComponent 组件实现：

this.xComponent.initialize({
  id: this.config.moduleName,
  type: XComponentType.SURFACE,
  libraryname: "adapter"  // 关联 libadapter.so
});

3. 多进程架构

实现类似 Electron 的多进程模型：

{
  "abilities": [
    {
      "name": "EntryAbility",
      "launchType": "specified"  // 主进程
    },
    {
      "name": "BrowserAbility",
      "process": ":browser"      // 浏览器进程
    }
  ]
}

📊 迁移成果

功能完成度

性能指标

• 启动时间：< 3 秒
• 内存占用：< 500MB（正常使用）
• 包体积：~200MB（优化后）
• 兼容性：支持 HarmonyOS 6.0.0+

🎓 经验总结

1. 架构设计的重要性

• 适配器模式：有效解决平台差异问题
• 模块化设计：提高代码可维护性
• 依赖注入：实现松耦合的模块系统

2. 问题排查方法

• 日志分析：使用 hdc hilog 查看系统日志
• 代码追踪：从 Electron API 调用追踪到鸿蒙实现
• 对比测试：对比不同配置下的行为差异

3. 最佳实践

• 始终配置 webPreferences：避免窗口行为异常
• 单实例模式：合理配置应用实例数量
• 包体积优化：及时清理不需要的文件
• 代码重构：保持代码清晰和可维护

4. 文档的重要性

• 问题记录：详细记录遇到的问题和解决方案
• 技术博客：分享经验和最佳实践
• 代码注释：添加清晰的注释说明

🚀 快速开始

环境要求

• HarmonyOS SDK: 6.0.0 (API Level 20) 或更高版本
• DevEco Studio: 最新版本
• Node.js: 16.x 或更高版本

构建步骤

# 1. 克隆项目
git clone https://gitcode.com/nutpi/min_ohos.git
cd min_ohos

# 2. 安装依赖
cd web_engine/src/main/resources/resfile/resources/app
npm install

# 3. 构建应用
npm run build

# 4. 构建 HAP 包
cd ../../../../../../..
hvigor assembleHap --mode module -p module=electron@default

运行应用

1. 在 DevEco Studio 中打开项目
2. 连接鸿蒙 PC 设备或启动模拟器
3. 点击运行按钮

🤝 贡献与反馈

项目地址

• GitCode: https://gitcode.com/nutpi/min_ohos[3]
• GitHub: https://github.com/minbrowser/min[4] (原始项目)

如何贡献

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

问题反馈

如果遇到问题或有建议，欢迎：

• 提交 Issue[5]
• 参与讨论
• 贡献代码

📝 总结

将 Min Browser 迁移到鸿蒙 PC 平台是一次充满挑战和收获的技术探索。在这个过程中，我们：

1. 深入理解了 Electron 架构：从主进程到渲染进程，从窗口管理到系统集成
2. 掌握了跨平台适配技巧：适配器模式、依赖注入、原生桥接
3. 解决了大量实际问题：白屏、窗口配置、菜单栏、包体积等
4. 积累了丰富的经验：形成了完整的技术文档和最佳实践

这个项目不仅是一个应用迁移，更是对跨平台开发理念的深入实践。它证明了通过合理的架构设计和技术选型，可以在保持应用原有特性的同时，让其在全新的平台上焕发生机。

对于想要进入鸿蒙生态的开发者，这个项目提供了一个极好的参考案例，展示了如何系统性地解决平台差异问题，实现真正的跨平台兼容。

🌟 致谢

• Min Browser 团队：感谢提供优秀的开源项目
• Electron 社区：感谢 Electron 框架的支持
• 鸿蒙开发者社区：感谢技术支持和反馈
• 所有贡献者：感谢代码贡献和问题反馈

Made with ❤️ for HarmonyOS PC

如果本教程对你有帮助，欢迎 Star ⭐ 本项目！

参考资料

[1]

https://github.com/minbrowser/min: https://github.com/minbrowser/min

[2]

https://minbrowser.org/: https://minbrowser.org/

[3]

https://gitcode.com/nutpi/min_ohos: https://gitcode.com/nutpi/min_ohos

[4]

https://github.com/minbrowser/min: https://github.com/minbrowser/min

[5]

Issue: https://gitcode.com/nutpi/min_ohos/issues