鸿蒙 PC 适配：Electron + Vue3 现代安全开发实战（兼容鸿蒙 PC/Windows/macOS/Linux）

雨季666

419人浏览 · 2025-11-27 22:07:06

雨季666 · 2025-11-27 22:07:06 发布

一、核心前置：现代 Electron 安全原则（适配鸿蒙 PC）

Electron 团队在新版本中强烈建议的安全准则，同样适用于鸿蒙 PC 环境下的开发，是保障鸿蒙 PC 应用安全性的核心基础：

禁用 nodeIntegration：避免渲染进程直接访问 Node.js API，降低鸿蒙 PC 系统下的安全风险；
开启 contextIsolation：隔离主进程和渲染进程的上下文，防止原型链污染，适配鸿蒙 PC 的权限管控机制；
使用预加载脚本（preload）：作为主 / 渲染进程的安全通信桥梁，仅暴露必要的 API，符合鸿蒙 PC 的应用安全规范；
限制 webSecurity：仅在开发阶段临时关闭，生产环境必须开启，适配鸿蒙 PC 的网络安全策略。

这是本文鸿蒙 PC 适配案例的核心配置准则，区别于入门级的 “全开放” 写法，同时兼顾鸿蒙 PC 的系统特性。

二、环境准备（适配鸿蒙 PC）

1. 初始化项目（Vite + Vue3 + Electron，兼容鸿蒙 PC）

我们使用 electron-vite 快速搭建集成 Vue3 的项目（无需手动配置 Vite 和 Electron 联动），该脚手架生成的项目结构天然适配鸿蒙 PC 的 Linux 子系统运行环境：

# 创建项目
npm create electron-vite@latest electron-vue3-harmonypc-demo -- --template vue
# 进入项目目录
cd electron-vue3-harmonypc-demo
# 安装依赖（适配鸿蒙PC Linux 子系统依赖解析规则）
npm install --registry=https://registry.npmmirror.com

项目结构说明（关键文件，适配鸿蒙 PC 目录规范）：

electron-vue3-harmonypc-demo/
├── electron/                # Electron 主进程目录（鸿蒙PC核心适配区）
│   ├── main/                # 主进程代码（含鸿蒙PC托盘/通知适配）
│   │   └── index.js         # 主进程入口
│   └── preload/             # 预加载脚本目录（鸿蒙PC通信安全层）
│       └── index.js         # 预加载脚本入口
├── src/                     # Vue3 渲染进程代码（适配鸿蒙PC显示）
│   ├── App.vue              # 根组件
│   └── main.js              # Vue 入口
├── index.html               # 渲染进程入口 HTML
└── package.json             # 项目配置（含鸿蒙PC打包规则）

2. 核心依赖版本（鸿蒙 PC 兼容性最佳）

本文案例基于以下版本，经测试可稳定运行在鸿蒙 PC（OpenHarmony 4.0+）Linux 子系统：

Electron：^29.0.0（适配鸿蒙 PC Linux 子系统内核）
Vue：^3.3.0
Vite：^5.0.0
electron-vite：^2.0.0

三、实战 1：搭建安全的主进程与预加载脚本（适配鸿蒙 PC）

1. 主进程配置（electron/main/index.js，新增鸿蒙 PC 适配）

核心实现窗口创建、托盘初始化、IPC 监听，全程遵循安全原则，同时适配鸿蒙 PC 的系统特性：

const { app, BrowserWindow, ipcMain, Tray, Menu, Notification } = require('electron');
const path = require('node:path');
const os = require('node:os');

// 全局变量：主窗口、托盘实例
let mainWindow = null;
let tray = null;

// 判断是否为鸿蒙PC环境
const isHarmonyPC = () => {
  return process.env.OS === 'OpenHarmony' || process.env.OS === 'HarmonyOS' || os.release().includes('harmony');
};

