想想項(xiàng)目創(chuàng)建之后，多久沒(méi)給 npm 依賴升級(jí)了？

如何得知當(dāng)前項(xiàng)目 npm 依賴的“健康度”？

給老項(xiàng)目升級(jí) npm 依賴，有哪些注意事項(xiàng)？

核心訴求

• 提高可維護(hù)性。不容易和后引入的依賴產(chǎn)生沖突。引入新特性，功能表現(xiàn)和文檔描述接近，后續(xù)開(kāi)發(fā)也能得心應(yīng)手。
• 提高可移植性。方便老項(xiàng)目向高版本 npm 或 pnpm 遷移。
  
• 提高可靠性。只要依賴還在穩(wěn)定迭代，升級(jí)必定能引入一系列 bugfix（卻也可能引入新 bug）。
  
• 提高安全性。官方社區(qū)會(huì)及時(shí)通告 npm 依賴的安全漏洞，將版本保持在安全范圍，能排除許多隱患。
  

流程方法

• 使用專業(yè)的評(píng)估工具。手動(dòng)升級(jí) @latest 等于把依賴當(dāng)成黑盒來(lái)操作。
• 按優(yōu)先級(jí)處理。集中精力升級(jí)核心依賴，以及含有安全隱患的庫(kù)，否則時(shí)間投入很容易超出預(yù)期。
  
• 閱讀 changelog，評(píng)估升級(jí)影響。
  
• 回歸測(cè)試，十分重要。
  

除了回歸測(cè)試以外，主導(dǎo)治理的人不僅要熟悉項(xiàng)目?jī)?nèi)容，也要對(duì)計(jì)劃升級(jí)的 npm 包有充分了解。如果沒(méi)有合適的人選，建議繼續(xù)在代碼堆里堅(jiān)持一會(huì)兒，畢竟升級(jí)有風(fēng)險(xiǎn)，后果得自負(fù)。

檢索工具

以下內(nèi)容以 npm 為例，pnpm 和 yarn 有可替代的命令。

過(guò)時(shí)依賴 npm outdated

npm outdated 命令會(huì)從 npm 源檢查已安裝的軟件包是否已過(guò)時(shí)。

隨便拿幾個(gè)包舉例：

Package                             Current   Wanted        Latest  Location
axios                                0.18.1   0.18.1        0.27.2  project-dir
log4js                               2.11.0   2.11.0         6.5.2  project-dir
lru-cache                             4.1.5    4.1.5        7.10.2  project-dir
socket.io                             2.4.1    2.5.0         4.5.1  project-dir
vue                                  2.6.14   2.6.14        3.2.37  project-dir
vue-lazyload                          1.3.3    1.3.4    3.0.0-rc.2  project-dir
vue-loader                           14.2.4   14.2.4        17.0.0  project-dir
vue-router                            3.5.3    3.5.4        4.0.16  project-dir
vuex                                  3.6.2    3.6.2         4.0.2  project-dir
webpack                              3.12.0   3.12.0        5.73.0  project-dir

默認(rèn)只會(huì)檢查項(xiàng)目 package.json 中直接引用的依賴， --all 選項(xiàng)可以用來(lái)匹配全部的依賴。但沒(méi)有必要，真要徹底升級(jí)，更推薦嘗試重建 lock 文件。

對(duì)于 outdated 的包，使用 npm update 或其他包管理工具對(duì)應(yīng)的 update 命令即可安裝 SemVer 標(biāo)準(zhǔn)執(zhí)行升級(jí)。如果想跨越 Major 版本，則需要手動(dòng)指定升級(jí)版本。

風(fēng)險(xiǎn)依賴 npm audit

npm audit 命令同樣是向 npm 源發(fā)起請(qǐng)求，它將 package-lock.json 作為參數(shù)，返回存在已知漏洞的依賴列表。換句話說(shuō)，audit 不需要安裝 node_modules 就可以執(zhí)行，其結(jié)果完全取決于當(dāng)前的 package-lock.json。

返回節(jié)選如下：

# Run  npm install swiper@8.2.5  to resolve 1 vulnerability
SEMVER WARNING: Recommended action is a potentially breaking change
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Critical      │ Prototype Pollution in swiper                                │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ swiper                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ swiper                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ swiper                                                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://github.com/advisories/GHSA-p3hc-fv2j-rp68            │
└───────────────┴──────────────────────────────────────────────────────────────┘
found 125 vulnerabilities (8 low, 66 moderate, 41 high, 10 critical) in 2502 scanned packages
  run `npm audit fix` to fix 15 of them.
  96 vulnerabilities require semver-major dependency updates.
  14 vulnerabilities require manual review. See the full report for details.

如果你發(fā)現(xiàn)執(zhí)行結(jié)果為 404，說(shuō)明當(dāng)前源不支持 audit 接口，可更換到支持 audit 的官方源重新執(zhí)行。

