本篇重點
- npm 常用指令速查表及各指令的詳細說明
- 說明 npm 從初始化到安裝到更新到移除等等實用指令
npm install和npm ci的差異
npm（Node Package Manager）是 Node.js 官方提供的套件管理工具，用於安裝、更新、移除與管理 JavaScript 套件。隨著前端與全端生態發展，npm 已成為專案初始化與依賴管理的標準配備。
npm 指令速查表
| 指令 (縮寫) | 核心用途 | 使用時機 |
|---|---|---|
init | 初始化專案 | 建立新專案並產生 package.json 時。 |
install (i) | 安裝套件 | 初次下載專案或新增第三方函式庫時。 |
uninstall (un, rm) | 移除套件 | 專案不再需要特定函式庫時。 |
update (up) | 更新套件 | 需要升級套件版本以獲取新功能或修復時。 |
run | 執行腳本 | 啟動伺服器、打包建置或執行測試時。 |
ci | 潔淨安裝 | 在 CI/CD 流程中確保依賴版本與 Lock 檔完全一致時。 |
ls | 檢視套件樹 | 檢查當前安裝的套件列表與版本結構時。 |
outdated | 檢查過期套件 | 確認有哪些套件存在新版本可供升級時。 |
audit | 安全稽核 | 掃描專案依賴是否存在已知的資安漏洞時。 |
npm init
專案初始化
用途與建議
- 建立
package.json檔案。 - 定義專案基本資訊與相依結構。
- 新專案第一步必用。
- 已存在
package.json時不需重複執行。
常用指令
npm init：互動式建立，需逐一回答問題。npm init -y：跳過問答，直接以預設值建立檔案。
npm install
安裝套件（縮寫：npm i）
用途與建議
- 解析並安裝
package.json中定義的依賴套件至node_modules目錄。 - 開發工具類套件務必使用
-D，避免增加生產環境的部署體積。
常用指令
npm i：讀取package.json安裝所有依賴。npm i <package>：安裝特定套件並寫入dependencies（等同於npm i <package> --save）。npm i <package> -D：安裝開發專用套件（如 webpack, jest），更新package.json寫入devDependencies。npm i <package> -g：安裝套件到全域環境（npm 的 global 目錄），通常用來安裝「指令型工具（CLI）」（如 nodemon, npm-check-updates），package.json和node_modules目錄皆不會更新。npm i <package> --no-save：只安裝到node_modules目錄，不會修改package.json，dependencies / devDependencies也都不會新增。npm i <package> -E：鎖定精確版本號（移除^符號），確保版本完全固定。
健忘筆記
當前的預設行為 (npm v5+)
自 2017 年 (v5.0.0) 起，npm install
- 自動寫入：套件會自動加進 package.json 的 dependencies 列表。
- 版本鎖定：同步更新 package-lock.json，確保團隊安裝的版本一致。
- 目的：防止開發者忘了存檔，導致其他人下載專案後因缺少套件而無法執行。
過去的行為 (npm v5 以前)
在舊版本中，npm install
- 手動存檔：你必須明確加上 --save（或 -S），npm 才會把套件寫進 package.json。
- 容易出錯：如果忘了加參數，套件只會存在於你電腦的 node_modules 裡；當專案上傳到 Git 後，其他成員執行 npm install 會抓不到該套件，造成開發環境不統一。
npm ci
自動化環境安裝
用途與建議
- Clean Install，專為自動化環境設計的安裝指令。
- 在 CI/CD Pipeline（如 GitHub Actions, Jenkins）中，應使用 npm ci 取代 npm install，確保部署環境與開發環境完全一致，避免因版本浮動導致的建置失敗。
常用指令
npm ci：先刪除 node_modules，並嚴格依照 package-lock.json 安裝。
和 npm install 的差異
| 項目 | npm i / npm install | npm ci |
|---|---|---|
| 主要用途 | 日常開發、新增或更新套件 | 持續整合 (CI)、部署、自動化測試 |
是否需要 package-lock.json | 不一定需要 | 一定需要 |
是否會更新 package-lock.json | 可能會更新 | 不會更新 |
| 版本解析方式 | 依 package.json 版本範圍重新解析 | 完全依照 package-lock.json |
node_modules 行為 | 僅更新差異部分，不會刪除現有資料 | 先刪除再重裝 |
| 安裝速度 | 較慢（需解析相依） | 通常較快 |
| 適合環境 | 本地開發 | CI / CD、正式建置 |
健忘筆記
開發用 npm i，自動化與部署用 npm ci。
npm run
執行專案腳本
用途與建議
- 用於執行 package.json 中 scripts 定義的指令。
- 將常用指令（如 build、dev、test）標準化，避免手動輸入完整指令。
- 適合專案開發、建置、測試與部署流程。
- 若指令名稱為 start、test、restart 或 stop，可省略 run 直接執行（如
npm start）。
常用指令
npm run <script>：執行指定的腳本（如npm run build）。npm run：列出目前專案中所有可用的 scripts。
npm uninstall
移除套件（縮寫：npm un, npm rm）
用途與建議
- 從專案中移除已安裝套件。
- 同步更新
package.json與package-lock.json檔案。 - 移除前需先搜尋專案是否仍有引用。
常用指令
npm uninstall <package>：移除指定套件npm uninstall -g <package>：移除指定全域環境套件
健忘筆記
可使用 npm list -g 來查看當前有哪些全域套件。
npm outdated
檢查過期套件
用途與建議
- 檢查目前安裝套件是否有可更新版本。
- 列出所有有新版本的套件，包含
Current（當前安裝）、Wanted（符合語意化版本範圍的最高版）、Latest（最新版）。 - 定期維護專案時使用。
常用指令
npm outdated：確認哪些套件存在新版本可升級。
健忘筆記
語意化版本（Semantic Versioning, SemVer）
SemVer 格式：MAJOR.MINOR.PATCH
- MAJOR：不相容的重大變更
- MINOR：向下相容的新功能
- PATCH：向下相容的錯誤修正
範例：2.4.1
版本符號
- ^：允許更新不變更主版本的最新版
- ~：允許更新修補版本
- *：接受任何版本
範例：^2.4.1、~2.4.1
npm update
更新套件（縮寫：npm up）
用途與建議
- 將套件更新至
Wanted版本，並修改package-lock.json（不修改package.json）。 - 可使用
npm outdated查詢Wanted版本。
常用指令
npm update：更新套件npm update <package>：更新指定套件
npm ls
檢視套件樹
用途與建議
- 顯示目前專案的套件相依樹。
- 用於檢查實際安裝版本與巢狀關係。
- 套件衝突或版本疑慮時使用。
常用指令
npm ls：列出完整的依賴樹狀圖npm ls <package>：列出指定套件的依賴樹狀圖npm ls --depth=0：僅列出第一層（頂層）依賴，可以快速查看專案直接引用的套件版本。
npm audit
安全性修復
用途與建議
- 掃描依賴套件的已知漏洞。
常用指令
npm audit：產出安全性報告。npm audit fix：嘗試自動修復可相容的漏洞版本。
