04 oh-package.json5 与依赖管理：ohpm 包管理器全解析

04 oh-package.json5 与依赖管理：ohpm 包管理器全解析

前言

图：04 oh-package.json5 与依赖管理：ohpm 包管理器全解析 运行效果截图（HarmonyOS NEXT）

鸿蒙应用开发使用 ohpm（OpenHarmony Package Manager） 作为包管理工具，配置文件为 oh-package.json5。如果你有 npm/yarn/pnpm 使用经验，会发现 ohpm 的设计理念与 npm 非常相似------语义化版本控制、两级依赖结构、lock 文件固定版本。

本文将详细解析 oh-package.json5 的所有配置字段，介绍 ohpm 常用命令，并深入讲解 HarmonyOS NEXT API 12 引入的 @kit. * 统一包引用规范与传统 @ohos.* 路径的区别。

ohpm 官方包仓库：ohpm.openharmony.cn

官方文档·oh-package.json5 配置：developer.huawei.com

图：ohpm 两级依赖结构------根目录 oh-package.json5（全局共用）+ entry/oh-package.json5（模块专有）

---

一、oh-package.json5 文件结构概述

1.1 两级配置结构

鸿蒙项目使用两级依赖管理结构，类似于 monorepo 中的工作区管理：

harmony-app/                    ← 项目根目录
├── oh-package.json5            ← 根级配置（全局共用依赖）
└── entry/
    └── oh-package.json5        ← 模块级配置（entry 模块专有依赖）

1.2 配置文件完整字段

oh-package.json5 支持以下字段：

字段	类型	说明	是否必须
modelVersion	string	ohpm 模型版本，当前为 5.1.0	✅
name	string	项目或模块名称	✅
version	string	语义化版本号（如 1.0.0）	✅
description	string	描述文字	推荐
main	string	入口文件（HAR 包必须，应用通常留空）	视情况
author	string	作者	可选
license	string	开源协议	推荐
dependencies	object	运行时依赖	按需
devDependencies	object	开发时依赖（不打包进产物）	按需

---

二、项目实际配置文件

2.1 根级 oh-package.json5

{
  "modelVersion": "5.1.0",
  "name": "handwriting-analysis",
  "version": "1.0.0",
  "description": "鹿鹿·笔迹心理分析 - HarmonyOS NEXT App",
  "main": "",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {
    "@ohos/hypium": "1.0.25"
  }
}

2.2 entry 模块 oh-package.json5

{
  "name": "entry",
  "version": "1.0.0",
  "description": "鹿鹿·笔迹心理分析 entry 模块",
  "main": "",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {}
}

2.3 配置说明

项目采用极简依赖策略：

• 根级 只引入了 @ohos/hypium（单元测试框架），其他 HarmonyOS 系统能力均通过 @kit.* 内置包引用，无需额外安装
• entry 模块当前无第三方依赖，所有能力来自鸿蒙系统内置 API

重要理解 ：HarmonyOS 的 @kit.* 包（如 @kit.CameraKit、@kit.AbilityKit）是系统内置包 ，不需要在 oh-package.json5 中声明依赖，直接 import 即可使用。这与 npm 生态中需要先 npm install 有本质区别。

---

三、语义化版本控制

3.1 版本号格式

ohpm 遵循 SemVer（语义化版本控制） 规范：

MAJOR.MINOR.PATCH
 ↑      ↑     ↑
主版本 次版本 修订版本

• MAJOR：不兼容的 API 变更时递增
• MINOR：向后兼容的功能新增时递增
• PATCH：向后兼容的问题修复时递增

3.2 版本范围匹配规则

// dependencies 中的版本范围写法
{
  "dependencies": {
    "pkg-a": "1.0.0",      // 精确版本：只使用 1.0.0
    "pkg-b": "^1.0.0",     // 兼容版本：>=1.0.0 且 <2.0.0
    "pkg-c": "~1.0.0",     // 近似版本：>=1.0.0 且 <1.1.0
    "pkg-d": ">=1.0.0",    // 最低版本：>=1.0.0 任意版本
    "pkg-e": "*"           // 任意最新版本（不推荐）
  }
}

3.3 版本锁定文件

执行 ohpm install 后，会生成 oh_modules/.ohpm/lock.json5 锁定文件：

