本文將提供較為全面的Node CLI Demo項(xiàng)目的構(gòu)建流程呻右，其中有誤的部分煩請指出

怎樣開發(fā)一個(gè)Node命令行工具包

• 1. 初始化項(xiàng)目
  • 1.1 配置package.json
    • 1.1.1 name
    • 1.1.2 version
    • 1.1.3 main
    • 1.1.4 scripts
    • 1.1.5 bin
  • 1.2 bin命令是如何運(yùn)行的
    • 1.2.1 Linux bin目錄的作用
    • 1.2.2 node bin
    • 1.2.3 全局安裝與非全局安裝
      • 1.2.3.1 全局安裝
      • 1.2.3.2 非全局安裝
    • 1.2.4 目標(biāo)文件的執(zhí)行原理
• 2. 目錄結(jié)構(gòu)規(guī)范
  • 2.1 README.md
  • 2.2 bin
  • 2.3 dist
  • 2.4 lib
• 3. 其他配置項(xiàng)
  • 3.1 TypeScript支持
    • 3.1.1 依賴安裝
    • 3.1.2 配置tsconfig.json
    • 3.1.3 配置npm scripts
  • 3.2 Eslint與Prettier
    • 3.2.1 安裝依賴
    • 3.2.2 配置.eslintrc與.eslintignore
    • 3.2.2 配置.prettierrc與.prettierignore
  • 3.3 代碼提交前檢測
    • 3.3.1 安裝依賴
    • 3.3.2 配置package.json
  • 3.4 .gitignore
  • 3.5 .npmignore
• 4. CLI常用第三方庫
• 5. npm發(fā)包
• 6. 總結(jié)

1. 初始化項(xiàng)目

在一個(gè)合適的地方創(chuàng)建項(xiàng)目文件夾

為了演示触机，本次的項(xiàng)目名為demo-cli

然后執(zhí)行以下命令初始化項(xiàng)目：

npm init

執(zhí)行以上命令之后沟娱，會(huì)先配置一些package.json的基礎(chǔ)信息纸肉，按提示輸入即可

項(xiàng)目初始化

1.1 配置package.json

為了方便呼胚，我們把項(xiàng)目從vscode中打開蔗彤，然后對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)堂淡，對于項(xiàng)目的每一次升級（引入新特性、打補(bǔ)丁扒腕、代碼重構(gòu)等）绢淀，我們都需要對版本進(jìn)行升級，遵循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 腳本的原理非常簡單楞抡。每當(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)目所提供的自定義指令寺谤，以及對應(yīng)的可執(zhí)行文件的映射地址

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

當(dāng)我們的自定義指令的名字就是項(xiàng)目名稱的時(shí)候仑鸥，可以簡寫為以下形式：

{
  "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)的文件其兴，如果我們在PATH里的目錄中注冊了相應(yīng)的指令或者通過alias對這個(gè)路徑起了別名的話，就不需要輸入完整路徑

linux或者M(jìn)acOS中的bin目錄一般是用來存放可執(zhí)行命令的文件夾夸政，通常有：

• /bin
• /sbin
• /usr/bin
• /usr/local/bin
• /usr/sbin
• ...

要具體了解這些目錄里有哪些指令忌警，可以參考這篇文章：bin目錄簡單區(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í)行腳本的目錄地址：

echo $PATH

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

以下為當(dāng)前電腦的全局指令盐茎、軟連接的指令及其所映射的文件地址

指令列表

軟鏈接的創(chuàng)建方式很簡單兴垦，比如我們對上圖的nest添加一個(gè)新的軟鏈nest2，可以執(zhí)行一下指令：

ln -s ../lib/node_modules/@nestjs/cli/bin/nest.js ./nest2

現(xiàn)在我們就可以在全局上使用nest2命令了，他和nest的效果是一致的

同時(shí)想要?jiǎng)h除軟連接也很簡單探越，只需要執(zhí)行以下指令即可：

rm ./nest2

1.2.3 全局安裝與非全局安裝

1.2.3.1 全局安裝

如果我們通過 -g 的形式來安裝一個(gè)包的話狡赐，他會(huì)被安裝到node相關(guān)文件夾中，在本文即為：
'/Users/***/.nvm/versions/node/v14.17.3/lib/node_modules'
目錄下钦幔，如果該包的package.json中存在bin字段的指令配置枕屉，同時(shí)會(huì)在：
'/Users/***/.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，

比如我們在寫自定義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 <executableName>是一種可移植指定解釋器的方式：簡而言之，它表示：執(zhí)行<executableName>食茎，無論你（第一次）在$PATH變量中列出的目錄中找到它（并隱式傳遞給文件的路徑）在眼前）蒂破。

說白了就是告訴系統(tǒng)，當(dāng)前的腳本需要通過node來執(zhí)行别渔，node解釋器所在位置需要在$PATH環(huán)境變量中所列舉的目錄中去尋找附迷，這里可以對應(yīng)到我在1.2.2 node bin節(jié)中第二張圖中的node命令：

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

用于存放自定義指令對應(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)目的對外暴露的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í)行結(jié)果

但是這種方式每次都需要重新執(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è)全局指令注冊候齿，

然后我們就可以直接在其他項(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 eslint@7.32.0 @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

{
  "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.2 配置.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": {
    "lib/**/*.{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
.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.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)樵趎pm scripts里添加了相應(yīng)的prepublish鉤子灭必，所以在publish之前會(huì)先跑構(gòu)建狞谱，從而確保我們的代碼是最新的

6. 總結(jié)

寫個(gè)cli demo會(huì)遇到很多問題，最惡心的還是eslint的VSCode配置問題禁漓，要調(diào)半天跟衅，如果說沒有在VSCode中配置eslint插件或者說打開VSCode的控制臺(tái)output：

VSCode 控制臺(tái) OUTPUT

有報(bào)錯(cuò)的話(以上為正常運(yùn)行)，eslint都不會(huì)生效播歼，具體錯(cuò)誤具體解決吧

除此之外伶跷，理解Linux指令的運(yùn)行原理以及node bin的執(zhí)行原理對于理解cli命令是怎么跑的特別重要，從而還能擴(kuò)展出一些其他用法秘狞，我們的項(xiàng)目還能不只是JS項(xiàng)目叭莫，還可以寫C++擴(kuò)展模塊

要站在巨人的肩膀上來開發(fā)，不要重復(fù)造輪子烁试，好的模塊經(jīng)得起考驗(yàn)雇初，但是要理解別人的代碼是怎么寫的，理解其中的原理廓潜，善于"借鑒"