Electron for 鸿蒙PC - Webpack PublicPath 动态设置完整方案

前言

在将 MarkText 适配到鸿蒙 PC 平台时，我们遇到了一个棘手的资源加载问题：所有通过 Webpack 打包的图片、字体等资源文件全部 404 。经过排查发现，鸿蒙 PC 的应用资源路径结构与标准 Electron 应用完全不同，导致 Webpack 的静态 publicPath 配置失效。

本文将详细记录我们如何通过运行时动态设置 publicPath 来解决这一问题，实现了资源在鸿蒙 PC 上的正确加载。

关键词：鸿蒙PC、Electron适配、Webpack、publicPath、资源加载、路径配置

目录

1. 鸿蒙PC的资源路径问题
2. [Webpack PublicPath 原理](#Webpack PublicPath 原理)
3. 动态设置方案设计
4. 完整实现代码
5. 遇到的坑与解决方案
6. 总结与展望

---

鸿蒙PC的资源路径问题

1.1 错误现象

MarkText 首次在鸿蒙 PC 上运行时，控制台出现大量 404 错误：

Failed to load resource: net::ERR_FILE_NOT_FOUND
file:///logo.a3f5b2c1.png

Failed to load resource: net::ERR_FILE_NOT_FOUND  
file:///fonts/SourceCodePro.woff2

Failed to load resource: net::ERR_FILE_NOT_FOUND
file:///images/icon-file.svg

表现：

• ❌ 应用图标不显示
• ❌ 自定义字体加载失败
• ❌ SVG 图标全部丢失
• ✅ HTML、CSS、JS 文件正常加载

1.2 路径结构对比

标准 Electron 应用路径：

Windows:  C:\Program Files\MyApp\resources\app\
macOS:    /Applications/MyApp.app/Contents/Resources/app/
Linux:    /opt/myapp/resources/app/

app.getAppPath() 返回:
→ /path/to/app/resources/app

鸿蒙 PC 应用路径：

鸿蒙PC:   /data/storage/el1/bundle/entry/resources/resfile/resources/app/
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          路径深度和结构完全不同！

app.getAppPath() 返回:
→ /data/storage/el1/bundle/entry/resources/resfile/resources/app

问题分析：

• Webpack 打包时使用的是静态 publicPath: '/'
• 运行时实际资源路径是 file:///data/storage/.../app/images/logo.png
• 但 Webpack 生成的代码尝试从 file:///logo.png 加载
• 路径不匹配 → 404 错误

1.3 为什么静态配置不可行

// webpack.config.js
module.exports = {
  output: {
    publicPath: '/data/storage/el1/bundle/...'  // ❌ 不可行！
  }
}

问题：

1. ❌ 不同用户安装路径可能不同
2. ❌ 开发环境和生产环境路径不同
3. ❌ 其他平台（Windows/macOS）路径完全不同
4. ❌ 无法做到一次打包，多平台运行

---

Webpack PublicPath 原理

2.1 PublicPath 的作用

根据 Webpack 官方文档，publicPath 用于指定资源文件的访问路径前缀。

打包前代码：

import logo from './assets/logo.png'

打包后代码（简化）：

const logo = __webpack_require__.p + 'images/logo.a3f5b2c1.png'
//            ^^^^^^^^^^^^^^^^^^^^   资源路径前缀

关键点：

• __webpack_require__.p 存储了 publicPath 的值
• 所有资源加载都会使用这个前缀
• 可以在运行时修改 __webpack_require__.p

2.2 静态 vs 动态 PublicPath

方式	配置位置	适用场景	鸿蒙PC适用性
静态配置	webpack.config.js	路径固定	❌ 不适用
动态设置	运行时 JavaScript	路径可变	✅ 完美适配

2.3 动态设置的时机要求

时间线：
  ① HTML 加载
  ② <script> 标签开始执行
  ③ Webpack runtime 初始化
  ④ 设置 __webpack_require__.p  ← 必须在这之前！
  ⑤ 应用代码开始执行
  ⑥ 加载资源（使用 publicPath）

关键 ：必须在 Webpack 加载任何模块之前设置好 publicPath。

---

动态设置方案设计

3.1 技术方案

核心思路：

1. 在主进程获取真实的应用路径（app.getAppPath()）
2. 在页面加载最早期通过 did-start-loading 事件注入初始化脚本
3. 拦截 __webpack_require__.p 的赋值，使用动态路径
4. 确保在 Webpack 执行前完成设置

架构图：

主进程 (Main Process)
  ↓ app.getAppPath()
获取真实路径: /data/storage/.../app
  ↓ webContents.on('did-start-loading')
注入初始化脚本
  ↓ executeJavaScript()
设置 window.__webpack_public_path__
  ↓ Object.defineProperty
拦截 __webpack_require__.p
  ↓
Webpack 执行
  ↓ 读取 __webpack_require__.p
使用动态路径加载资源 ✅

3.2 关键技术点

1. 使用 did-start-loading 事件

根据 Electron 官方文档，did-start-loading 是页面开始加载时触发的最早事件。

mainWindow.webContents.on('did-start-loading', () => {
  // 在这里注入的代码会在页面脚本执行前运行
})

2. 拦截 __webpack_require__.p 赋值

使用 Object.defineProperty 拦截属性赋值：

Object.defineProperty(tempRequire, 'p', {
  get: function() {
    return window.__webpack_public_path__  // 返回动态值
  },
  set: function(value) {
    console.log('Webpack 尝试设置:', value)
    // 忽略 Webpack 的默认值，使用我们的动态值
  }
})

---

完整实现代码

4.1 主进程注入脚本

// main.js (主进程)
const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false
    }
  })
  
  // 关键：在页面开始加载时注入动态 publicPath 设置
  mainWindow.webContents.on('did-start-loading', () => {
    // 获取应用真实路径
    const appPath = app.getAppPath()
  
    // 转换为 file:// 协议的 URL
    const publicPath = `file://${appPath}/`
  
    console.log('[Main] 应用路径:', appPath)
    console.log('[Main] 设置 publicPath:', publicPath)
  
    // 注入初始化代码（在 Webpack 执行前）
    const initScript = `
      (function() {
        console.log('[Init] 开始设置动态 publicPath')
      
        // 1. 设置全局变量
        window.__webpack_public_path__ = '${publicPath}'
        console.log('[Init] publicPath 已设置:', window.__webpack_public_path__)
      
        // 2. 创建临时对象拦截 __webpack_require__.p
        const tempRequire = {}
      
        Object.defineProperty(tempRequire, 'p', {
          configurable: true,
          enumerable: true,
          get: function() {
            // Webpack 读取 publicPath 时返回我们的动态值
            return window.__webpack_public_path__
          },
          set: function(value) {
            // Webpack 尝试设置默认 publicPath
            console.log('[Init] Webpack 默认 publicPath:', value)
            console.log('[Init] 使用动态 publicPath:', window.__webpack_public_path__)
            // 不做任何操作，保持使用动态值
          }
        })
      
        // 3. 如果 __webpack_require__ 已经存在，迁移其他属性
        if (window.__webpack_require__) {
          Object.keys(window.__webpack_require__).forEach(key => {
            if (key !== 'p') {
              tempRequire[key] = window.__webpack_require__[key]
            }
          })
        }
      
        // 4. 替换全局 __webpack_require__
        window.__webpack_require__ = tempRequire
      
        console.log('[Init] __webpack_require__.p 拦截已设置')
        console.log('[Init] 动态 publicPath 初始化完成 ✓')
      })()
    `
  
    mainWindow.webContents.executeJavaScript(initScript)
      .then(() => {
        console.log('[Main] 初始化脚本注入成功')
      })
      .catch(err => {
        console.error('[Main] 初始化脚本注入失败:', err)
      })
  })
  
  // 加载应用
  mainWindow.loadFile('index.html')
  
  return mainWindow
}

