前言

在将 Abricotine 适配到鸿蒙 PC 平台时，我们遇到了一个文件路径格式问题：HarmonyOS 的文件选择器返回的路径格式与标准平台不同，可能是 file://docs/storage/... 格式，也可能是标准 file:// URI 格式，还可能是绝对路径格式。这些不同的格式导致文件操作失败，应用无法正常打开和保存文件。

本文将深入分析 HarmonyOS 文件路径格式的特点，提供完整的路径转换和 URI 解析方案，确保应用能够正确处理各种路径格式，实现完美的文件操作体验。

关键词：鸿蒙PC、Electron适配、文件路径、URI解析、路径转换、文件选择器

目录

1. 问题现象与路径格式分析
2. HarmonyOS 文件路径格式特点
3. 路径转换方案设计
4. 完整实现方案
5. 最佳实践与注意事项
6. 常见问题解答
7. 总结与展望

---

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

问题现象与路径格式分析

1.1 问题现象

应用打开文件时，出现以下问题：

错误1：路径格式不识别

[HarmonyOS Renderer] File path: file://docs/storage/emulated/0/Documents/test.md
[HarmonyOS Renderer] Error: ENOENT: no such file or directory

错误2：URI 解析失败

[HarmonyOS Renderer] File path: file:///storage/emulated/0/Documents/test.md
[HarmonyOS Renderer] Error: Failed to parse file URI

错误3：路径格式不一致

[HarmonyOS Renderer] File path: /storage/emulated/0/Documents/test.md  ✅ 正常
[HarmonyOS Renderer] File path: file://docs/storage/.../test.md        ❌ 失败

1.2 路径格式对比

不同平台的文件选择器返回格式：

平台	路径格式示例	特点
Windows	C:\Users\...\file.md	绝对路径，Windows 格式
macOS	/Users/.../file.md	绝对路径，Unix 格式
Linux	/home/.../file.md	绝对路径，Unix 格式
鸿蒙PC	file://docs/storage/...	URI 格式，特殊前缀
鸿蒙PC	file:///storage/...	标准 URI 格式
鸿蒙PC	/storage/...	绝对路径格式

问题分析：

• HarmonyOS 文件选择器可能返回多种格式
• 需要统一转换为绝对路径格式
• URI 解析需要考虑编码问题

---

HarmonyOS 文件路径格式特点

3.1 file://docs/ 格式

格式说明：

file://docs/storage/emulated/0/Documents/test.md

特点：

• file://docs/ 是 HarmonyOS 特有的 URI 前缀
• 需要转换为 /storage/emulated/0/Documents/test.md
• 移除 file://docs 前缀即可

3.2 标准 file:// URI 格式

格式说明：

file:///storage/emulated/0/Documents/test.md
file:///C:/Users/.../file.md  (Windows)

特点：

• 标准 file:// URI 格式
• 需要解析 URI 并提取路径
• 路径可能包含编码字符（如 %20 表示空格）

3.3 绝对路径格式

格式说明：

/storage/emulated/0/Documents/test.md
C:\Users\...\file.md  (Windows)

特点：

• 已经是绝对路径
• 可以直接使用
• 不需要转换

---

路径转换方案设计

4.1 转换流程

输入路径（多种格式）
    ↓
检测路径格式
    ↓
转换为统一格式（绝对路径）
    ↓
规范化路径
    ↓
返回绝对路径 ✅

4.2 格式检测逻辑

function detectPathFormat(filePath) {
  if (!filePath) {
    return 'empty'
  }
  
  // 检测 file://docs/ 格式
  if (filePath.startsWith('file://docs/')) {
    return 'harmonyos-uri'
  }
  
  // 检测标准 file:// URI 格式
  if (filePath.startsWith('file://')) {
    return 'standard-uri'
  }
  
  // 检测绝对路径
  if (path.isAbsolute(filePath)) {
    return 'absolute'
  }
  
  // 相对路径
  return 'relative'
}

---

完整实现方案

5.1 路径转换工具类

// utils/path-converter.js

const path = require('path')
const { URL } = require('url')

/**
 * 路径转换工具类
 * 统一处理 HarmonyOS 的各种路径格式
 */
class PathConverter {
  /**
   * 检测路径格式
   */
  static detectFormat(filePath) {
    if (!filePath || typeof filePath !== 'string') {
      return 'invalid'
    }
  
    // 检测 file://docs/ 格式（HarmonyOS 特有）
    if (filePath.startsWith('file://docs/')) {
      return 'harmonyos-uri'
    }
  
    // 检测标准 file:// URI 格式
    if (filePath.startsWith('file://')) {
      return 'standard-uri'
    }
  
    // 检测绝对路径
    if (path.isAbsolute(filePath)) {
      return 'absolute'
    }
  
    // 相对路径
    return 'relative'
  }
  
