OpenHarmony开发中的知识：区分工程级与模块级—package.json

 从OHPM 5.0.0版本开始，支持区分工程级与模块级oh-package.json5配置。其中：

• 工程级oh-package.json5文件：位于工程根目录下，主要用来描述全局配置，如：依赖覆盖（overrides）、依赖关系重写（overrideDependencyMap）和参数化配置（parameterFile）等，详情请见：工程级oh-package.json5 字段。
• 模块级oh-package.json5文件：位于工程各个模块的根目录下，用来描述包名、版本、入口文件（类型声明文件）和依赖项等信息，详情请见：模块级oh-package.json5 字段。

开发者可将标准的DevEco Studio工程下的各个模块打成HAR包后，发布到OpenHarmony三方库中心仓；所有发布到仓库的包必须包含模块级oh-package.json5文件，以描述当前包基本信息。

工程级oh-package.json5 字段

配置项	字段名称	字段说明	字段要求	字段类型	默认值	备注
开发态版本	modelVersion	开发态版本号	必选	字符串	无	开发态版本号。
描述配置	description	简介	可选	字符串	无	用于描述工程信息的字符串。
依赖配置	dependencies	生产依赖	可选	对象	{}	用于配置参与编译/运行阶段使用的依赖，声明需要在代码中import的三方库（推荐在模块级oh-package.json5中配置生产依赖）。
	devDependencies	开发依赖	可选	对象	{}	配置开发态依赖，配置只能参与项目的开发或测试阶段的依赖。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（如手机）上使用，则不能在其中配置。
	dynamicDependencies	动态依赖	可选	对象	{}	配置项目动态依赖的HSP模块。在开发者需要动态加载HSP的时候配置使用（不推荐在工程级配置）。
	overrides	依赖覆盖配置	可选	对象	{}	支持将依赖树中的包替换为另一个指定版本，详情见overrides。
	overrideDependencyMap	重写依赖关系	可选	对象	{}	支持将依赖树中包的子依赖替换为配置文件中配置的依赖，详情见overrideDependencyMap。
其他	scripts	自定义脚本	可选	对象	{}	维护一个脚本别名到脚本内容的映射表，开发者可以通过ohpm run <脚本别名>来触发对应脚本内容的执行。
	hooks	钩子	可选	对象	{}	安装或卸载的钩子设置，包含 "preInstall", "postInstall", "preUninstall", "postUninstall","preVersion", "postVersion", "prePublish", "postPublish" 字段。仅支持执行当前工程中的 hooks，不支持执行依赖中的 hooks。
	parameterFile	参数化配置文件路径	可选	字符串	无	标识是否开启参数化。未配置：关闭参数化；已配置：开启参数化。需同时指定参数化配置文件路径，详见parameterFile。

模块级oh-package.json5字段说明

配置项	字段名称	字段说明	字段要求	字段类型	默认值	备注
描述配置	name	名称	必选	字符串	无	格式如 @group/packagename，全局唯一。除了 @ 和 / 之外，group 和 packagename 只能包含小写字母、数字、_ 和 - 组成，总长度小于等于128个字符，且必须以字母开头，也不能是ArkTS 的保留关键字。
	version	版本号	必选	字符串	1.0.0	必须遵循 semver 语义化规范，从1.0.0开始。
	description	简介	可选	字符串	无	用于描述三方库信息的字符串，有助于被搜索发现。
	keywords	关键字	可选	数组	[]	关键字信息数组，便于搜索使用。例如：["tools", "project"]。
	author	作者	可选	对象或字符串	无	包含 name 字段（可选）和 email 字段（可选），例如："author": {"name": "xxx" , "email": "xxx@xxx.com" }。或者直接为作者名称，例如："author": "xxx"。 name字段允许使用字母、数字，点（.），中划线（-），下划线（_），空格，中文。其中首字母必须为英文字母。
	homepage	主页链接	可选	字符串	""	通常是项目gitee链接。
	repository	仓库地址	可选	字符串	""	开源代码仓库地址。在私仓管理界面的系统设置处可定义是否为必填。
	license	开源协议	必选	字符串	"ISC"	当前项目的开源许可证。遵循 spdx license 规范。许可证若为 GPL，repository 建议不为空。