app.whenReady().then(createWindow)

4.2 HTML 备用方案

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>MarkText</title>
  
  <!-- 备用方案：如果主进程注入失败，使用 HTML 中的设置 -->
  <script>
    (function() {
      // 如果主进程注入成功，这里会跳过
      if (window.__webpack_public_path__) {
        console.log('[HTML] publicPath 已由主进程设置')
        return
      }
    
      console.warn('[HTML] 使用备用 publicPath 设置')
    
      // 根据当前页面 URL 推断应用路径
      const currentURL = window.location.href
      const appPath = currentURL.substring(0, currentURL.lastIndexOf('/') + 1)
    
      window.__webpack_public_path__ = appPath
    
      console.log('[HTML] 备用 publicPath:', appPath)
    })()
  </script>
</head>
<body>
  <div id="root"></div>
  
  <!-- Webpack 打包的主脚本 -->
  <script src="./dist/bundle.js"></script>
</body>
</html>

4.3 Webpack 配置

// webpack.config.js
const path = require('path')

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
    // 设置一个占位符，运行时会被动态值覆盖
    publicPath: '/'
  },
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif|svg)$/,
        type: 'asset/resource',
        generator: {
          filename: 'images/[name].[hash:8][ext]'
        }
      },
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/,
        type: 'asset/resource',
        generator: {
          filename: 'fonts/[name].[hash:8][ext]'
        }
      }
    ]
  }
}