npm http fetch POST 404 https://registry.npmmirror.com/-/npm/v1/security/audits 306ms
npm ERR! code ENOAUDIT
npm ERR! audit Your configured registry (https://registry.npmmirror.com/) does not support audit requests.
npm ERR! audit The server said: <h1>404 Not Found</h1>

結(jié)果中雖然提到了 npm audit fix 命令，卻不總是可靠的，它能修復(fù)的依賴有限，遠(yuǎn)不如通過(guò)升級(jí) root 依賴修復(fù)間接依賴帶來(lái)的數(shù)量明顯。

隱式依賴 npx depcheck

npm cli 工具 depcheck 能輔助我們找到項(xiàng)目中 Unused dependencies（無(wú)用依賴）和 Phantom dependencies（幻影依賴），分別表示寫入 package.json 但沒(méi)被項(xiàng)目使用、被項(xiàng)目引用了但沒(méi)有寫入 package.json。

depcheck 更像是一個(gè)縮小排查范圍的過(guò)濾器，不能輕信其打印結(jié)果。例如，depcheck 默認(rèn)無(wú)法識(shí)別特殊掛載的 plugin。

Unused dependencies
 * clipboard
 * cross-env
 * firebase
 * proxy
 * route-cache
 * socket.io
Unused devDependencies
 * add-asset-html-webpack-plugin
 * commitizen
 * eslint
 * husky
 * jasmine
 * rimraf
 * stylelint
Missing dependencies
 * node-notifier: ./build/utils.js

要?jiǎng)h除一個(gè)無(wú)用依賴，必須熟悉該 npm 包的使用性質(zhì)，再結(jié)合 grep 工具反復(fù)確認(rèn)。

僵尸依賴 npm install

最后，還要提防一種 Zombie dependencies（僵尸依賴）。不同于前面介紹的隱式依賴，它的危害很大。

首先它切實(shí)被項(xiàng)目使用，但已經(jīng)被維護(hù)者 deprecated 或 archieved。意味著版本不再更新，包名不會(huì)出現(xiàn)在 outdated 列表；很可能沒(méi)人報(bào)告漏洞，也不會(huì)出現(xiàn)在 audit 列表。但潛在的 bug 無(wú)人修復(fù)，它將一直躲藏在項(xiàng)目里，伺機(jī)而動(dòng)。

筆者沒(méi)發(fā)現(xiàn)合適的工具去尋找僵尸依賴，只好多留意 npm install 的 deprecated 日志。

治理建議

如何閱讀 CHANGELOG

changelog 一般位于代碼倉(cāng)庫(kù)的 CHANGELOG.md 或 History.md，隨意一些的也可能放在在 Github 的 releases 頁(yè)，正式一些的會(huì)放在官方網(wǎng)站的 Migrations 類目。

如果發(fā)現(xiàn)一個(gè) npm 包沒(méi)有 changelog，或 changelog 寫得太差，建議換成其他更靠譜的替代品 ，就只能靠閱讀 commits 了。

關(guān)鍵詞（歡迎補(bǔ)充）：

• BREAKING CHANGE
• !
  
• Node.js
  

開(kāi)發(fā)者普遍會(huì)用上面的方式標(biāo)注不兼容的變更。

lock 文件版本管理

該建議是對(duì)商業(yè)軟件的研發(fā)流程而言?；钴S的開(kāi)源場(chǎng)景并不需要 lock 文件，為了開(kāi)發(fā)者迭代和測(cè)試的過(guò)程能趁早發(fā)現(xiàn)兼容性問(wèn)題。

package-lock.json 的設(shè)計(jì)文稿就直言推薦把 lock 文件加入代碼倉(cāng)庫(kù)：

• 保證團(tuán)隊(duì)成員和 CI 能使用完全相同的依賴關(guān)系。
• 作為 node_modules 的輕量化備份。
  
• 讓依賴樹的變化更具可見(jiàn)性。
  
• 加速安裝過(guò)程。
  

但是，npm 依賴管理的策略因團(tuán)隊(duì)和項(xiàng)目而異，是否提交 lock 文件到 git 倉(cāng)庫(kù)可以按需取舍，版本管理的形式還有很多。

例如研發(fā)流程完善，每次發(fā)布的 lock 文件都會(huì)留在制品庫(kù)或鏡像中，能夠隨時(shí)被還原?？扇绻鄙傧嚓P(guān)舉措，就要想辦法將生產(chǎn)環(huán)境的 lock 文件備份，為問(wèn)題復(fù)現(xiàn)、故障恢復(fù)提供依據(jù)。

更新 hoisting