  /**
   * 转换路径为绝对路径
   */
  static toAbsolutePath(filePath, baseDir = null) {
    if (!filePath) {
      return null
    }
  
    const format = this.detectFormat(filePath)
    console.log('[PathConverter] Detected format:', format, 'for path:', filePath)
  
    let absolutePath = null
  
    switch (format) {
      case 'harmonyos-uri':
        // file://docs/storage/... -> /storage/...
        absolutePath = filePath.replace(/^file:\/\/docs/, '')
        console.log('[PathConverter] Converted HarmonyOS URI:', filePath, '->', absolutePath)
        break
      
      case 'standard-uri':
        // file:///path/to/file -> /path/to/file
        try {
          const url = new URL(filePath)
          absolutePath = decodeURIComponent(url.pathname)
        
          // Windows 路径处理：file:///C:/... -> C:/...
          if (process.platform === 'win32' && absolutePath.startsWith('/')) {
            absolutePath = absolutePath.substring(1)
          }
        
          console.log('[PathConverter] Converted standard URI:', filePath, '->', absolutePath)
        } catch (error) {
          console.error('[PathConverter] Failed to parse URI:', error)
          // 尝试简单替换
          absolutePath = filePath.replace(/^file:\/\//, '')
        }
        break
      
      case 'absolute':
        // 已经是绝对路径，直接使用
        absolutePath = filePath
        break
      
      case 'relative':
        // 相对路径，需要 baseDir
        if (baseDir) {
          absolutePath = path.resolve(baseDir, filePath)
        } else {
          absolutePath = path.resolve(filePath)
        }
        break
      
      default:
        console.error('[PathConverter] Unknown path format:', format)
        return null
    }
  
    // 规范化路径
    if (absolutePath) {
      absolutePath = path.normalize(absolutePath)
    }
  
    return absolutePath
  }
  
  /**
   * 批量转换路径
   */
  static toAbsolutePaths(filePaths, baseDir = null) {
    if (!Array.isArray(filePaths)) {
      return []
    }
  
    return filePaths.map(filePath => this.toAbsolutePath(filePath, baseDir)).filter(Boolean)
  }
  
  /**
   * 验证路径是否有效
   */
  static isValidPath(filePath) {
    const absolutePath = this.toAbsolutePath(filePath)
    return absolutePath !== null && absolutePath.length > 0
  }
}

module.exports = PathConverter

5.2 Abricotine 集成

在 abr-document.js 中集成路径转换：

// abr-document.js

const PathConverter = require('./utils/path-converter')

// 修改 open 方法
open: function (filePath, callback) {
  console.log('[HarmonyOS Renderer] open() called with path:', filePath)
  
  // ⚠️ HarmonyOS: 转换文件路径格式
  var finalPath = PathConverter.toAbsolutePath(filePath)
  
  if (!finalPath) {
    console.error('[HarmonyOS Renderer] Failed to convert path:', filePath)
    if (callback) callback(new Error('Invalid file path'))
    return
  }
  
  console.log('[HarmonyOS Renderer] Final file path for readFile:', finalPath)
  
  // 使用转换后的路径读取文件
  files.readFile(finalPath, function (data, path) {
    if (data === null || data === undefined) {
      console.error('[HarmonyOS Renderer] ⚠️ File read returned null/undefined')
      if (callback) callback(new Error('Failed to read file'))
      return
    }
  
    // 设置文档路径（使用转换后的路径）
    that.setPath(finalPath)
  
    // 设置文档内容
    that.setData(data)
  
    if (callback) callback(null, finalPath)
  })
}

5.3 文件选择器适配

在文件选择对话框返回后，统一转换路径：

// dialogs.js

const PathConverter = require('./utils/path-converter')

// 修改文件选择处理
function handleFileSelection(result) {
  if (result.canceled) {
    return null
  }
  
  // HarmonyOS 文件选择器可能返回单个路径或路径数组
  const selectedPaths = result.filePaths || (result.filePath ? [result.filePath] : [])
  
  if (selectedPaths.length === 0) {
    return null
  }
  
  // 转换所有路径
  const convertedPaths = PathConverter.toAbsolutePaths(selectedPaths)
  
  if (convertedPaths.length === 0) {
    console.error('[Dialogs] Failed to convert any paths')
    return null
  }
  
  // 返回第一个路径（或所有路径）
  return convertedPaths.length === 1 ? convertedPaths[0] : convertedPaths
}

---

最佳实践与注意事项

6.1 路径规范化

始终规范化路径：

// ✅ 好：规范化路径
const normalizedPath = path.normalize(absolutePath)

// ❌ 不好：直接使用未规范化的路径
const rawPath = filePath.replace('file://docs', '')

6.2 URI 编码处理

正确处理 URI 编码：

// ✅ 好：解码 URI
const decodedPath = decodeURIComponent(url.pathname)

// ❌ 不好：不解码
const rawPath = url.pathname  // 可能包含 %20 等编码

6.3 错误处理

添加完善的错误处理：

static toAbsolutePath(filePath, baseDir = null) {
  try {
    // ... 转换逻辑
    return absolutePath
  } catch (error) {
    console.error('[PathConverter] Error converting path:', error)
    return null
  }
}

---

常见问题解答

Q1: 为什么需要处理多种路径格式？

A: HarmonyOS 文件选择器在不同场景下可能返回不同格式的路径，需要统一转换为绝对路径才能正常使用。

Q2: file://docs/ 格式是什么？

A: 这是 HarmonyOS 特有的 URI 格式，file://docs/ 前缀表示用户文档目录，需要移除前缀转换为绝对路径。

Q3: 如何处理路径编码问题？

A: 使用 decodeURIComponent() 解码 URI 中的编码字符（如 %20 表示空格）。

---

总结与展望

8.1 核心要点总结

通过本文的深入分析，我们了解到：

1. 路径格式多样性：HarmonyOS 文件选择器可能返回多种格式的路径
2. 统一转换方案：使用路径转换工具类统一处理各种格式
3. 最佳实践：规范化路径，正确处理 URI 编码

8.2 技术价值

这个解决方案不仅解决了路径格式问题，还带来了以下好处：

• ✅ 更好的兼容性：支持所有路径格式
• ✅ 更清晰的路径管理：统一使用绝对路径
• ✅ 更好的错误处理：完善的错误处理机制

---

相关资源

Node.js 官方文档：

• path 模块
• URL 模块

MDN 文档：

• URL API
• decodeURIComponent

HarmonyOS 官方文档：

• 文件管理开发指南