{
  "@ohos/hypium@1.0.25": {
    "version": "1.0.25",
    "resolved": "https://ohpm.openharmony.cn/ohpm/@ohos/hypium/-/hypium-1.0.25.tgz",
    "integrity": "sha512-..."
  }
}

锁定文件的作用：

• 保证团队成员安装相同版本：避免 "在我机器上好好的" 问题
• 应该提交到版本控制：确保 CI/CD 环境与开发环境一致

---

四、ohpm 常用命令

4.1 基础命令一览

# 安装所有依赖（根据 oh-package.json5）
ohpm install

# 安装指定包
ohpm install @ohos/hypium

# 安装指定版本
ohpm install @ohos/hypium@1.0.25

# 仅安装开发依赖
ohpm install --save-dev @ohos/some-dev-tool

# 移除依赖
ohpm uninstall @ohos/hypium

# 查看已安装的依赖树
ohpm list

# 查看包详情
ohpm info @ohos/hypium

# 更新依赖到最新兼容版本
ohpm update

# 清理缓存
ohpm cache clean

4.2 ohpm 与 npm 命令对照

npm 命令	ohpm 等效命令	说明
npm install	ohpm install	安装所有依赖
npm install pkg	ohpm install pkg	安装指定包
npm uninstall pkg	ohpm uninstall pkg	移除包
npm list	ohpm list	查看依赖树
npm cache clean	ohpm cache clean	清除缓存

4.3 oh_modules 目录结构

oh_modules/
├── .ohpm/                      # ohpm 元数据目录
│   ├── @ohos+hypium@1.0.25/    # 每个包的独立目录
│   │   ├── oh_modules/         # 该包的子依赖
│   │   └── package.json5       # 包清单
│   └── lock.json5              # 锁定文件
└── @ohos/
    └── hypium/                  # 实际使用的包（符号链接）

---

五、@kit 包引用系统详解

5.1 @kit 与 @ohos 的区别

HarmonyOS NEXT API 11 引入了 @kit.* 统一包管理系统，作为传统 @ohos.* 的现代化替代：
#mermaid-svg-FFsxO61qxSofbTrA{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FFsxO61qxSofbTrA .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FFsxO61qxSofbTrA .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FFsxO61qxSofbTrA .error-icon{fill:#552222;}#mermaid-svg-FFsxO61qxSofbTrA .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FFsxO61qxSofbTrA .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FFsxO61qxSofbTrA .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FFsxO61qxSofbTrA .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FFsxO61qxSofbTrA .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FFsxO61qxSofbTrA .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FFsxO61qxSofbTrA .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FFsxO61qxSofbTrA .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FFsxO61qxSofbTrA .marker.cross{stroke:#333333;}#mermaid-svg-FFsxO61qxSofbTrA svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FFsxO61qxSofbTrA p{margin:0;}#mermaid-svg-FFsxO61qxSofbTrA .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-FFsxO61qxSofbTrA .cluster-label text{fill:#333;}#mermaid-svg-FFsxO61qxSofbTrA .cluster-label span{color:#333;}#mermaid-svg-FFsxO61qxSofbTrA .cluster-label span p{background-color:transparent;}#mermaid-svg-FFsxO61qxSofbTrA .label text,#mermaid-svg-FFsxO61qxSofbTrA span{fill:#333;color:#333;}#mermaid-svg-FFsxO61qxSofbTrA .node rect,#mermaid-svg-FFsxO61qxSofbTrA .node circle,#mermaid-svg-FFsxO61qxSofbTrA .node ellipse,#mermaid-svg-FFsxO61qxSofbTrA .node polygon,#mermaid-svg-FFsxO61qxSofbTrA .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-FFsxO61qxSofbTrA .rough-node .label text,#mermaid-svg-FFsxO61qxSofbTrA .node .label text,#mermaid-svg-FFsxO61qxSofbTrA .image-shape .label,#mermaid-svg-FFsxO61qxSofbTrA .icon-shape .label{text-anchor:middle;}#mermaid-svg-FFsxO61qxSofbTrA .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-FFsxO61qxSofbTrA .rough-node .label,#mermaid-svg-FFsxO61qxSofbTrA .node .label,#mermaid-svg-FFsxO61qxSofbTrA .image-shape .label,#mermaid-svg-FFsxO61qxSofbTrA .icon-shape .label{text-align:center;}#mermaid-svg-FFsxO61qxSofbTrA .node.clickable{cursor:pointer;}#mermaid-svg-FFsxO61qxSofbTrA .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-FFsxO61qxSofbTrA .arrowheadPath{fill:#333333;}#mermaid-svg-FFsxO61qxSofbTrA .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-FFsxO61qxSofbTrA .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-FFsxO61qxSofbTrA .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FFsxO61qxSofbTrA .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-FFsxO61qxSofbTrA .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FFsxO61qxSofbTrA .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-FFsxO61qxSofbTrA .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-FFsxO61qxSofbTrA .cluster text{fill:#333;}#mermaid-svg-FFsxO61qxSofbTrA .cluster span{color:#333;}#mermaid-svg-FFsxO61qxSofbTrA div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-FFsxO61qxSofbTrA .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-FFsxO61qxSofbTrA rect.text{fill:none;stroke-width:0;}#mermaid-svg-FFsxO61qxSofbTrA .icon-shape,#mermaid-svg-FFsxO61qxSofbTrA .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FFsxO61qxSofbTrA .icon-shape p,#mermaid-svg-FFsxO61qxSofbTrA .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-FFsxO61qxSofbTrA .icon-shape .label rect,#mermaid-svg-FFsxO61qxSofbTrA .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FFsxO61qxSofbTrA .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-FFsxO61qxSofbTrA .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-FFsxO61qxSofbTrA :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} @kit.CameraKit
内部映射
@ohos.multimedia.camera
@ohos.multimedia.image
相机相关其他模块