依赖配置	dependencies	生产依赖	可选	对象	{}	用于配置参与编译/运行阶段使用的依赖，声明需要在代码中import的三方库（参与编译/运行阶段使用的依赖）。
	devDependencies	开发依赖	可选	对象	{}	用于配置开发态依赖，只能参与项目的开发或测试阶段。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（手机）上使用，则不能在其中配置。
	dynamicDependencies	动态依赖	可选	对象	{}	用于配置项目动态依赖的HSP模块。在开发者需要动态加载HSP的时候配置使用。
文件配置	main	入口	必选	字符串	无	指定加载的入口文件。
	types	类型定义	可选	字符串	""	指定类型定义的文件名。当用 typescript 定义新的类型，需要提供给其他开发者使用，则需要指定其声明文件，一般为 .d.ts，.d.ets 文件。
兼容性检测相关配置	compatibleSdkVersion	SDK版本	可选	字符串	无	三方库开发者使用的SDK版本，构建时由hvigor自动填充，提供给SDK做兼容性检测。 在prepublish、publish时，ohpm会对该字段进行检测(非空和长度校验)，并根据.ohpmrc中开关 compability_log_leve配置的值进行提示或报错处理。 配置示例参看兼容性字段配置示例。
	compatibleSdkType	SDK类型	可选	字符串	无	三方库开发者使用的SDK类型，构建时由hvigor自动填充，提供给SDK做兼容性检测, 示例值："OpenHarmony"、"HarmonyOS"。 在prepublish、publish时，ohpm会对该字段进行检测(非空和长度校验)，并根据.ohpmrc中开关 compability_log_level配置的值进行提示或报错处理。 配置示例参看兼容性字段配置示例。
	obfuscated	混淆标识	可选	布尔	无	三方库是否开启混淆标识，构建时由hvigor自动填充，提供给SDK做兼容性检测。 在prepublish、publish时，ohpm会对该字段进行检测(非空校验)，并根据.ohpmrc中开关 compability_log_level配置的值进行提示或报错处理。 配置示例参看兼容性字段配置示例。
	nativeComponents	native so依赖配置	可选	数组	无	三方库使用的so包配置，构建时由hvigor自动填充，提供给SDK做兼容性检测。 对于用户自行引入的so依赖(存放于libs目录)，需要用户手动维护该数组，数组单个元素类型为对象，对象内可配置的字段有：name、compatibleSdkVersion、compatibleSdkType。 在prepublish、publish时，如果包内存在so包，则ohpm会对该字段进行检测，并根据.ohpmrc中开关 compability_log_level 配置的值进行提示或报错处理；反之则不检测该字段。 配置示例参看兼容性字段配置示例。
其他	artifactType	类型	可选	字符串	"original"	OpenHarmony包制品类型，有两个选项：original、obfuscation。original：源码，即发布源码(.ts/.ets)；obfuscation：混淆代码，即源码经过混淆之后发布上传。
	scripts	自定义脚本	可选	对象	{}	维护一个脚本别名到脚本内容的映射表，开发者可以通过ohpm run <脚本别名>来触发对应脚本内容的执行。
	hooks	钩子	可选	对象	{}	安装或卸载的钩子设置，包含 "preInstall", "postInstall", "preUninstall", "postUninstall","preVersion", "postVersion", "prePublish", "postPublish" 字段。仅支持执行当前工程中的 hooks，不支持执行依赖中的 hooks。
	category	检查规则白名单	可选	对象	{}	在私仓管理界面配置后自动生成，白名单为分号隔开的字符串列表，每个列表项必须是一个由大小写字母或下划线组成的字符串，包含在白名单中的配置项，不再做规则检查。
	packageType	包类型	可选	字符串	InterfaceHar	标识模块是否为HSP包，在新建Shared Library时会自动生成该字段，并默认赋值为"InterfaceHar"；Static Library中没有该字段，标识为普通HAR包。