// 创建主窗口（适配鸿蒙PC窗口渲染规则）
const createWindow = () => {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    // 禁用窗口缩放（鸿蒙PC默认推荐）
    resizable: true,
    // 安全配置核心（鸿蒙PC强制要求）
    webPreferences: {
      // 开启上下文隔离（必须）
      contextIsolation: true,
      // 禁用 Node.js 直接集成（必须）
      nodeIntegration: false,
      // 预加载脚本：唯一的通信桥梁
      preload: path.join(__dirname, '../preload/index.js'),
      // 生产环境开启 webSecurity（鸿蒙PC网络安全要求）
      webSecurity: process.env.NODE_ENV !== 'development',
      // 禁用远程模块（Electron 14+ 已移除，鸿蒙PC不兼容）
      enableRemoteModule: false
    },
    // 鸿蒙PC窗口样式适配
    titleBarStyle: isHarmonyPC() ? 'default' : 'hiddenInset'
  });

  // 加载页面：开发环境加载 Vite 开发服务器，生产环境加载打包后的 HTML
  if (process.env.VITE_DEV_SERVER_URL) {
    mainWindow.loadURL(process.env.VITE_DEV_SERVER_URL);
    // 开发环境打开开发者工具（鸿蒙PC支持）
    mainWindow.webContents.openDevTools();
  } else {
    mainWindow.loadFile(path.join(__dirname, '../../dist/index.html'));
  }

  // 窗口最小化到托盘（鸿蒙PC行为适配：最小化不退出）
  mainWindow.on('minimize', (e) => {
    e.preventDefault(); // 阻止默认关闭行为
    mainWindow.hide(); // 隐藏窗口
  });

  // 关闭所有窗口时退出应用（鸿蒙PC/Windows/Linux 统一逻辑，macOS 除外）
  mainWindow.on('closed', () => {
    mainWindow = null;
  });
};

// 创建系统托盘（适配鸿蒙PC托盘样式）
const createTray = () => {
  // 托盘图标（鸿蒙PC优先使用 png 格式）
  const iconPath = path.join(
    __dirname,
    isHarmonyPC() ? 'tray-harmony.png' : (os.platform() === 'win32' ? 'tray.ico' : 'tray.png')
  );

  // 实例化托盘（鸿蒙PC托盘行为适配）
  tray = new Tray(iconPath);
  // 设置托盘提示文本（鸿蒙PC支持中文）
  tray.setToolTip(isHarmonyPC() ? '鸿蒙PC - Electron Vue3 应用' : 'Electron Vue3 托盘应用');

  // 构建托盘右键菜单（新增鸿蒙PC专属选项）
  const trayMenuTemplate = [
    {
      label: '显示窗口',
      click: () => mainWindow.show()
    },
    {
      label: '发送通知',
      click: () => sendNotification()
    },
    // 鸿蒙PC专属菜单
    isHarmonyPC() ? {
      label: '鸿蒙PC系统信息',
      click: () => {
        new Notification({
          title: '鸿蒙PC信息',
          body: `鸿蒙PC Linux 子系统版本：${os.release()}`
        }).show();
      }
    } : {},
    {
      type: 'separator' // 分隔线
    },
    {
      label: '退出',
      click: () => {
        // 退出前销毁托盘（鸿蒙PC防止进程残留）
        tray.destroy();
        app.quit();
      }
    }
  ].filter(item => Object.keys(item).length > 0); // 过滤空项

  // 设置托盘菜单
  const trayMenu = Menu.buildFromTemplate(trayMenuTemplate);
  tray.setContextMenu(trayMenu);
  
  // 点击托盘图标显示/隐藏窗口（鸿蒙PC交互适配）
  tray.on('click', () => {
    mainWindow.isVisible() ? mainWindow.hide() : mainWindow.show();
  });
};

