【HarmonyOS NAPI 深度探索9】发布到 npm 并管理版本

开发了一个强大的 N-API 模块后，下一步就是将它发布到 npm，让更多开发者可以使用。同时，随着模块的更新迭代，版本管理也非常重要。今天，我们将讲解如何将 N-API 模块发布到 npm，并通过版本号管理来维护模块的稳定性和新功能。

准备工作

在开始之前，确保以下条件已满足：

1. npm 账号：如果还没有 npm 账号，先到 npm 官网注册一个账号。

2. 配置 npm：在本地终端登录 npm 账号：

   npm login
   

3. 完成模块开发：确保你的 N-API 模块已经通过测试，并且所有必要的文件都已经准备好。

创建 package.json

如果项目中还没有 package.json 文件，可以使用以下命令自动生成：

npm init

按照提示填写模块的基本信息，包括：

• name：模块名称，必须是全局唯一的。
• version：初始版本号，例如 1.0.0。
• description：模块的简要描述。
• main：入口文件，一般为 index.js。
• keywords：与模块相关的关键词，便于搜索。
• author：开发者信息。
• license：许可证类型，一般为 MIT。

生成的 package.json 文件可能如下：

{"name": "harmonyos-napi-example","version": "1.0.0","description": "An example N-API module for HarmonyOS","main": "index.js","keywords": ["HarmonyOS", "N-API", "example"],"author": "Your Name","license": "MIT"
}

确保忽略不必要的文件

在项目根目录创建 .npmignore 文件，忽略不需要发布的文件，例如：

node_modules/
*.log
prebuilds/
test/

确保最终发布的包干净、精简。

测试模块的本地安装

在发布前，测试模块能否正常被其他项目安装。运行以下命令：

npm pack

这会生成一个 .tgz 文件，例如 harmonyos-napi-example-1.0.0.tgz，然后在另一个项目中安装：

npm install /path/to/harmonyos-napi-example-1.0.0.tgz

确认模块能正常工作后，再进行发布。

发布到 npm

1. 确保模块名称的可用性：如果模块名称不是私有的，需确保没有其他人占用。

   npm search harmonyos-napi-example
   

2. 发布模块：在模块目录下运行：

   npm publish
   

   如果是私有模块，需要添加 --access=restricted：

   npm publish --access=restricted
   

3. 检查发布是否成功：运行以下命令查看模块信息：

   npm info harmonyos-napi-example
   

管理版本

模块发布后，随着功能的增加和 bug 的修复，版本管理变得非常重要。

版本号规则

npm 使用语义化版本号（Semantic Versioning, SemVer）：

• 主版本号（Major）：做了不兼容的重大更改时递增。
• 次版本号（Minor）：新增了向后兼容的功能时递增。
• 修订号（Patch）：修复了向后兼容的问题时递增。

例如，从 1.0.0 更新到：

• 2.0.0：不兼容的重大更改。
• 1.1.0：新增向后兼容的功能。
• 1.0.1：修复向后兼容的问题。

修改版本号

手动修改 package.json 中的 version，或使用 npm 提供的命令自动更新版本号：

npm version patch   # 修订号递增
npm version minor   # 次版本号递增
npm version major   # 主版本号递增

运行该命令后，package.json 中的版本号会自动更新，同时生成一个新的 Git 提交。

发布新版本

更新版本号后，重新运行：

npm publish

模块的废弃与取消发布

如果发布了错误的模块版本，npm 提供了以下操作：

1. 废弃模块版本：

   npm deprecate harmonyos-napi-example@"<1.0.0" "This version contains critical bugs."
   

   用户安装时会收到警告信息。

2. 取消发布模块：

   npm unpublish harmonyos-napi-example@1.0.0
   

   注意，取消发布的操作仅对最近 72 小时内发布的版本有效。

总结

通过 npm，发布和分发你的 N-API 模块变得非常简单。无论是初始化项目、测试本地安装，还是版本管理和更新，整个流程非常直观。

发布到 npm 不仅能让更多开发者使用你的模块，还能帮助你更好地管理模块的生命周期。所以，快动手试试，把你的 N-API 模块分享给全世界吧！