注意

在oh-package.json5文件中dependencies、devDependencies、dynamicDependencies节点声明本地依赖时，配置的依赖名必须和依赖包的包名（即包内oh-package.json5中配置的name）一致，否则会有警告提示。若希望将告警升级为报错并中断命令执行，可以通过在.ohpmrc中配置enforce_dependency_key=true，详情请参考enforce_dependency_key。

兼容性字段配置示例

三方库开发者使用的SDK和当前集成该三方库工程编译时使用的SDK可能存在不一致的情况。因此，ohpm新增了兼容性检测相关配置以帮助SDK做兼容性分析。配置示例如下：

{
  "name": "library",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "Index.ets",
  "license": "Apache-2.0",
  "dependencies": {
    "liblibrary.so": "file:./src/main/cpp/types/liblibrary"
  },
  "compatibleSdkVersion": 12,
  "compatibleSdkType": "HarmonyOS",
  "obfuscated": false,
  "nativeComponents": [
    {
      "name": "liblibrary.so",
      "compatibleSdkVersion": 12,
      "compatibleSdkType": "HarmonyOS"
    }
  ]
}

创建一个新的oh-package.json5文件

通过命令行创建 oh-package.json5文件，执行如下命令：

1.导航到包的目录。

cd /path/to/package

2.执行初始化命令，并按照问卷填写相关参数。

• 对无命名空间模块，执行以下命令：

ohpm init

• 对有命名空间模块，执行以下命令：

ohpm init --group group_name

3.若跳过问卷填写，创建默认文件，可在初始化命令行加上配置参数 --yes。

ohpm init --yes

默认创建的oh-package.json5 文件示例：

{
 "name": "package_name",
 "version": "1.0.0",
 "description": "",
 "main": "index.ts",
 "author": "",
 "license": "ISC",
 "dependencies": {}
}

依赖配置说明

ohpm 存在 dependencies，devDependencies和dynamicDependencies 三种依赖类型。同时支持具体版本号，范围版本号，tag标签，本地har/tgz文件路径和本地源码目录多种方式引入依赖。

1. dependencies：生产依赖，即参与编译/运行阶段使用的依赖，用来定义生产态HAR/HSP包依赖，声明在代码中被 import的三方库。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（手机）上使用，则必须配置。
2. devDependencies：开发态依赖，只能参与项目的开发或测试阶段的依赖。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（如手机）上使用，则不能配置在该字段中。
3. dynamicDependencies：动态依赖，用来配合动态import，表达动态 import 使用的HSP 包依赖。动态依赖不会在加载时就被编译，而是根据条件导入模块或者按需导入模块，具有更高效的依赖加载速度。
4. 依赖配置示例：

{
  "dependencies": {
    // 具体版本号引入，支持符合semver标准的版本号
    "specific_version": "1.0.0",

    // 范围版本号引入，^引入1.x.x的最新版本，~引入1.0.x的最新版本。范围版本优先选取正式版本，无匹配的正式版本才会选取先行版本
    "scope_version": "^1.0.1",

    // tag标签引入，示例引入标签为"beta"对应的版本号
    "tag_version": "tag:beta",

    // 本地文件引入，可引入本地har/tgz文件
    "local_file": "file:./xx.har",
    // 本地源码引入，可引入本地其他模块的源码，示例直接引入本地的"module1"模块
    "local_source_code": "file:../module1"
  },
  "devDependencies": {
    // 支持依赖引入类型同dependencies
  },
  "dynamicDependencies": {
    // 支持依赖引入类型同 dependencies
  }
}

overrides

