怎樣開發一個 Node-js 命令行工具包

1. 初始化項目

在一個合適的地方創建項目文件夾，爲了演示，本次的項目名爲 demo-cli，然後執行以下命令初始化項目：

npm init

執行以上命令之後，會先配置一些 package.json 的基礎信息，按提示輸入即可：

1.1 配置 package.json

爲了方便，我們把項目從 vscode 中打開，然後對 package.json 進行詳細配置，篇幅有限，這裏僅介紹其中比較重要的部分：

推薦閱讀：package.json 詳細配置。

1.1.1 name

項目名，同時也是發包的時候別人引入時的默認名稱。

1.1.2 version

版本號，對於項目的每一次升級（引入新特性、打補丁、代碼重構等），我們都需要對版本進行升級，遵循 major、minor、patch 原則。

推薦閱讀：npm 語義化版本控制。

1.1.3 main

項目入口文件的位置，方便別人引入我們的包的時候，從哪裏進行解析，這裏也是我們進行接口導出的模塊地址，稍後會進行詳細介紹。

1.1.4 scripts

腳本指令，在這裏可以自定義一些指令。

npm 腳本的原理非常簡單。每當執行 npm run，就會自動新建一個 Shell，在這個 Shell 裏面執行指定的腳本命令。因此，只要是 Shell（一般是 Bash）可以運行的命令，就可以寫在 npm 腳本里面。

比較特別的是，npm run 新建的這個 Shell，會將當前目錄的 node_modules/.bin 子目錄加入 PATH 變量，執行結束後，再將 PATH 變量恢復原樣。

推薦閱讀：npm scripts 使用指南。

1.1.5 bin

我們的項目所提供的自定義指令，以及對應的可執行文件的映射地址：

{
  ...
  "bin": {
    "demo-cli": "bin/demo-cli"
  },
  ...
}

當我們的自定義指令的名字就是項目名稱的時候，可以簡寫爲以下形式：

{
  ...
  "bin": "bin/demo-cli",
  ...
}

1.2 bin 命令是如何運行的

1.2.1 Linux bin 目錄的作用

shell 任務的一個重要部分是搜索命令。Bash 是按照下一的步驟來完成的：檢查命令是否包含斜槓。如果沒有，首先檢查函數列表是否包含一個我們尋找的命令。如果命令不是一個函數，那麼在內建命令列表中檢查。shell 內建命令是指 bash（或其它版本）工具集中的命令。一般都會有一個與之同名的系統命令，比如 bash 中的 echo 命令與 /bin/echo 是兩個不同的命令，儘管他們行爲大體相仿。當在 bash 中鍵入一個命令時系統會先看他是否是一個內建命令，如果不是纔會查看是否是系統命令或第三方工具。所以在 bash 中鍵入 echo 命令實際上執行 bash 工具集中的 bash 命令也就是內建命令，而不是 /bin/echo 這個系統命令。備註：Linux 中的 type 命令如果命令既不是函數也不是內建命令，那麼掃描列在 PATH 中的目錄列表來進行查找。

通常如果我們要在 Linux 中執行自定義腳本，那麼我們需要通過路徑的形式來執行相應的文件，如果我們在 PATH 裏的目錄中註冊了相應的指令或者通過 alias 對這個路徑起了別名的話，就不需要輸入完整路徑。

linux 或者 MacOS 中的 bin 目錄一般是用來存放可執行命令的文件夾，通常有：

• /bin

• /sbin

• /usr/bin

• /usr/local/bin

• /usr/sbin

• ...

要具體瞭解這些目錄裏有哪些指令，可以參考這篇文章：bin 目錄簡單區別

1.2.2 node bin

首先，我們需要找到我們的 node 的安裝地址，這個可以通過在 Linux、MacOS 或者 VSCode 的終端裏輸入一下指令來獲得：

echo $PATH

這會打印出當前所配置的環境變量，一般我們安裝 node 的時候會自動在 PATH 里加入，node 的可執行腳本的目錄地址：

如上圖所示，其中 “/Users/hopewlliu/.nvm/versions/node/v14.17.3/bin” 便是本電腦 node 中所有所有全局指令所在位置。

以下爲當前電腦的全局指令、軟連接的指令及其所映射的文件地址：

軟鏈的創建方式很簡單，比如我們對上圖的 imserver 添加一個新的軟鏈 imserver2，可以執行一下指令：