4.4 应用代码正常使用

// src/index.js
import logo from './assets/logo.png'
import './styles/main.css'

// 资源会自动使用动态 publicPath
const img = document.createElement('img')
img.src = logo  
// 实际路径：file:///data/storage/.../app/images/logo.a3f5b2c1.png ✅

document.body.appendChild(img)

console.log('Logo 路径:', logo)

4.5 运行时日志输出

成功运行时的控制台输出：

[Main] 应用路径: /data/storage/el1/bundle/entry/resources/resfile/resources/app
[Main] 设置 publicPath: file:///data/storage/el1/bundle/entry/resources/resfile/resources/app/
[Main] 初始化脚本注入成功
[Init] 开始设置动态 publicPath
[Init] publicPath 已设置: file:///data/storage/el1/bundle/entry/resources/resfile/resources/app/
[Init] __webpack_require__.p 拦截已设置
[Init] 动态 publicPath 初始化完成 ✓
[Init] Webpack 默认 publicPath: /
[Init] 使用动态 publicPath: file:///data/storage/el1/bundle/entry/resources/resfile/resources/app/
Logo 路径: file:///data/storage/el1/bundle/entry/resources/resfile/resources/app/images/logo.a3f5b2c1.png

---

遇到的坑与解决方案

5.1 坑1：注入时机太晚

问题 ：使用 did-finish-load 事件注入，Webpack 已经开始加载资源。

// ❌ 错误：太晚了
mainWindow.webContents.on('did-finish-load', () => {
  // 这时 Webpack 已经执行，资源已经开始加载
})

解决方案：

// ✅ 正确：使用最早的事件
mainWindow.webContents.on('did-start-loading', () => {
  // 页面刚开始加载，还没有执行任何脚本
})

5.2 坑2：路径中的反斜杠

问题 ：Windows 路径包含反斜杠 \，在 JavaScript 字符串中会被转义。

// Windows 路径
const appPath = 'C:\\Program Files\\MyApp'

// 注入到 JavaScript 中会出错
const script = `window.__webpack_public_path__ = '${appPath}'`
// 结果：window.__webpack_public_path__ = 'C:\Program Files\MyApp'
//                                          ^^  转义错误！

解决方案：

// 统一转换为正斜杠
const appPath = app.getAppPath().replace(/\\/g, '/')
const publicPath = `file://${appPath}/`