// 发送系统通知（适配鸿蒙PC通知机制）
const sendNotification = () => {
  // 检查系统是否支持通知（鸿蒙PC需单独校验）
  if (Notification.isSupported()) {
    const notification = new Notification({
      title: isHarmonyPC() ? '鸿蒙PC - Electron 通知' : 'Electron 通知',
      body: isHarmonyPC() ? '这是鸿蒙PC专属的系统通知 🚀' : '这是一条安全的系统通知 🚀',
      // 鸿蒙PC通知图标适配
      icon: path.join(__dirname, isHarmonyPC() ? 'notification-harmony.png' : 'notification.png')
    });

    // 显示通知
    notification.show();
    // 通知点击事件（鸿蒙PC唤醒窗口适配）
    notification.on('click', () => {
      mainWindow.show();
      if (isHarmonyPC()) {
        mainWindow.focus(); // 鸿蒙PC强制聚焦窗口
      }
    });
  }
};

// IPC 通信：监听渲染进程的“获取系统信息”请求（新增鸿蒙PC信息）
ipcMain.handle('get-system-info', () => {
  return {
    platform: os.platform(), // 系统平台（win32/darwin/linux/harmony）
    arch: os.arch(), // 系统架构
    homedir: os.homedir(), // 用户主目录
    isHarmonyPC: isHarmonyPC(), // 是否为鸿蒙PC环境
    kernelVersion: os.release() // 内核版本（鸿蒙PC可识别）
  };
});

// IPC 通信：监听渲染进程的“发送通知”请求
ipcMain.on('send-notification', (_, msg) => {
  const notification = new Notification({
    title: isHarmonyPC() ? '来自鸿蒙PC渲染进程的通知' : '来自渲染进程的通知',
    body: msg
  });
  notification.show();
});

// Electron 应用就绪后初始化（适配鸿蒙PC启动逻辑）
app.whenReady().then(() => {
  createWindow();
  createTray(); // 初始化托盘（鸿蒙PC托盘常驻）
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

// 处理跨平台退出逻辑（鸿蒙PC归为 linux 逻辑）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin' && !isHarmonyPC()) app.quit();
  // 鸿蒙PC窗口全关时不退出，仅隐藏（符合鸿蒙PC应用习惯）
  if (isHarmonyPC() && mainWindow) mainWindow.hide();
});

// 禁止应用多开（鸿蒙PC强制要求）
const gotTheLock = app.requestSingleInstanceLock();
if (!gotTheLock) {
  app.quit();
} else {
  app.on('second-instance', () => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.show();
      mainWindow.focus();
      // 鸿蒙PC多开提醒
      if (isHarmonyPC()) {
        new Notification({
          title: '鸿蒙PC提示',
          body: '应用已在运行中，请勿重复启动'
        }).show();
      }
    }
  });
}

2. 预加载脚本（electron/preload/index.js，适配鸿蒙 PC 通信）

预加载脚本运行在独立的上下文，是主 / 渲染进程通信的唯一安全桥梁，同时适配鸿蒙 PC 的权限管控：

const { contextBridge, ipcRenderer } = require('electron');

// 向渲染进程暴露安全的 API 接口（鸿蒙PC最小权限原则）
// 注意：仅暴露需要的方法，避免暴露整个 ipcRenderer
contextBridge.exposeInMainWorld('electronAPI', {
  // 获取系统信息（含鸿蒙PC标识）
  getSystemInfo: () => ipcRenderer.invoke('get-system-info'),
  // 发送自定义通知（适配鸿蒙PC通知）
  sendNotification: (msg) => ipcRenderer.send('send-notification', msg),
  // 窗口最小化（鸿蒙PC窗口行为适配）
  minimizeWindow: () => ipcRenderer.send('window-minimize'),
  // 窗口关闭（鸿蒙PC：关闭=隐藏）
  closeWindow: () => ipcRenderer.send('window-close'),
  // 鸿蒙PC专属 API：检查鸿蒙环境
  isHarmonyPC: () => ipcRenderer.invoke('is-harmony-pc')
});

// 补充：主进程监听窗口最小化/关闭（鸿蒙PC行为适配）
ipcRenderer.on('window-minimize', () => {
  const win = BrowserWindow.getFocusedWindow();
  if (win) win.minimize();
});