5.2 完整的 @kit 对照表

@kit 引用	对应 @ohos 路径	主要能力
@kit.AbilityKit	@ohos.app.ability.UIAbility 等	UIAbility、common、Want、Permissions
@kit.ArkUI	@ohos.window 等	window 窗口管理
@kit.CameraKit	@ohos.multimedia.camera	相机采集、预览、拍照
@kit.CoreFileKit	@ohos.file.fs	文件 I/O 操作
@kit.MediaLibraryKit	@ohos.multimedia.mediaLibrary	相册读写
@kit.BasicServicesKit	@ohos.pasteboard 等	剪贴板、系统服务
@kit.PerformanceAnalysisKit	@ohos.hilog 等	日志、性能分析
@kit.ConnectivityKit	@ohos.nfc.tag 等	NFC、蓝牙、WiFi
@kit.ScanKit	@ohos.multimedia.scan	二维码扫描

5.3 @kit 导入实战

// ===== 项目实际使用的 @kit 导入 =====

// 1. UIAbility 相关
import { AbilityConstant, UIAbility, Want, common } from '@kit.AbilityKit';

// 2. 相机功能
import { camera } from '@kit.CameraKit';

// 3. 文件系统
import { fileIo as fs } from '@kit.CoreFileKit';

// 4. 相册访问
import { photoAccessHelper } from '@kit.MediaLibraryKit';

// 5. 日志记录
import { hilog } from '@kit.PerformanceAnalysisKit';

// 6. 窗口管理
import { window } from '@kit.ArkUI';

// 7. 剪贴板（pasteboard 分享）
import { pasteboard } from '@kit.BasicServicesKit';

// 8. NFC 近场通信
import { tag } from '@kit.ConnectivityKit';

---

六、HAR/HSP/HAP 包类型与依赖

6.1 三种包类型

HarmonyOS 项目中有三种包类型，用途各不相同：

包类型	全称	用途	是否可独立安装
HAP	HarmonyOS Ability Package	可独立运行的应用包	✅
HSP	HarmonyOS Shared Package	进程内共享库	❌（随主 HAP 安装）
HAR	HarmonyOS Archive	静态库（源码共享）	❌（编译时嵌入）

6.2 本地 HAR 依赖

项目可以依赖本地的 HAR 包：

// entry/oh-package.json5 引用本地 HAR
{
  "dependencies": {
    "@local/common-ui": "file:../local_har/common-ui"
  }
}

6.3 依赖最佳实践

引用第三方依赖时的建议：

• 优先使用系统内置 @kit 包：性能最优，无需安装，随系统更新
• ohpm 官方仓库包 ：从 ohpm.openharmony.cn 获取经过华为审核的包
• 谨慎使用 npm 生态包：鸿蒙不直接支持 npm 包，需经过专门的适配（HAR 包形式）