常年累月的更新之下，許多 package-lock.json 的外層依賴的版本會(huì)落后于子節(jié)點(diǎn)，因?yàn)槟壳?npm 為了保持最小更新幅度，不會(huì)對(duì) lock 樹做旋轉(zhuǎn)和變形。即使更新的項(xiàng)目的直接依賴到 latest，它的間接依賴可能還是舊的，以致現(xiàn)存的依賴提升結(jié)果和默認(rèn) hoisting 算法的偏差越來(lái)越大。

一些老項(xiàng)目脫離 package-lock.json 文件之后，甚至無(wú)法正常安裝構(gòu)建。此時(shí)依賴已經(jīng)處于非常不健康的狀態(tài)，開(kāi)發(fā)者需要擔(dān)心新引入的依賴是否會(huì)破壞平衡，無(wú)法遷移 npm 包管理工具，也不能升級(jí) Node.js 版本。不過(guò)亡羊補(bǔ)牢并不復(fù)雜，總好過(guò)修復(fù)一個(gè)沒(méi)有 package-lock.json 的項(xiàng)目。

想生成一份可靠的 package-lock.json，最簡(jiǎn)單的辦法就是除舊迎新：

rm -rf package-lock.json node_modules
npm i

更好的辦法是換到不使用 hoisting 的依賴管理工具。

情況講清楚了，什么時(shí)候重建可以看自身需求。但是，將 lock 文件加入 .gitignore 的同學(xué)就要注意了，如果別人出現(xiàn)了你本地?zé)o法復(fù)現(xiàn)的問(wèn)題，記得先刪掉 package-lock.json。

整理 dependencies 和 devDependencies

package.json 中 dependencies 和 devDependencies 的區(qū)別就不必介紹了，但大家在項(xiàng)目中是否會(huì)做嚴(yán)格區(qū)分呢？

一來(lái) devDependencies 是為 npm 包優(yōu)化依賴關(guān)系設(shè)計(jì)的，作為應(yīng)用的項(xiàng)目通常不會(huì)打包發(fā)布到 npm 上；二來(lái)不作區(qū)分也沒(méi)有直接帶來(lái)不良后果。因此經(jīng)常會(huì)有小伙伴將開(kāi)發(fā)環(huán)境依賴的工具直接安裝到 dependencies 中。

不過(guò)，即使對(duì)項(xiàng)目而言，devDependencies 也有積極意義：

• 能從語(yǔ)義上劃分依賴的用途。
• 使用 npm install --production 可以忽略 devDependencies，提高安裝效率，顯著減少 node_modules 的體積。
  

第二點(diǎn)還需要做個(gè)補(bǔ)充說(shuō)明，由于靜態(tài)項(xiàng)目的構(gòu)建環(huán)境往往需要安裝大部分 devDependencies 中的依賴，一般只有放在服務(wù)端運(yùn)行的 Node.js 項(xiàng)目才需要考慮這么做。但隨著 TypeScript 的普及或是 SSR 的引入，這些服務(wù)端項(xiàng)目在運(yùn)行前也需要執(zhí)行構(gòu)建。那還有什么用？別忘了，還有一個(gè) npm prune --production 能用作后置的項(xiàng)目體積優(yōu)化。

當(dāng)然了，語(yǔ)義劃分帶來(lái)幫助也足夠大了，例如根據(jù)依賴關(guān)系來(lái)優(yōu)化 npm 治理的優(yōu)先級(jí)和策略。

順便再提一句，dependencies 和 devDependencies 不是用來(lái)區(qū)分重要程度，請(qǐng)不要把運(yùn)行可有可無(wú)的依賴放在 devDependencies，應(yīng)該放在optionalDependencies (https://docs.npmjs.com/cli/v6/configuring-npm/package-json#optionaldependencies) 中。

結(jié)語(yǔ)

以上介紹的經(jīng)驗(yàn)多為概述，主要結(jié)合 npm 依賴管理工具的特點(diǎn)，沒(méi)能介紹 yarn 和 pnpm 等工具獨(dú)有的 API 和問(wèn)題，如果讀者想了解更多內(nèi)容，請(qǐng)查閱相關(guān)文檔。此外，同時(shí)使用多種依賴管理工具的項(xiàng)目頗為復(fù)雜，比較少見(jiàn)，本文未作分析，也不建議讀者朋友們嘗試。而在軟件工程領(lǐng)域，依賴治理還有很多要點(diǎn)需要我們?nèi)ミM(jìn)一步實(shí)踐，不過(guò)內(nèi)容更側(cè)重于 refactor。

回到標(biāo)語(yǔ)所提項(xiàng)目依賴的“健康度”，實(shí)為筆者胡謅，用來(lái)形容依賴關(guān)系的混亂程度。不做這些依賴治理，也沒(méi)有太大關(guān)系，因?yàn)檐浖纳芷谕鶊?jiān)持不到依賴關(guān)系崩壞的那天。但混亂的依賴管理，卻能輕易促成代碼的腐化。