5.3 坑3：开发环境与生产环境

问题：开发时使用 webpack-dev-server，生产使用 file:// 协议。

解决方案：

// 运行时检测环境
if (window.location.protocol === 'http:') {
  // 开发环境，使用 webpack-dev-server 的默认 publicPath
  console.log('[Init] 开发环境，跳过动态 publicPath 设置')
} else {
  // 生产环境，设置动态 publicPath
  window.__webpack_public_path__ = getDynamicPath()
}

5.4 坑4：executeJavaScript 失败

问题 ：executeJavaScript 可能因为各种原因失败。

解决方案：多重保险机制

// 方案1：主进程注入（最可靠）
mainWindow.webContents.on('did-start-loading', () => {
  mainWindow.webContents.executeJavaScript(initScript)
})

// 方案2：HTML 头部设置（备用）
<script>
  if (!window.__webpack_public_path__) {
    window.__webpack_public_path__ = inferPath()
  }
</script>

// 方案3：应用启动时检测（最终兜底）
if (!window.__webpack_public_path__) {
  console.error('publicPath 未设置！')
  window.__webpack_public_path__ = './'
}

5.5 坑5：CSS 中的资源路径

问题：CSS 文件中引用的图片也需要正确的路径。

/* CSS 中的背景图 */
.container {
  background: url('./images/bg.png');
}

解决方案：使用 CSS-in-JS 或 CSS 变量

// 方案1：CSS-in-JS
const styles = {
  background: `url(${require('./bg.png')})`
}

// 方案2：CSS 变量
document.documentElement.style.setProperty(
  '--asset-path',
  window.__webpack_public_path__
)

.container {
  background: url(var(--asset-path)/images/bg.png);
}

---

总结与展望

6.1 成果总结

通过动态设置 Webpack PublicPath，我们成功解决了 MarkText 在鸿蒙 PC 上的资源加载问题：

✅ 完全解决了资源 404 问题

✅ 支持任意安装路径 （用户可以安装到任何位置）

✅ 一次打包，多平台运行 （Windows、macOS、Linux、鸿蒙PC）

✅ 零侵入性 （不需要修改业务代码）

✅ 多重保险机制（主进程注入 + HTML备用 + 运行时检测）

6.2 关键技术点

1. did-start-loading 事件：最早的注入时机
2. Object.defineProperty：拦截属性赋值
3. app.getAppPath()：获取真实应用路径
4. 多重保险机制：确保可靠性

6.3 适用场景

这套方案不仅适用于鸿蒙 PC，也适用于：

• ✅ Electron 便携版应用（路径不固定）
• ✅ 需要从不同位置加载资源的应用
• ✅ 特殊平台适配（如嵌入式系统）
• ✅ 任何需要动态资源路径的场景

6.4 性能影响

指标	静态 PublicPath	动态 PublicPath
初始化耗时	0ms	~5ms
资源加载速度	相同	相同
内存占用	相同	相同
代码体积	相同	+2KB

结论：性能影响可忽略不计。

6.5 源码地址

完整代码已开源在 MarkText for HarmonyOS 项目中：

• 项目地址：https://gitcode.com/szkygc/marktext
• 关键文件 ：
  • main.js - 主进程注入逻辑
  • index.html - HTML 备用方案
  • webpack.config.js - Webpack 配置

---

相关资源

Webpack 官方文档：

• Webpack PublicPath 指南
• Webpack Output 配置

Electron 官方文档：

• app.getAppPath() API
• WebContents Events
• webContents.executeJavaScript

鸿蒙PC开发资源：

• OpenHarmony PC开发者专区
• HarmonyOS PC 开发者社区

---

技术难度：⭐⭐⭐⭐ 中高级

实战价值：⭐⭐⭐⭐⭐ 解决鸿蒙PC资源加载核心问题

推荐指数：⭐⭐⭐⭐⭐ Electron应用必备技能