【Nodejs】1195- 怎樣開發(fā)一個(gè) Node.js 命令行工具包
1. 初始化項(xiàng)目
在一個(gè)合適的地方創(chuàng)建項(xiàng)目文件夾，為了演示，本次的項(xiàng)目名為 demo-cli，然后執(zhí)行以下命令初始化項(xiàng)目：
npm init
執(zhí)行以上命令之后，會(huì)先配置一些 package.json 的基礎(chǔ)信息，按提示輸入即可：
1.1 配置 package.json
為了方便，我們把項(xiàng)目從 vscode 中打開，然后對(duì) package.json 進(jìn)行詳細(xì)配置，篇幅有限，這里僅介紹其中比較重要的部分：
推薦閱讀：package.json 詳細(xì)配置。
1.1.1 name
項(xiàng)目名，同時(shí)也是發(fā)包的時(shí)候別人引入時(shí)的默認(rèn)名稱。
1.1.2 version
版本號(hào)，對(duì)于項(xiàng)目的每一次升級(jí)（引入新特性、打補(bǔ)丁、代碼重構(gòu)等），我們都需要對(duì)版本進(jìn)行升級(jí)，遵循 major、minor、patch 原則。
推薦閱讀：npm 語義化版本控制。
1.1.3 main
項(xiàng)目入口文件的位置，方便別人引入我們的包的時(shí)候，從哪里進(jìn)行解析，這里也是我們進(jìn)行接口導(dǎo)出的模塊地址，稍后會(huì)進(jìn)行詳細(xì)介紹。
1.1.4 scripts
腳本指令，在這里可以自定義一些指令。
npm 腳本的原理非常簡(jiǎn)單。每當(dāng)執(zhí)行?
npm run，就會(huì)自動(dòng)新建一個(gè) Shell，在這個(gè) Shell 里面執(zhí)行指定的腳本命令。因此，只要是 Shell（一般是 Bash）可以運(yùn)行的命令，就可以寫在 npm 腳本里面。比較特別的是，
npm run?新建的這個(gè) Shell，會(huì)將當(dāng)前目錄的?node_modules/.bin?子目錄加入?PATH?變量，執(zhí)行結(jié)束后，再將?PATH?變量恢復(fù)原樣。
推薦閱讀：npm scripts 使用指南。
1.1.5 bin
我們的項(xiàng)目所提供的自定義指令，以及對(duì)應(yīng)的可執(zhí)行文件的映射地址：
{
...
"bin": {
"demo-cli": "bin/demo-cli"
},
...
}
當(dāng)我們的自定義指令的名字就是項(xiàng)目名稱的時(shí)候，可以簡(jiǎn)寫為以下形式：
{
...
"bin": "bin/demo-cli",
...
}
1.2 bin 命令是如何運(yùn)行的
1.2.1 Linux bin 目錄的作用
shell 任務(wù)的一個(gè)重要部分是搜索命令。Bash 是按照下一的步驟來完成的：檢查命令是否包含斜杠。如果沒有，首先檢查函數(shù)列表是否包含一個(gè)我們尋找的命令。如果命令不是一個(gè)函數(shù)，那么在內(nèi)建命令列表中檢查。shell 內(nèi)建命令是指 bash（或其它版本）工具集中的命令。一般都會(huì)有一個(gè)與之同名的系統(tǒng)命令，比如 bash 中的 echo 命令與 /bin/echo 是兩個(gè)不同的命令，盡管他們行為大體相仿。當(dāng)在 bash 中鍵入一個(gè)命令時(shí)系統(tǒng)會(huì)先看他是否是一個(gè)內(nèi)建命令，如果不是才會(huì)查看是否是系統(tǒng)命令或第三方工具。所以在 bash 中鍵入 echo 命令實(shí)際上執(zhí)行 bash 工具集中的 bash 命令也就是內(nèi)建命令，而不是 /bin/echo 這個(gè)系統(tǒng)命令。備注：Linux 中的 type 命令如果命令既不是函數(shù)也不是內(nèi)建命令，那么掃描列在?PATH?中的目錄列表來進(jìn)行查找。
通常如果我們要在 Linux 中執(zhí)行自定義腳本，那么我們需要通過路徑的形式來執(zhí)行相應(yīng)的文件，如果我們?cè)?PATH 里的目錄中注冊(cè)了相應(yīng)的指令或者通過?alias?對(duì)這個(gè)路徑起了別名的話，就不需要輸入完整路徑。
linux 或者 MacOS 中的 bin 目錄一般是用來存放可執(zhí)行命令的文件夾，通常有：
/bin
/sbin
/usr/bin
/usr/local/bin
/usr/sbin
...
要具體了解這些目錄里有哪些指令，可以參考這篇文章：bin 目錄簡(jiǎn)單區(qū)別
1.2.2 node bin
首先，我們需要找到我們的 node 的安裝地址，這個(gè)可以通過在 Linux、MacOS 或者 VSCode 的終端里輸入一下指令來獲得：
echo $PATH
這會(huì)打印出當(dāng)前所配置的環(huán)境變量，一般我們安裝 node 的時(shí)候會(huì)自動(dòng)在 PATH 里加入，node 的可執(zhí)行腳本的目錄地址：
如上圖所示，其中?“/Users/hopewlliu/.nvm/versions/node/v14.17.3/bin”?便是本電腦 node 中所有所有全局指令所在位置。
以下為當(dāng)前電腦的全局指令、軟連接的指令及其所映射的文件地址：
軟鏈的創(chuàng)建方式很簡(jiǎn)單，比如我們對(duì)上圖的?imserver?添加一個(gè)新的軟鏈?imserver2，可以執(zhí)行一下指令：
ln -s ../lib/node_modules/@tencent/imserver-cli/bin/imserver ./imserver2
現(xiàn)在我們就可以在全局上使用?imserver2?命令了，他和?imserver?的效果是一致的。
同時(shí)想要?jiǎng)h除軟連接也很簡(jiǎn)單，只需要執(zhí)行以下指令即可：
rm ./imserver2
1.2.3 全局安裝與非全局安裝
1.2.3.1 全局安裝
如果我們通過?-g?的形式來安裝一個(gè)包的話，他會(huì)被安裝到 node 相關(guān)文件夾中，在本文即為：
“/Users/hopewlliu/.nvm/versions/node/v14.17.3/lib/node_modules”
目錄下，如果該包的 package.json 中存在 bin 字段的指令配置，同時(shí)會(huì)在：
“/Users/hopewlliu/.nvm/versions/node/v14.17.3/bin”
目錄下創(chuàng)建相應(yīng)的指令軟鏈。
1.2.3.2 非全局安裝
非全局安裝的包存在于我們的項(xiàng)目的根目錄的?node_modules?目錄下，如果該包存在自定義指令，那么會(huì)在安裝包的時(shí)候在當(dāng)前項(xiàng)目的根目錄的?node_modules/.bin?目錄下添加相應(yīng)的自定義指令的軟鏈接，想要執(zhí)行這個(gè)包的自定義指令，我們可以直接通過路徑的形式來找到該包指令所在位置然后執(zhí)行，但是通常的做法是在當(dāng)前的項(xiàng)目的 package.json 中添加相應(yīng)的?npm scripts?來執(zhí)行，原理就是?npm scrpits?在執(zhí)行的前一刻會(huì)開啟新的?shell?并把當(dāng)前項(xiàng)目的根目錄的?node_modules/.bin?目錄加入?PATH?環(huán)境變量中，然后在這個(gè)?shell?中執(zhí)行自定義的腳本指令，并在執(zhí)行完成之后將?PATH?恢復(fù)原樣。
1.2.4 目標(biāo)文件的執(zhí)行原理
解釋完指令的尋找與執(zhí)行后，我們需要探討一下相應(yīng)的腳本是如何被執(zhí)行的，通常我們寫的自定義腳本文件的入口文件的上方都需要寫上一行代碼：
#!/usr/bin/env node#!?是一個(gè)約定的標(biāo)記，它告訴系統(tǒng)這個(gè)腳本需要什么解釋器來執(zhí)行，即使用哪一種 Shell，比如我們?cè)趯懽远x shell 腳本的時(shí)候可以在腳本的第一行指定當(dāng)前腳本所使用的解釋器：
#!/bin/bash
#!/bin/zsh
...
這樣寫的目的是為了使該文件以可執(zhí)行程序去運(yùn)行的時(shí)候可以找到相應(yīng)的解釋器，當(dāng)然如果將文件所在位置作為參數(shù)傳遞給解釋器來執(zhí)行的話，則不需要在自定義腳本的第一行添加上述代碼（寫了也沒用），例如：
/bin/bash ./test.sh
...
說了這么多，那么我們的?“#!/usr/bin/env node“又有什么不同呢？
#!/usr/bin/env?是一種可移植指定解釋器的方式：簡(jiǎn)而言之，它表示：執(zhí)行?，無論你（第一次）在?$PATH?變量中列出的目錄中找到它（并隱式傳遞給文件的路徑）在眼前）。
說白了就是告訴系統(tǒng)，當(dāng)前的腳本需要通過 node 來執(zhí)行，node 解釋器所在位置需要在 $PATH?環(huán)境變量中所列舉的目錄中去尋找，這里可以對(duì)應(yīng)到我在?2.2.2?節(jié)中第二張圖中的 node 命令：
因此此文件就可以默認(rèn)通過 node 來執(zhí)行，并且我們也可以省略文件的后綴名（或者寫啥后綴都行），與此同時(shí)也不需要我們顯式的通過指定 node 解釋器以文件路徑作為參數(shù)的形式來執(zhí)行，也就是類似于以下方式：
node ./test.js
...
2. 目錄結(jié)構(gòu)規(guī)范
.
├── README.md
├── bin
│ └── demo-cli
├── dist
├── lib
├── node_modules // 依賴庫
├── package-lock.json // 包版本控制
└── package.json // 包配置
2.1 README.md
項(xiàng)目的介紹文件，包括指令怎么用，指令有哪些選項(xiàng)等，以及其他信息。
2.2 bin
用于存放自定義指令對(duì)應(yīng)的可執(zhí)行文件。
2.3 dist
用于打包后發(fā)包，產(chǎn)物目錄。
2.4 lib
源碼所在位置，你可以根據(jù)需求自定義相關(guān)的文件結(jié)構(gòu)，但是這里需要注意一點(diǎn)的是，如果你需要暴露 API 給外部使用，那么一定要和?package.json?中的?main?字段建立好聯(lián)系。
3. 其他配置項(xiàng)
3.1 TypeScript 支持
為了方便開發(fā)與代碼類型檢查和提示，同時(shí)更好的組織代碼，我們需要給項(xiàng)目添加 typescript 支持:
3.1.1 依賴安裝
npm install --save-dev typescript @types/node rimraf
3.1.2 配置 tsconfig.json
{
...
"compilerOptions": {
"baseUrl": ".",
"rootDir": "lib",
"lib": ["esnext"],
"module": "commonjs",
"outDir": "dist/lib",
"allowJs": true,
"strict": true,
"declaration": true,
"target": "es6",
"suppressImplicitAnyIndexErrors": true,
},
"include": ["lib"],
...
}
詳細(xì)配置：tsconfig.json。
3.1.3 配置 npm scripts
{
...
"scripts": {
"clean": "rimraf dist",
"dev": "npm run clean && tsc -w",
"prepublish": "npm run clean && tsc"// 發(fā)包構(gòu)建用
},
...
}
經(jīng)過以上配之后，我們當(dāng)前的 demo-cli 的項(xiàng)目結(jié)構(gòu)可以是：
.
├── README.md
├── bin
│ └── demo-cli
├── lib
│ ├── core
│ │ └── index.ts
│ ├── index.ts
│ ├── library.ts
│ └── utils
│ └── index.ts
├── package-lock.json
├── package.json
└── tsconfig.json
其中?library.ts?用于導(dǎo)出項(xiàng)目的對(duì)外暴露的 API，同時(shí)需要在 package.json 中配置 main 字段：
{
...
"main": "dist/lib/library.js",
...
}
這樣別人用我們的包的時(shí)候就可以使用相關(guān)的 API 了，但是我們的包定位是 cli 命令行工具，所以這一步是可選的，index.ts?是項(xiàng)目的入口文件，也是指令執(zhí)行調(diào)用的主文件。例如，我們可以在 **/bin/demo-cli** 中寫好以下代碼：
#!/usr/bin/env node
require('../dist/lib/index.js');
然后在 **/lib/index.ts** 中寫好以下代碼：
function main() {
console.log('這里是程序執(zhí)行入口函數(shù)');
}
main();
現(xiàn)在就可以通過：
node ./bin/demo-cli
命令來調(diào)試我們的代碼了！不出意外，會(huì)產(chǎn)生如下輸出：
但是這種方式每次都需要重新執(zhí)行，才能看到已修改的代碼的效果，所以我們可以在 vscode 中開啟一個(gè)新的 shell 執(zhí)行我們定義好的 npm scripts：
npm run dev
這樣我們的文件就是動(dòng)態(tài)變化的了，我們改了代碼就會(huì)產(chǎn)生相應(yīng)的 ts 編譯后的結(jié)果，那么我們要怎樣調(diào)試指令呢？通過 node ./bin/demo-cli 來調(diào)試還是不妥，這種 cli 工具我們都是要靠項(xiàng)目調(diào)試的，因此我們需要通過在本項(xiàng)目的根目錄下執(zhí)行以下指令：
npm link
這樣的話，會(huì)在全局中創(chuàng)建關(guān)于我們的 demo-cli 的自定義指令的軟鏈接，這其實(shí)相當(dāng)于是一個(gè)全局指令注冊(cè)，然后我們就可以直接在其他項(xiàng)目中使用?demo-cli?指令來運(yùn)行調(diào)試我們的腳本了，調(diào)試完之后別忘了刪除全局鏈接，只需要在項(xiàng)目的根目錄下執(zhí)行以下指令:
npm unlink
3.2 Eslint 與 Prettier
3.2.1 安裝依賴
npm i -D [email protected] @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier eslint-plugin-prettier prettier
經(jīng)驗(yàn)證，7.32.0 版本比較好用，8.0 以上移除了一些 API，產(chǎn)生 eslint 加載失敗，導(dǎo)致 VSCode 的 eslint 實(shí)時(shí)檢查不生效。
3.2.2 配置.eslintrc 與.eslintignore
.eslintrc.js：
{
"root": true,
"parser": "@typescript-eslint/parser", //定義ESLint的解析器
"plugins": [
"prettier",
"@typescript-eslint"
],//定義了該eslint文件所依賴的插件,
"extends": [
"prettier"
],
"rules": {
"no-var": "error",
"prettier/prettier": "error"
}
}
.eslintignore：
dist
node_modules3.2.3 配置.prettierrc 與.prettierignore
.prettierrc：
{
"useTabs": false,
"printWidth": 120,
"singleQuote": true,
"trailingComma": "es5",
"arrowParens": "always"
}
.prettierignore：
dist
node_modules3.3 代碼提交前檢測(cè)
3.3.1 安裝依賴
npm install -D husky lint-staged
3.3.2 配置 package.json
{
...
"lint-staged": {
"*.{js,ts}": [
"prettier-eslint --write",
"eslint --fix",
"git add"
]
},
...
}
啟動(dòng)鉤子：
npx husky install
添加鉤子 pre-commit:
npx husky add .husky/pre-commit'echo \"git commit trigger husky pre-commit hook\" && npx lint-staged'這樣在 git commit 之前就能使用 lint-staged 去檢查相應(yīng)的文件，并執(zhí)行相應(yīng)的命令來修復(fù)我們的代碼。
3.4 .gitignore
node_modules
package-lock.json
dist
3.5 .npmignore
# Dependency directories
node_modules
package-lock.json
# source code
lib
.eslintrc.js
.eslintignore
.prettierrc
.prettierignore
.gitignore
tsconfig.json
經(jīng)過以上配之后，當(dāng)前項(xiàng)目的目錄結(jié)構(gòu)為：
.
├── bin
│ └── demo-cli
├── dist
├── lib
│ ├── core
│ │ └── index.ts
│ ├── index.ts
│ ├── library.ts
│ └── utils
│ ├── index.js
│ └── index.ts
├── node_modules
├── .eslintignore
├── .eslintrc
├── .gitignore
├── .npmignore
├── .prettierignore
├── .prettierrc
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json
4. CLI 常用第三方庫
commander?—— 提供 cli 命令與參數(shù)
glob?—— 遍歷文件
shelljs?—— 常用的 shell 命令支持
prompts?—— 讀取控制臺(tái)用戶輸入
fs-extra?—— 文件讀寫等操作
inquirer?—— 類似于 prompts
chalk?—— 彩色日志
debug?—— 類似于 chalk
execa?—— 執(zhí)行 shell 指令
...
5. npm 發(fā)包
第一次發(fā)包：
npm adduser
否則：
npm login
然后：
npm publish
這里因?yàn)樵?npm scripts 里添加了相應(yīng)的 prepublish 鉤子，所以在 publish 之前會(huì)先跑構(gòu)建，從而確保我們的代碼是最新的。
6. 總結(jié)
寫個(gè) cli demo 會(huì)遇到很多問題，最痛苦的還是 eslint 的 VSCode 配置問題，要調(diào)半天，如果說沒有在 VSCode 中配置 eslint 插件或者說打開 VSCode 的控制臺(tái) output：
有報(bào)錯(cuò)的話 (以上為正常運(yùn)行)，eslint 都不會(huì)生效，具體錯(cuò)誤具體解決吧。
除此之外，理解 Linux 指令的運(yùn)行原理以及 node bin 的執(zhí)行原理對(duì)于理解 cli 命令是怎么跑的特別重要，從而還能擴(kuò)展出一些其他用法，我們的項(xiàng)目還能不只是 JS 項(xiàng)目，還可以寫 C++ 擴(kuò)展模塊。
要站在巨人的肩膀上來開發(fā)，不要重復(fù)造輪子，好的模塊應(yīng)該是經(jīng)得起考驗(yàn)的，但是要理解別人的代碼是怎么寫的，理解其中的原理，善于 “借鑒 “。
回復(fù)“加群”與大佬們一起交流學(xué)習(xí)~
點(diǎn)擊“閱讀原文”查看 130+ 篇原創(chuàng)文章