---

七、ohpm 进阶：版本策略与依赖安全

7.1 SemVer 语义化版本与范围符号

ohpm 遵循 SemVer 语义化版本 规范。版本格式为 MAJOR.MINOR.PATCH：

版本变更	规则	示例
MAJOR	不兼容的 API 变更	1.x.x → 2.0.0
MINOR	向后兼容的新功能	1.2.x → 1.3.0
PATCH	向后兼容的 bug 修复	1.2.3 → 1.2.4

版本范围符号：

{
  "dependencies": {
    "libA": "1.0.0",      // 精确版本 --- 强烈推荐用于生产
    "libB": "^1.2.0",     // 兼容版本 --- 允许 1.x.x 但不允许 2.0.0
    "libC": "~1.2.0",     // 补丁版本 --- 只允许 1.2.x
    "libD": ">=1.0.0 <2.0.0"  // 范围指定
  }
}

最佳实践 ：生产项目建议使用精确版本（如 "1.2.3" 而非 "^1.2.3"），配合 oh-package-lock.json5 确保每次构建结果完全一致。

7.2 oh-package-lock.json5 锁定文件

lock 文件自动生成，记录每个依赖包的精确安装版本：

// oh-package-lock.json5（自动生成，不要手动编辑）
{
  "modelVersion": "5.1.0",
  "selfVersion": "1.0.0",
  "dependencies": {
    "axios": {
      "version": "1.6.8",         // 精确安装版本
      "resolved": "https://ohpm.openharmony.cn/...",
      "integrity": "sha512-...",   // 包完整性校验 hash
      "dependencies": {}          // 间接依赖树
    }
  }
}

lock 文件的规范：

1. 提交到 Git：确保团队所有成员使用完全相同的依赖版本
2. 不要手动编辑 ：只通过 ohpm install / ohpm update 更新
3. CI/CD 使用 ohpm ci ：在 CI 环境中用 ohpm ci（不会更新 lock）而非 ohpm install

7.3 ohpm 常见问题排查

问题现象	可能原因	解决方案
ohpm install 超时	网络代理问题	设置 .ohpmrc 镜像或关闭代理
找不到 @kit.* 包	SDK 版本不匹配	在 SDK Manager 中安装对应版本
依赖版本冲突	多个包依赖了同一包的不兼容版本	使用 ohpm why 包名 排查依赖树
模块间循环依赖	HAR 模块互相依赖	重新规划模块边界
本地 HAR 找不到	file: 路径错误	使用相对于 oh-package.json5 的路径

# 常用排查命令
ohpm list              # 显示所有已安装的包和版本
ohpm why axios         # 查看 axios 为何被安装（依赖链）
ohpm outdated          # 列出所有可更新的包
ohpm audit             # 安全漏洞扫描（华为官方包仓库）

7.4 Mermaid：ohpm 依赖管理流程

