NPM包开发测试与发布
NPM包开发测试与发布
引言
在项目开发过程中，有时会遇到在多个项目中使用到具有相同或类似功能的工具方法，这时就需要将这些工具方法代码块在多个项目中分别定义，不方便统一管理。
针对以上情况，可以将这些公用的工具方法放入一个单独的项目中，打包发布到 NPM 上，在项目中通过npm包引用的方式使用工具方法。
进行开发之前，本地需要有 NodeJS 和 NPM 环境。
下面简要记录一下 NPM 工具包开发、测试与发布流程。
1. 开发步骤
开发步骤分为：项目创建、功能代码编写、源代码编译。
1.1. 项目创建
Step1： 首先创建一个空项目，使用 Webstorm 或者 VSCode 打开项目或者使用命令切换至项目根目录，创建 src 文件夹和 index.ts 文件。
其中 src 目录下存放工具类/工具方法的源码文件，index.ts 文件内容用于将工具类/工具方法导出，以便在其它模块导入使用。
Step2： 接着在项目中打开终端使用 git init 命令和 npm init 命令初始化项目的 git 信息和 npm 信息。
如果想将包发布成有作用域的包，使用如下命令：
npm init --scope=@my-username
也可以在使用 npm init 命令生成 package.json 文件后手动指定包名及其它信息。
下面进行工具类/工具方法的功能实现。
1.2. 功能代码编写
Step1： 在 src/ 目录下创建 ts 文件，在 ts 文件中编写使用到的工具类或者工具方法，编写完毕后使用 export 将类或者方法导出，以供其它模块使用。示例如下。
src/ArrayUtils.ts 文件内容如下：
/**
* 检验参数是否为数组，如果是，则原样返回，否则返回空数组
* @param arr
*/
export function arrayCheck(arr: any): Array {
if (Object.prototype.toString.call(arr) === '[object Array]') {
return arr;
} else {
return [];
}
}
export class ArrayUtils {
static arrayCheck(arr: any): Array {
return arrayCheck(arr);
}
}
Step2： 在 index.ts 文件中使用 export 将 src/ 目录下编写好的 ts 文件中的可导出项全部导出。示例如下。
index.ts 文件内容
export * from './src/ArrayUtils';
其它工具类或工具方法文件，同理，在 src/ 目录下创建文件编写好代码后，使用 export 导出，在 index.ts 文件中使用 export 将 src/ 目录下工具类文件内的类和方法全部导出，供其它模块使用。
工具类代码编写完毕后，下面对代码进行编译。
1.3. ts文件编译
在项目终端执行如下命令安装 typescript 依赖。
npm i typescript -D
在项目根目录下创建 tsconfig.json 文件，配置 ts 文件的 编译选项。
配置示例如下：
{
"compilerOptions": {
"baseUrl": "./",
"module": "es6",
"target": "es2020",
"allowJs": false,
"declaration": true,
"outDir": "./dist",
"strict": true
},
"exclude": [
"node_modules"
],
"include": [
"index.ts",
"src/*"
]
}
配置项含义：
baseUrl：模块解析的基准目录。module：指定生成哪个模块系统的代码。【这里需要提前了解不同模块系统之间的异同】target：指定ECMAScript目标版本。declaration：生成相应的 .d.ts文件。outDir：指定编译文件的输出路径。include：指定需要编译的文件。strict：启用所有严格类型检查选项。
更多配置选项信息，请查阅 TypeScript 配置选项。
配置完成后，在终端使用tsc命令将需要编译的ts文件编译成对应的js文件和.d.ts文件。
执行编译命令后，会生成编译文件。项目文件结构如下：
编译完毕后，修改 package.json 文件中的 main 属性值，让其指向编译后的 index.js 文件。
{
"name": "ts-utils",
"version": "1.0.0",
"description": "ts-utils",
"main": "./dist/index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"url": ""
},
"author": "",
"license": "ISC",
"devDependencies": {
"typescript": "^4.6.3"
}
}
进行到这一步，下面就可以在本地进行NPM包的测试了。
2. npm包本地测试
以下NPM包开发项目称为 项目A ，引用npm包的项目称为 项目B。
2.1. 将npm包文件引入项目
两种测试方式，具体介绍如下：
第一种：使用npm link命令关联依赖包使用
a. 在 项目A 的根目录下使用 npm link 命令将 npm包模块注册到全局，在全局的node_modules目录下会出现当前包所在项目的快捷方式引用。
E:\PersonalProject\ts-utils>npm link
audited 1 package in 1.121s
found 0 vulnerabilities
C:\Users\zhang\AppData\Roaming\npm\node_modules\ts-utils -> E:\PersonalProject\ts-utils
E:\PersonalProject\ts-utils>
b. 在 项目B 的根目录下使用 npm link package-name 命令将包关联到项目中，然后正常使用即可。
E:\PersonalProject\tsom-login>npm link ts-utils
E:\PersonalProject\tsom-login\node_modules\ts-utils -> C:\Users\zhang\AppData\Roaming\npm\node_modules\ts-utils -> E:\PersonalProject\ts-utils
E:\PersonalProject\tsom-login>
注意： 在 项目B 的 package.json 文件中加入依赖包，例如在dependencies项中加入以下依赖：
"ts-utils": "1.0.0"
此处的包名称和版本号对应 npm 包中 package.json 中定义的包名和版本号。
⚠ 注意： 如果不加此依赖项，会出现包无法引入，报错的情况。
测试没问题后，在 项目A 的根目录下使用 npm unlink 命令解除项目与全局的关联。在 项目B 的根目录下使用 npm unlink package-name 命令解除项目与本地npm包的关联。
第二种：复制 npm包 整个文件夹到 项目B 的 node_modules 目录下，在 package.json 中添加依赖项。
2.2. npm包功能测试
方法调用有以下两种方式：
1️⃣ 支持直接使用方法名称调用对应方法
import { arrayCheck } from 'ts-utils';
console.log(arrayCheck(undefined)); // []
console.log(arrayCheck([])); // []
2️⃣ 可以使用类名.方法名调用
import { ArrayUtils } from 'ts-utils';
console.log('arrayCheck ==? ', ArrayUtils.arrayCheck(undefined)); // []
console.log('arrayCheck ==? ', ArrayUtils.arrayCheck([1, 2, 3])); // [1, 2, 3]
3. 发布
1️⃣ 使用 npm login 命令，输入用户名密码登录npm。
2️⃣ 使用 npm publish 命令发布。
如果 npm 包作为有作用域的包进行发布，请使用如下命令：
npm publish --access public
4. 注意事项
发布之前到 npm 网站上确定一下 npm 包名是否已被其它用户使用，如果被占用，请更换。
可以将包名换成类似 @scope/package-name 的形式，将其作为一个有范围的公共包进行发布。