ohpm客户端在1.4.0版本开始支持Override机制，可以在项目级别的oh-package.json5（即项目根目录下的oh-package.json5）文件中添加overrides配置，方便将依赖树中的依赖替换为另一个版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的HAR包或源码目录。

例如，想要确保foo始终安装1.0.0版本，可以在项目级的oh-package.json5中增加如下配置：

overrides必须配置在项目级别的oh-package.json5中，配置在模块级别的oh-package.json5中将不会生效。

{
  "overrides": {
    "foo": "1.0.0"
  }
}

若本地存在foo的源码或者HAR包，想确保foo始终使用您本地的版本，可以在项目级的oh-package.json5中如下配置：

{
   "overrides": {
      // 本地存在"foo"的源码目录，如项目根目录下的foo目录
      // "foo": "file:./foo" 
      // 本地存在"foo"的HAR文件，如项目根目录下的libs目录中的foo.har
      "foo": "file:./libs/foo.har"
   }
}

parameterFile

OHPM新增了参数化配置功能。开发者可在项目根目录配置一个参数化文件（json格式文件），在该文件中维护模块或依赖版本信息，不同模块将根据该文件中的版本进行配置，满足不同构建场景下，开发者快速切换依赖版本的需要。同时，支持通过命令行指定参数化文件，降低流水线场景下模块和依赖版本的变更难度。

OHPM客户端在1.6.0版本开始支持参数化配置。可以在项目级别的oh-package.json5文件（即项目根目录下的oh-package.json5）中添加parameterFile配置，并同时指定parameterFile文件路径。配置规则如下：

• 文件路径支持配置相对路径，并以项目根目录为起点；
• 配置文件内容采用json5格式，支持多层json对象嵌套；
• 参数化key由字母、数字、_ 和 - 组成且只能以字母开头，大小写敏感；
• 参数化value类型只能是"string"或"object", value类型为string时，需符合semver规范。

说明

1. parameterFile字段必须配置在项目级别的oh-package.json5中，否则将不会生效或产生报错提示。
2. parameterFile配置文件位置可以通过命令行选项'-pf <string>' 或 '--parameterFile <string>'指定，但必须先在项目级别oh-package.json5中配置parameterFile字段，否则会报错提示；支持该选项的命令有：install、list、version。
3. parameterFile字段配置后，不允许执行update命令、uninstall命令和指定包名安装（如：'ohpm i <pkg>'）。
4. parameterFile文件路径大小写不敏感，不建议通过大小写来区分不同的配置文件。
5. oh-package.json5中支持参数化的字段有：version、dependencies、devDependencies和dynamicDependencies，未列举的字段均不支持参数化配置。

oh-package.json5示例：

{
  "name": "parameter-test",
  "version": "@param:version", //使用时必须以 '@param:' 开头
  "description": "test desc.",
  "main": "index.ets",
  "author": "test author",
  "license": "ISC",
  "dependencies": {
    "libtest1": "@param:dependencies.libtest1"
  },
  "devDependencies": {
    "libtest2": "@param:devDependencies.libtest2"
  },
  "dynamicDependencies": {
    "libtest3": "@param:dynamicDependencies.libtest3"
  },
  "parameterFile": './parameterFile/parameterFile.json5' // 开启参数化并指定参数化配置文件路径
}

parameterFile所指向文件的配置示例：

{
  "version": "1.0.0",
  "dependencies": {
    "libtest1": "1.0.1"
  },
  "devDependencies": {
    "libtest2": "*"
  },
  "dynamicDependencies": {
    "libtest3": "latest"
  }
}

overrideDependencyMap

OHPM客户端在1.7.0版本开始支持使用overrideDependencyMap机制重写源码模块或三方库的依赖关系。开发者可在工程级oh-package.json5文件中新增overrideDependencyMap配置，在该配置对象中通过key-value形式配置依赖关系重写文件；其中，key为依赖标识符，value为依赖关系重写文件路径。在依赖安装时， ohpm会将依赖树中的某个依赖节点的所有直接子依赖替换为对应依赖关系重写文件中配置的依赖项，依赖关系重写文件中支持配置的依赖类型为dependencies、devDependencies、dynamicDependencies，通过使用overrideDependencyMap机制，可以满足开发者在不同场景下，动态变更依赖的需求。

