本文將提供較為全面的Node CLI Demo項目的構建流程，其中有誤的部分煩請指出
怎樣開發一個Node命令行工具包
1. 初始化項目
在一個合適的地方創建項目文件夾
為了演示，本次的項目名為demo-cli
然后執行以下命令初始化項目：
npm init
執行以上命令之后，會先配置一些package.json的基礎信息，按提示輸入即可
1.1 配置package.json
為了方便，我們把項目從vscode中打開，然后對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/***/.nvm/versions/node/v14.17.3/bin"便是本電腦node中所有所有全局指令所在位置
以下為當前電腦的全局指令、軟連接的指令及其所映射的文件地址
軟鏈接的創建方式很簡單，比如我們對上圖的nest添加一個新的軟鏈nest2，可以執行一下指令：
ln -s ../lib/node_modules/@nestjs/cli/bin/nest.js ./nest2
現在我們就可以在全局上使用nest2命令了，他和nest的效果是一致的
同時想要刪除軟連接也很簡單，只需要執行以下指令即可：
rm ./nest2
1.2.3 全局安裝與非全局安裝
1.2.3.1 全局安裝
如果我們通過 -g 的形式來安裝一個包的話，他會被安裝到node相關文件夾中，在本文即為：
'/Users/***/.nvm/versions/node/v14.17.3/lib/node_modules'
目錄下，如果該包的package.json中存在bin字段的指令配置，同時會在：
'/Users/***/.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環境變量中所列舉的目錄中去尋找，這里可以對應到我在1.2.2 node bin節中第二張圖中的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
{
"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"
]
},
}
啟動鉤子:
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
.eslintignore
.prettierrc
.prettierignore
.gitignore
tsconfig.json
經過以上配之后，當前項目的目錄結構為：
.
├── 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命令與參數
- 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++擴展模塊
要站在巨人的肩膀上來開發，不要重復造輪子，好的模塊經得起考驗，但是要理解別人的代碼是怎么寫的，理解其中的原理，善于"借鑒"