ln -s ../lib/node_modules/@tencent/imserver-cli/bin/imserver ./imserver2

現在我們就可以在全局上使用 imserver2 命令了，他和 imserver 的效果是一致的。

同時想要刪除軟連接也很簡單，只需要執行以下指令即可：

rm ./imserver2

1.2.3 全局安裝與非全局安裝

1.2.3.1 全局安裝

如果我們通過 -g 的形式來安裝一個包的話，他會被安裝到 node 相關文件夾中，在本文即爲：

“/Users/hopewlliu/.nvm/versions/node/v14.17.3/lib/node_modules”

目錄下，如果該包的 package.json 中存在 bin 字段的指令配置，同時會在：

“/Users/hopewlliu/.nvm/versions/node/v14.17.3/bin”

目錄下創建相應的指令軟鏈。

1.2.3.2 非全局安裝

非全局安裝的包存在於我們的項目的根目錄的 node_modules 目錄下，如果該包存在自定義指令，那麼會在安裝包的時候在當前項目的根目錄的 node_modules/.bin 目錄下添加相應的自定義指令的軟鏈接，想要執行這個包的自定義指令，我們可以直接通過路徑的形式來找到該包指令所在位置然後執行，但是通常的做法是在當前的項目的 package.json 中添加相應的 npm scripts 來執行，原理就是 npm scrpits 在執行的前一刻會開啓新的 shell 並把當前項目的根目錄的 node_modules/.bin 目錄加入 PATH 環境變量中，然後在這個 shell 中執行自定義的腳本指令，並在執行完成之後將 PATH 恢復原樣。

1.2.4 目標文件的執行原理

解釋完指令的尋找與執行後，我們需要探討一下相應的腳本是如何被執行的，通常我們寫的自定義腳本文件的入口文件的上方都需要寫上一行代碼：

#!/usr/bin/env node

#! 是一個約定的標記，它告訴系統這個腳本需要什麼解釋器來執行，即使用哪一種 Shell，比如我們在寫自定義 shell 腳本的時候可以在腳本的第一行指定當前腳本所使用的解釋器：

• #!/bin/bash

• #!/bin/zsh

• ...

這樣寫的目的是爲了使該文件以可執行程序去運行的時候可以找到相應的解釋器，當然如果將文件所在位置作爲參數傳遞給解釋器來執行的話，則不需要在自定義腳本的第一行添加上述代碼（寫了也沒用），例如：

• /bin/bash ./test.sh

• ...

說了這麼多，那麼我們的 “#!/usr/bin/env node“又有什麼不同呢？

#!/usr/bin/env <executableName> 是一種_可移植_指定解釋器的方式：簡而言之，它表示：執行 <executableName>，無論你（第一次）在 $PATH 變量中列出的目錄中找到它（並隱式傳遞給文件的路徑）在眼前）。

說白了就是告訴系統，當前的腳本需要通過 node 來執行，node 解釋器所在位置需要在 **$PATH ** 環境變量中所列舉的目錄中去尋找，這裏可以對應到我在 2.2.2 節 中第二張圖中的 node 命令：

因此此文件就可以默認通過 node 來執行，並且我們也可以省略文件的後綴名（或者寫啥後綴都行），與此同時也不需要我們顯式的通過指定 node 解釋器以文件路徑作爲參數的形式來執行，也就是類似於以下方式：

• node ./test.js

• ...

2. 目錄結構規範

.
├── README.md
├── bin
│   └── demo-cli
├── dist
├── lib
├── node_modules // 依賴庫
├── package-lock.json // 包版本控制
└── package.json // 包配置

2.1 README.md

項目的介紹文件，包括指令怎麼用，指令有哪些選項等，以及其他信息。

2.2 bin

用於存放自定義指令對應的可執行文件。

2.3 dist

用於打包後發包，產物目錄。

2.4 lib

源碼所在位置，你可以根據需求自定義相關的文件結構，但是這裏需要注意一點的是，如果你需要暴露 API 給外部使用，那麼一定要和 package.json 中的 main 字段建立好聯繫。

3. 其他配置項

3.1 TypeScript 支持

爲了方便開發與代碼類型檢查和提示，同時更好的組織代碼，我們需要給項目添加 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"],
  ...
}

詳細配置：tsconfig.json。

3.1.3 配置 npm scripts

