npm 教學指南指令與版本管理 定義 package.json 規範與語意化版本 SemVer 實務

如何掌握 npm 套件管理與多版本切換？

npm 教學 的核心在於建立「可預測開發環境」。 Node.js 套件管理 流程包含：1. 核心配置：透過 package.json 管理依賴，並利用 package-lock.json 確保團隊成員與 CI/CD 環境的版號一致性；2. 精確指令：掌握 npm install --production 縮減部署體積，並在 CI 環境改用 npm ci 實作 Clean Install；3. 版本規範：深入理解 語意化版本 (SemVer)，利用 ^ 或 ~ 符號在相容性與功能更新間取得平衡；4. 環境管理：透過 nvm 教學 實踐多版本 Node.js 切換，搭配 .nvmrc 實現專案級的自動化版本鎖定。這套實務能顯著提升開發效率，是現代前端工程師的必備技能。

npm 介紹：Node.js 預設的套件管理平台

什麼是 npm? npm 是 Node Package Manager 的縮寫，是 Node.js 預設的 node 套件管理平台。本篇 npm 教學 將帶您深入了解這款開發者必備的工具。npm 本機端的相關工具在安裝 node.js 時也會一起安裝，另一套 Package Manager 本機端工具則是 Facebook 推出的 Yarn。

套件做到的事就是別人已經研究過的東西我們可以不需要再研究一次，就像增加魅力的日常穿搭或是實用小物來說，我們其實就可以透過閱讀一些日雜來學習和應用。

小編甚至發現一些日雜還會附贈一些 C/P 值高也實用好看的小物，透過別人整理好的套件，雖然沒辦法個人和客製化，但也能夠在各方面快速達到一個水平，這就是套件的好處。

套件管理工具就像是那些雜誌或是懶人包的型錄，能快速幫我們在方方面面進入狀況，要把到妹跟專案能不能上線似乎有點類似，最重要的就是快速在各方面都能達到某些限制條件的水平。

當撰寫網頁應用程式時，會使用到其他撰寫好的套件或模組。在未使用任何 build tool 時，通常：

1. 透過 CDN 將樣式或是腳本放在 HTML 中。
2. 寫在 JavaScript 中動態加入 <script src=""> 的 tag。

當套件或模組越來越多時，版本或相容管理複雜度就會增加，此時透過 Package Manager 指令能更方便進行套件的管理動作 (安裝、升級或刪除)，接下來這篇文章將提到：

• package.json 是什麼。
• npm install 安裝 node_module 的語法。
• node_module 版本號碼 (SemVer)。
• npm 維護 node_module 的語法。
• 用 nvm 管理 node.js 版本。

Package.json：專案的核心配置檔案

npm 是一個 package manager。當專案什麼都沒有的時候，在安裝 Node.js 後會需要在專案根目錄輸入 npm init 來把專案初始化。

填入相關資訊後，未來所有關於套件的相關配置都會存在 package.json 中。安裝第一個套件後，同時也會多出一個 package-lock.json 檔來保存安裝的紀錄。

• dependencies: 執行環境會需要
• devDependencies: 開發或測試環境需要
• optionalDependencies: 不一定在每個環境都能夠裝起來

package-lock.json：確保套件版本的一致性

package-lock.json 會在更動 node_modules 或 package.json 的時候自動產生相關紀錄，它會非常詳細記錄相關套件的精確版本號，確保團隊成員與 CI/CD 環境中的套件一致性。

目前總共有 v1 v2 v3 三個版本，v3 版後 lockfile 會藏在 node_modules/.package-lock.json

v1: 相容 npm v5 v6
v2: 相容 npm v7+ 且會向下相容 v1.
v3: 相容 npm v7+ 無法向下相容，因為會藏起來在 node_modules/.package-lock.json

npm 指令實戰：安裝與管理 node_modules

用最常用的 lodash 舉例，列出幾種 npm 指令 與結果說明：

透過以下指令可以針對 package.json 做安裝 ，熟悉這些指令在未來我們需要控制 Docker Image 的大小、縮短 CI/CD 的時間上會有很大的幫助。

npm install 失敗