#mermaid-svg-LHAqXHSqPIPxqafi{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-LHAqXHSqPIPxqafi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-LHAqXHSqPIPxqafi .error-icon{fill:#552222;}#mermaid-svg-LHAqXHSqPIPxqafi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-LHAqXHSqPIPxqafi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-LHAqXHSqPIPxqafi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-LHAqXHSqPIPxqafi .marker.cross{stroke:#333333;}#mermaid-svg-LHAqXHSqPIPxqafi svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-LHAqXHSqPIPxqafi p{margin:0;}#mermaid-svg-LHAqXHSqPIPxqafi .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-LHAqXHSqPIPxqafi .cluster-label text{fill:#333;}#mermaid-svg-LHAqXHSqPIPxqafi .cluster-label span{color:#333;}#mermaid-svg-LHAqXHSqPIPxqafi .cluster-label span p{background-color:transparent;}#mermaid-svg-LHAqXHSqPIPxqafi .label text,#mermaid-svg-LHAqXHSqPIPxqafi span{fill:#333;color:#333;}#mermaid-svg-LHAqXHSqPIPxqafi .node rect,#mermaid-svg-LHAqXHSqPIPxqafi .node circle,#mermaid-svg-LHAqXHSqPIPxqafi .node ellipse,#mermaid-svg-LHAqXHSqPIPxqafi .node polygon,#mermaid-svg-LHAqXHSqPIPxqafi .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-LHAqXHSqPIPxqafi .rough-node .label text,#mermaid-svg-LHAqXHSqPIPxqafi .node .label text,#mermaid-svg-LHAqXHSqPIPxqafi .image-shape .label,#mermaid-svg-LHAqXHSqPIPxqafi .icon-shape .label{text-anchor:middle;}#mermaid-svg-LHAqXHSqPIPxqafi .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-LHAqXHSqPIPxqafi .rough-node .label,#mermaid-svg-LHAqXHSqPIPxqafi .node .label,#mermaid-svg-LHAqXHSqPIPxqafi .image-shape .label,#mermaid-svg-LHAqXHSqPIPxqafi .icon-shape .label{text-align:center;}#mermaid-svg-LHAqXHSqPIPxqafi .node.clickable{cursor:pointer;}#mermaid-svg-LHAqXHSqPIPxqafi .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-LHAqXHSqPIPxqafi .arrowheadPath{fill:#333333;}#mermaid-svg-LHAqXHSqPIPxqafi .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-LHAqXHSqPIPxqafi .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-LHAqXHSqPIPxqafi .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-LHAqXHSqPIPxqafi .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-LHAqXHSqPIPxqafi .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-LHAqXHSqPIPxqafi .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-LHAqXHSqPIPxqafi .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-LHAqXHSqPIPxqafi .cluster text{fill:#333;}#mermaid-svg-LHAqXHSqPIPxqafi .cluster span{color:#333;}#mermaid-svg-LHAqXHSqPIPxqafi div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-LHAqXHSqPIPxqafi .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-LHAqXHSqPIPxqafi rect.text{fill:none;stroke-width:0;}#mermaid-svg-LHAqXHSqPIPxqafi .icon-shape,#mermaid-svg-LHAqXHSqPIPxqafi .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-LHAqXHSqPIPxqafi .icon-shape p,#mermaid-svg-LHAqXHSqPIPxqafi .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-LHAqXHSqPIPxqafi .icon-shape .label rect,#mermaid-svg-LHAqXHSqPIPxqafi .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-LHAqXHSqPIPxqafi .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-LHAqXHSqPIPxqafi .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-LHAqXHSqPIPxqafi :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
oh-package.json5
ohpm install
解析依赖树
lock 文件存在?
按 lock 文件精确安装
按版本范围解析最新版
下载到 oh_modules/
生成 oh-package-lock.json5
DevEco Studio 编译打包

---

八、注意事项与常见问题

8.1 开发注意事项

在实际开发过程中，需特别注意以下几点：

• API 兼容性：部分接口仅在特定 HarmonyOS NEXT 版本中可用，需做版本条件判断
• 权限模型：采用静态声明（module.json5）+ 动态申请（requestPermissionsFromUser）的两阶段授权
• 生命周期 ：合理使用 aboutToAppear() 和 aboutToDisappear() 管理资源初始化与释放
• 状态同步 ：跨页面数据通过 AppStorage 共享，组件内状态使用 @State / @Prop / @Link 装饰器

8.2 常见错误与解决方案

常见问题快速排查表：

问题类型	排查方向	参考方法
应用崩溃	查看 hilog 错误日志	hilog.error(TAG, "...", e.message)
状态丢失	检查 AppStorage 键名拼写	统一使用常量管理键名
动画不流畅	避免在 animateTo 回调中执行 I/O	动画与数据操作分离

总结

oh-package.json5 和 ohpm 是鸿蒙项目的基础设施：

1. 两级结构：根级（全局共用）+ 模块级（专有），类似 npm workspace
2. @kit 包：系统内置，无需安装，直接 import，是 HarmonyOS NEXT 的推荐导入方式
3. 版本控制：遵循 SemVer，lock 文件确保版本一致性
4. 包类型：HAP（可运行）、HSP（运行时共享）、HAR（静态库），合理选择依赖类型
5. ohpm 命令：与 npm 语法高度相似，学习成本低

下一篇预告 ：第05篇 路由配置与 main_pages.json 详解

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• ohpm 包管理器官方文档
• oh-package.json5 配置参考
• HAR/HSP 模块共享指南
• @kit 系统能力包概览
• SemVer 语义化版本规范（中文）
• 第03篇 module.json5
• 第06篇 目录结构
• 第10篇 模块导入详解
• DevEco Studio 依赖管理