ipcRenderer.on('window-close', () => {
  const win = BrowserWindow.getFocusedWindow();
  if (win) {
    // 鸿蒙PC关闭窗口改为隐藏
    const isHarmony = process.env.OS === 'OpenHarmony' || process.env.OS === 'HarmonyOS';
    isHarmony ? win.hide() : win.close();
  }
});

// 鸿蒙PC专属 IPC 监听
ipcMain.handle('is-harmony-pc', () => {
  const os = require('node:os');
  return os.release().includes('harmony') || process.env.OS === 'OpenHarmony';
});

四、实战 2：Vue3 渲染进程开发（适配鸿蒙 PC 显示）

1. Vue 根组件（src/App.vue，新增鸿蒙 PC 适配）

集成 Electron 原生能力，适配鸿蒙 PC 的显示样式和交互逻辑：

<template>
  <div class="container" :class="{ 'harmony-pc': isHarmonyPC }">
    <header class="header">
      <h1>
        <span v-if="isHarmonyPC">鸿蒙PC - </span>
        Electron + Vue3 现代开发示例
      </h1>
      <div class="window-controls">
        <button @click="minimizeWindow">🗕</button>
        <button @click="closeWindow">{{ isHarmonyPC ? '🗕' : '🗙' }}</button>
      </div>
    </header>

    <main class="content">
      <!-- 系统信息展示（含鸿蒙PC标识） -->
      <div class="system-info">
        <h2>系统信息 <span v-if="isHarmonyPC" class="harmony-tag">鸿蒙PC</span></h2>
        <button @click="getSystemInfo" class="btn">获取系统信息</button>
        <pre v-if="systemInfo">{{ JSON.stringify(systemInfo, null, 2) }}</pre>
      </div>

      <!-- 自定义通知（鸿蒙PC专属文案） -->
      <div class="notification">
        <h2>发送系统通知</h2>
        <input
          v-model="notificationMsg"
          type="text"
          placeholder="输入通知内容..."
          class="input"
          :placeholder="isHarmonyPC ? '输入鸿蒙PC通知内容...' : '输入通知内容...'"
        />
        <button @click="sendNotification" class="btn">
          {{ isHarmonyPC ? '发送鸿蒙PC通知' : '发送通知' }}
        </button>
      </div>
    </main>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';

// 响应式数据
const systemInfo = ref(null);
const notificationMsg = ref('Hello Electron + Vue3!');
const isHarmonyPC = ref(false);

// 从预加载脚本暴露的 API 中获取方法
const { getSystemInfo, sendNotification, minimizeWindow, closeWindow, isHarmonyPC: checkHarmonyPC } = window.electronAPI;

// 初始化：检查是否为鸿蒙PC环境
onMounted(async () => {
  try {
    isHarmonyPC.value = await checkHarmonyPC();
    // 鸿蒙PC默认通知文案
    if (isHarmonyPC.value) {
      notificationMsg.value = '你好，鸿蒙PC！Electron 应用已就绪 🎉';
    }
  } catch (err) {
    console.error('检查鸿蒙PC环境失败：', err);
  }
});

// 获取系统信息（含鸿蒙PC标识）
const getSystemInfo = async () => {
  try {
    const info = await getSystemInfo();
    systemInfo.value = info;
    isHarmonyPC.value = info.isHarmonyPC;
  } catch (err) {
    console.error('获取系统信息失败：', err);
    alert(isHarmonyPC.value ? '鸿蒙PC获取系统信息失败，请查看控制台' : '获取系统信息失败，请查看控制台');
  }
};

// 发送自定义通知
const sendNotification = () => {
  if (!notificationMsg.value) {
    alert(isHarmonyPC.value ? '请输入鸿蒙PC通知内容' : '请输入通知内容');
    return;
  }
  sendNotification(notificationMsg.value);
};
</script>

<style scoped>
/* 基础样式 */
.container {
  width: 100%;
  height: 100vh;
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  background-color: #f5f5f5;
  display: flex;
  flex-direction: column;
}

/* 鸿蒙PC专属样式（适配鸿蒙字体和配色） */
.harmony-pc {
  font-family: 'HarmonyOS Sans', sans-serif;
  background-color: #f8f9fa;
}