• 更新 lockfile npm i --package-lock-only
• npm install -g npm@X.X.X 退版到適合版本
• 當 Nodejs 從 v14 升級到 v16 以上 lock 檔版本衝突，可選擇 npm 降版或 npm i --force
• 相依性出現問題，可使用 npm install --legacy-peer-deps

npm 套件版本衝突

可以執行 npm ls + 套件名稱，舉例來說最常遇到的會是 eslint 的問題，就可以輸入 npm ls eslint，來看是在什麼地方出現衝突。

npm ci

npm ci 的 ci 是 Clean install 的意思，因為 npm install 有時候會因為套件的升級等等導致安裝失敗，npm ci 會針對 package-lock.json 來還原套件，較適合是用在 CI 環境。

語意化版本 (SemVer)：理解套件版本遞增規則

node_module 版號 通常會有三位數字 1.2.3 對應到 主版號.次版號.修訂號。這種規範被稱為 語意化版本 (Semantic Versioning)，其遞增規則如下：

• 主版號：當你做了不相容的 API 修改
• 次版號：當你做了向下相容的功能性新增
• 修訂號：當你做了向下相容的問題修正
• 先行版號及版本編譯資訊: 加到「主版號.次版號.修訂號」的後面，作為延伸

安裝特定版號的方法，可以去 npm 官方提供的計算機試用看看

• 主版號: * or x
• 次版號: 1 or 1.x or ^1.0.4
• 修訂號: 1.0 or 1.0.x or ~1.0.4
• 先行版號: 1.0.0-beta7

npm 套件維護與資安審核

除了安裝，npm 也提供了一系列維護指令，幫助我們管理專案健康度。

nvm 教學：靈活切換與管理多版本 Node.js

nvm (Node Version Manager) 是一套管理 node.js 版本的工具，尤其在同時須開發不同版本 node.js 專案時很好用。這份 nvm 教學 將幫助您輕鬆掌控開發環境。

舉例來說用了這套工具升級就只要兩步驟很簡單

1. nvm install --lts
2. nvm use --lts。

注意事項:

• nvm-windows
  • 解除安裝已安裝的 node
  • 清空相關資料夾 C:\Program Files\nodejs
  • 解除安裝已安裝的 npm
  • 清空相關資料夾 C:\Users\<user>\AppData\Roaming\npm
• mac
  • 不要用 brew 安裝

.nvmrc

如果專案大多使用不同 Node 版本，也可以在專案中加入 .nvmrc 方便使用。

在專案中新增一個 .nvmrc 然後填入版本即可執行 nvm use。

1

12.16.1

.node-version

.node-version 是一個能被多種工具讀取的配置檔，開發者也透過其他跨平台管理工具來管理 Node 的版本。

• fnm: https://github.com/Schniz/fnm
• nvs: https://github.com/jasongin/nvs
• nodenv: https://github.com/nodenv/nodenv

線上發佈服務

• Cloudflare Pages: https://developers.cloudflare.com/pages/platform/build-configuration#language-support-and-tools
• netlify: https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript

FAQ：npm 與 Node.js 套件管理常見問題

Q1：npm install 與 npm ci 有什麼本質上的區別？

A：npm install 可能會根據 package.json 中的版號規範（如 ^）嘗試安裝較新的套件並更新 package-lock.json；而 npm ci 則嚴格依照 package-lock.json 的版本進行安裝，且會先刪除現有的 node_modules。在 CI/CD 流程中，npm ci 是確保構建一致性的標準做法。

Q2：package.json 中的 ^ (caret) 與 ~ (tilde) 符號有什麼差別？

A：這是 語意化版本 (SemVer) 管理中的細節：^1.2.3 代表允許更新到不改變主版號的最新版本（最高到 1.x.x）；而 ~1.2.3 則僅允許更新到不改變次版號的最新修訂版本（最高到 1.2.x）。如果您追求穩定性，使用 ~ 或鎖定精確版號能減少非預期 API 變動導致的錯誤。

Q3：為什麼建議使用 .nvmrc 而非手動切換 Node 版本？

A：團隊協作應盡可能減少人為失誤。透過在專案根目錄放置 .nvmrc，成員只需執行 nvm use 指令，工具就會自動根據設定切換到指定版本。這能有效避免因 Node 版本差異（如：ESM 支援度不同）導致的本地運行或建置失敗。

• ← 上一篇
• 下一篇 →