{
    ...
  "scripts": {
    "clean": "rimraf dist",
    "dev": "npm run clean && tsc -w",
    "prepublish": "npm run clean && tsc"// 發包構建用
  },
  ...
}

經過以上配之後，我們當前的 demo-cli 的項目結構可以是：

.
├── 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 用於導出項目的對外暴露的 API，同時需要在 package.json 中配置 main 字段：

{
  ...
  "main": "dist/lib/library.js",
  ...
}

這樣別人用我們的包的時候就可以使用相關的 API 了，但是我們的包定位是 cli 命令行工具，所以這一步是可選的，index.ts 是項目的入口文件，也是指令執行調用的主文件。例如，我們可以在 /bin/demo-cli 中寫好以下代碼：

#!/usr/bin/env node

require('../dist/lib/index.js');

然後在 /lib/index.ts 中寫好以下代碼：

function main() {
  console.log('這裏是程序執行入口函數');
}
 
main();

現在就可以通過：

node ./bin/demo-cli

命令來調試我們的代碼了！不出意外，會產生如下輸出：

但是這種方式每次都需要重新執行，才能看到已修改的代碼的效果，所以我們可以在 vscode 中開啓一個新的 shell 執行我們定義好的 npm scripts：

npm run dev

這樣我們的文件就是動態變化的了，我們改了代碼就會產生相應的 ts 編譯後的結果，那麼我們要怎樣調試指令呢？通過 node ./bin/demo-cli 來調試還是不妥，這種 cli 工具我們都是要靠項目調試的，因此我們需要通過在本項目的根目錄下執行以下指令：

npm link

這樣的話，會在全局中創建關於我們的 demo-cli 的自定義指令的軟鏈接，這其實相當於是一個全局指令註冊，然後我們就可以直接在其他項目中使用 demo-cli 指令來運行調試我們的腳本了，調試完之後別忘了刪除全局鏈接，只需要在項目的根目錄下執行以下指令:

npm unlink

3.2 Eslint 與 Prettier

3.2.1 安裝依賴

npm i -D eslint@7.32.0 @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier eslint-plugin-prettier prettier

經驗證，7.32.0 版本比較好用，8.0 以上移除了一些 API，產生 eslint 加載失敗，導致 VSCode 的 eslint 實時檢查不生效。

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_modules

3.2.3 配置. prettierrc 與. prettierignore

.prettierrc：

{
  "useTabs": false,
  "printWidth": 120,
  "singleQuote": true,
  "trailingComma": "es5",
  "arrowParens": "always"
}

.prettierignore：

dist
node_modules

3.3 代碼提交前檢測

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"
    ]
  },
  ...
}

啓動鉤子：

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 去檢查相應的文件，並執行相應的命令來修復我們的代碼。

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

經過以上配之後，當前項目的目錄結構爲：

.
├── 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 命令與參數

• glob —— 遍歷文件

• shelljs —— 常用的 shell 命令支持

• prompts —— 讀取控制檯用戶輸入

• fs-extra —— 文件讀寫等操作

• inquirer —— 類似於 prompts

• chalk —— 彩色日誌

• debug —— 類似於 chalk

• execa —— 執行 shell 指令

• ...

5. npm 發包

第一次發包：

npm adduser

否則：

npm login

然後：

npm publish

這裏因爲在 npm scripts 裏添加了相應的 prepublish 鉤子，所以在 publish 之前會先跑構建，從而確保我們的代碼是最新的。

6. 總結

寫個 cli demo 會遇到很多問題，最痛苦的還是 eslint 的 VSCode 配置問題，要調半天，如果說沒有在 VSCode 中配置 eslint 插件或者說打開 VSCode 的控制檯 output：

有報錯的話 (以上爲正常運行)，eslint 都不會生效，具體錯誤具體解決吧。

除此之外，理解 Linux 指令的運行原理以及 node bin 的執行原理對於理解 cli 命令是怎麼跑的特別重要，從而還能擴展出一些其他用法，我們的項目還能不只是 JS 項目，還可以寫 C++ 擴展模塊。

要站在巨人的肩膀上來開發，不要重複造輪子，好的模塊應該是經得起考驗的，但是要理解別人的代碼是怎麼寫的，理解其中的原理，善於 “借鑑 “。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/xoYQeUhNSxXhAc3_l9xRJA