.harmony-pc .header {
  background-color: #1a73e8; /* 鸿蒙PC主题色 */
}

.harmony-tag {
  background-color: #1a73e8;
  color: white;
  padding: 2px 8px;
  border-radius: 4px;
  font-size: 12px;
  margin-left: 8px;
}

.header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0 20px;
  height: 60px;
  background-color: #2c3e50;
  color: white;
  -webkit-app-region: drag; /* 允许窗口拖拽（鸿蒙PC/Windows/macOS） */
}

.window-controls {
  -webkit-app-region: no-drag; /* 取消拖拽，允许点击 */
}

.window-controls button {
  background: transparent;
  border: none;
  color: white;
  font-size: 16px;
  cursor: pointer;
  width: 30px;
  height: 30px;
  border-radius: 4px;
}

.window-controls button:hover {
  background-color: rgba(255, 255, 255, 0.2);
}

.content {
  flex: 1;
  padding: 30px;
  display: flex;
  gap: 40px;
}

.system-info, .notification {
  flex: 1;
  background: white;
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
}

/* 鸿蒙PC卡片样式适配 */
.harmony-pc .system-info, .harmony-pc .notification {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
  border: 1px solid #e5e7eb;
}

.btn {
  padding: 8px 16px;
  background-color: #3498db;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  margin-bottom: 10px;
}

/* 鸿蒙PC按钮样式 */
.harmony-pc .btn {
  background-color: #1a73e8;
}

.harmony-pc .btn:hover {
  background-color: #1557b0;
}

.btn:hover {
  background-color: #2980b9;
}

.input {
  width: 100%;
  padding: 8px;
  margin-bottom: 10px;
  border: 1px solid #ddd;
  border-radius: 4px;
  box-sizing: border-box;
}

/* 鸿蒙PC输入框样式 */
.harmony-pc .input {
  border: 1px solid #d0d7de;
  padding: 10px;
}

pre {
  background-color: #f8f8f8;
  padding: 10px;
  border-radius: 4px;
  overflow-x: auto;
}

/* 鸿蒙PC代码块样式 */
.harmony-pc pre {
  background-color: #f5f7fa;
  border: 1px solid #e5e7eb;
}
</style>

2. Vue 入口文件（src/main.js）

标准 Vue3 入口配置，兼容鸿蒙 PC 环境：

import { createApp } from 'vue'
import App from './App.vue'

// 鸿蒙PC适配：设置全局样式
if (window.electronAPI && window.electronAPI.isHarmonyPC) {
  window.electronAPI.isHarmonyPC().then(isHarmony => {
    if (isHarmony) {
      document.documentElement.classList.add('harmony-pc');
    }
  });
}

createApp(App).mount('#app')

3. 渲染进程入口 HTML（index.html）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <!-- 鸿蒙PC字体引入 -->
  <link rel="stylesheet" href="https://cdn.staticfile.org/harmonyos-font/1.0.0/harmonyos-sans.css" />
  <title>
    <script>
      // 动态标题：区分鸿蒙PC环境
      document.write(window.electronAPI ? '鸿蒙PC - Electron + Vue3 应用' : 'Electron + Vue3 应用');
    </script>
  </title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.js"></script>
</body>
</html>

五、运行与调试（鸿蒙 PC 专属流程）

1. 开发环境运行

# 通用运行命令
npm run dev
# 鸿蒙PC Linux 子系统运行命令（指定环境变量）
OS=HarmonyOS npm run dev

此时会启动 Vite 开发服务器和 Electron 应用，鸿蒙 PC 环境下具备以下特性：

Vue3 热更新（鸿蒙 PC Linux 子系统支持）；
开发者工具自动打开（鸿蒙 PC 兼容 Chrome 调试工具）；
窗口可拖拽（header 区域），适配鸿蒙 PC 窗口交互逻辑；
点击 “获取系统信息” 可展示鸿蒙 PC 标识、Linux 子系统版本等专属信息；
鸿蒙 PC 专属通知文案和样式；
窗口最小化 / 关闭行为适配鸿蒙 PC（关闭 = 隐藏，常驻托盘）；
禁止多开，重复启动会聚焦已有窗口并弹出鸿蒙 PC 专属提示。

