大家好，我是若川。最近組織了源碼共讀活動，感興趣的可以點此加我微信 ruochuan12?參與，每周大家一起學習200行左右的源碼，共同進步。同時極力推薦訂閱我寫的《學習源碼整體架構系列》?包含20余篇源碼文章。

源碼共讀活動很多都是讀的npm包，這篇文章很詳細，推薦給大家。

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 noderequire('../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++ 擴展模塊。

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

·················?若川簡介?·················

你好，我是若川，畢業于江西高校。現在是一名前端開發“工程師”。寫有《學習源碼整體架構系列》20余篇，在知乎、掘金收獲超百萬閱讀。
從2014年起，每年都會寫一篇年度總結，已經寫了7篇，點擊查看年度總結。
同時，最近組織了源碼共讀活動，幫助3000+前端人學會看源碼。公眾號愿景：幫助5年內前端人走向前列。