同时，支持在.ohpmrc中使用projectPackageJson配置项来覆盖项目根目录下oh-package.json5中的配置，方便开发者快速切换配置，详情见 ohpmrc中projectPackageJson配置。

配置说明

• 配置格式

  "[@group/]libname[@version]" : "config_path"，其中 [@group/]libname[@version] 为依赖标识符key, config_path为配置文件路径value。

• 配置示例

{
  "overrideDependencyMap": {
  "@group/libname": "dep-test.json5"
  }
}

• 配置约束
  • overrideDependencyMap必须配置在工程级oh-package.json5中，配置在模块级oh-package.json5中将不会生效。
  • key中@version部分可选，未指定@version时，替换所有名称为@group/libname的依赖的直接子依赖；指定@version时，替换所有名称为@group/libname且版本为version的依赖的直接子依赖，同时，version需符合semver规范，不支持tags、range version。
  • value是一个json5文件路径，文件内只支持配置：dependencies、devDependencies、dynamicDependencies。
  • value对应的文件路径只支持绝对路径，配置为相对路径时，需要手动设置.ohpmrc文件中odm_r2_project_root=true, 此时，相对路径会从项目根目录为起点开始解析。

overrideDependencyMap场景示例

• 模块entry下oh-package.json5配置了一个远程包依赖libbase，如下所示：

{
  "name": "entry",
  "version": "1.0.0",
  "main": "Index.ets",
  "license": "Apache-2.0",
  "dependencies": {
    "libbase": "1.0.0"
  }
}

• 依赖libbase的oh-package.json5内容，存在一个子依赖lib1，如下所示：

{
  "name": "libbase",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "Index.ets",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {
    "lib1": "1.0.0" //子依赖
  }
}

• 项目根目录oh-package.json5内容，如下所示：

{
  "name": "overridedependencymaptest",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "overrideDependencyMap": {      
    "libbase": "D:\\overrideDependencyMapTest\\dep-debug.json5" //overrideDependencyMap依赖替换配置，可配置多条
  }
}

• 配置文件dep-debug.json5中依赖配置如下所示：

{
  "dependencies": { // 详细依赖配置
    "lib1": "1.0.0",
    "log4js": "1.0.0"
  },
  "devDependencies": {
  },
  "dynamicDependencies": {
  }
}

• entry模块下执行：ohpm i, 由于entry下依赖了libbase，而libbase在overrideDependencyMap有配置，此时会使用dep-debug.json5文件内的依赖覆盖libbase的dependencies、devDependencies、dynamicDependencies节点，最终，entry模块会安装libbase、lib1、log4js（无overrideDependencyMap配置覆盖时，只会安装：libbase、lib1）。
• entry list结果如下：

entry 1.0.0 D:\overrideDependencyMapTest\entry
└── libbase 1.0.0
    └── lib1 1.0.0
    └── log4js 1.0.0

.ohpmrc中projectPackageJson配置

通过在.ohpmrc文件中配置projectPackageJson，可同时实现对overrides、overrideDependencyMap字段配置的效果，替换项目级oh-package.json5文件中相应的配置，方便开发者在不同使用场景下快速切换使用。配置格式及使用约束如下所示：

• 配置格式

  projectPackageJson:<project_root>=<config_path>, 其中 projectPackageJson:<project_root> 部分视做key, config_path 部分视做value。配置key指定项目根目录路径（绝对路径），配置value指定json5格式配置文件路径用以覆盖项目级oh-package.json5中的配置。

• 配置示例

  projectPackageJson:D:\test\TestProject=projectPackageJson.json5