2. 鸿蒙 PC 关键功能验证

安全通信：渲染进程无法直接访问 Node.js 模块，符合鸿蒙 PC 安全规范；
托盘功能：鸿蒙 PC 托盘常驻，右键菜单含 “鸿蒙 PC 系统信息” 专属选项；
系统通知：鸿蒙 PC 原生通知样式，点击可唤醒并聚焦窗口；
界面适配：自动加载鸿蒙 PC 字体、主题色和交互样式；
环境识别：自动检测鸿蒙 PC 环境并展示专属标识。

六、生产环境打包与优化（鸿蒙 PC 专属配置）

1. 打包命令

# 通用打包命令
npm run build
# 鸿蒙PC专属打包命令（仅打包 Linux 格式）
npm run build:harmonypc

在 package.json 中新增鸿蒙 PC 打包脚本：

"scripts": {
  "dev": "electron-vite dev",
  "build": "electron-vite build",
  "build:harmonypc": "electron-vite build && electron-builder --linux",
  "preview": "electron-vite preview"
}

打包完成后，输出文件位于 dist-electron 目录，鸿蒙 PC 支持的格式：

AppImage（推荐）：可直接运行，无需安装
deb/rpm：适配鸿蒙 PC Linux 子系统包管理

2. 鸿蒙 PC 打包优化技巧

（1）减小应用体积（鸿蒙 PC 存储空间优化）

"build": {
  "asar": true, // 鸿蒙PC强制开启，提升安全性
  "asarUnpack": ["**/*.node"], // 排除原生模块
  "linux": {
    "target": ["AppImage"], // 鸿蒙PC优先打包 AppImage
    "artifactName": "${productName}-harmonypc-${version}.${ext}" // 鸿蒙PC包命名
  }
}

（2）鸿蒙 PC 专属图标配置

"build": {
  "icon": "resources/harmony-icon.png", // 鸿蒙PC支持 png 格式
  "linux": {
    "icon": "resources/harmony-icon.png"
  }
}

（3）鸿蒙 PC 自动更新适配

集成 electron-updater 并适配鸿蒙 PC 更新逻辑：

const { autoUpdater } = require('electron-updater');

// 鸿蒙PC更新源配置
if (isHarmonyPC()) {
  autoUpdater.setFeedURL({
    provider: 'generic',
    url: 'https://your-harmony-pc-update-server.com/'
  });
}

// 检查更新（鸿蒙PC静默更新）
autoUpdater.checkForUpdatesAndNotify({
  title: '鸿蒙PC应用更新',
  body: '发现新版本，正在后台更新...'
});

// 鸿蒙PC更新完成提示
autoUpdater.on('update-downloaded', () => {
  new Notification({
    title: '鸿蒙PC更新完成',
    body: '重启应用以应用更新（鸿蒙PC专属）'
  }).show();
  autoUpdater.quitAndInstall();
});

七、核心知识点总结

安全基础（适配鸿蒙 PC）：禁用 nodeIntegration + 开启 contextIsolation，符合鸿蒙 PC 安全规范；预加载脚本通过 contextBridge 暴露最小必要 API，适配鸿蒙 PC 权限管控。
环境适配：通过系统环境变量和内核版本识别鸿蒙 PC，定制化窗口、托盘、通知等原生行为，匹配鸿蒙 PC 用户习惯。
开发效率：使用 electron-vite 快速搭建项目，支持鸿蒙 PC 热更新；Vue3 渲染进程自动适配鸿蒙 PC 字体、样式和交互。
打包部署：鸿蒙 PC 优先打包 AppImage 格式，开启 asar 归档提升安全性，适配鸿蒙 PC Linux 子系统运行规则。
用户体验：鸿蒙 PC 专属文案、样式和功能，窗口行为（关闭 = 隐藏）贴合鸿蒙 PC 应用生态。