• 配置约束
  • key必须以 'projectPackageJson:' 开头；project_root表示项目根路径。
  • value对应json5文件内只支持配置：overrides、overrideDependencyMap，不支持 parameterFile(编辑器和编译器无法识别)。
  • 对同一个project_root，如存在多条projectPackageJson配置路径，仅最后一条会生效。
  • value对应的文件路径支持绝对路径和相对路径，配置为相对路径时，从项目根目录为起点开始解析。

示例

下面演示在.ohpmrc中配置同一工程的不同环境下的projectPackageJson配置，当配置生效时，会直接覆盖项目级oh-package.json5中对应配置。

• 在项目级或用户级.ohpmrc中增加2条配置，分别对应开发、Release环境，如下所示：

registry=http://localhost:8088/repos/ohpm
log_level=debug
strict_ssl=false
projectPackageJson:D:\overrideDependencyMapTest=oh-pkg-debug.json5 //debug环境配置
projectPackageJson:D:\overrideDependencyMapTest=oh-pkg-release.json5 //release环境配置，.ohpmrc中存在同一工程的多条配置时默认按配置先后顺序取最后一条，即当前配置生效

• 文件oh-pkg-release.json5配置，新增了一条依赖libbase的配置，如下所示：

{
  "overrideDependencyMap": {
    "libbase": "D:\\overrideDependencyMapTest\\dep-release.json5"
  }
}

• Release环境下libbase的依赖依赖替换文件dep-release.json5中依赖配置如下所示：

  {
    "dependencies": {
      "lib1": "1.0.0"，
      "lib2": "2.0.0",
      "lib3": "3.0.0"
    }
  }

• 基于 overrideDependencyMap场景示例 工程，在entry模块下执行：ohpm i，此时，在ohpm运行时中会将项目级oh-package.json5中的配置会变更为：

{
  "name": "overridedependencymaptest",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "overrideDependencyMap": {
    "libbase": "D:\\overrideDependencyMapTest\\dep-release.json5"
  }
}

• 最终安装结果如下：

  entry 1.0.0 D:\overrideDependencyMapTest\entry
  └── libbase 1.0.0
      └── lib1 1.0.0
      └── lib2 2.0.0
      └── lib3 3.0.0

• oh-package-lock.json5

  oh-package-lock.json5用于锁定所有依赖的版本，以及缓存依赖的元数据信息。不建议开发者手动修改该文件的内容，也不建议开发者使用其他分析工具直接读取该文件的内容。

  建议将oh-package-lock.json5文件提交到代码仓库中进行版本管理。优点如下：

• 确保构建可复现： oh-package-lock.json5文件记录了三方包安装时确切的依赖树，其中包括每个依赖的版本、子依赖及其版本等详细信息。将该文件提交到代码仓库，能够确保团队成员、持续集成（CI）服务器或其他任何克隆该项目的用户，在执行ohpm install时可以获得完全一致的依赖版本，从而保证项目的可复现构建。
• 提高安装速度： ohpm在安装依赖时，会优先使用oh-package-lock.json5锁定的版本信息，避免重新解析依赖版本，有效地加快安装过程。
• 安全性： 通过锁定依赖版本，oh-package-lock.json5可以帮助防止因上游依赖更新引入的安全漏洞。当发现依赖存在安全问题时，可以针对性地更新特定依赖版本，并将更新后的oh-package-lock.json5提交到仓库，确保所有使用者都获取到修复后的版本。
• 便于协同工作： 当团队成员在项目中添加、更新或删除依赖时，他们应运行ohpm update以更新oh-package-lock.json5。提交这些变更到仓库，可以让其他成员了解到依赖的变化，并在拉取最新代码后自动获取正确的依赖版本。

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？但是又不知道从哪里下手，而且学习时频繁踩坑，最终浪费大量时间。所以本人整理了一些比较合适的鸿蒙（HarmonyOS NEXT）学习路径和一些资料的整理供小伙伴学习

点击领取→纯血鸿蒙Next全套最新学习资料（安全链接，放心点击）