Node.js、npm、npx 完整指令入門 — 60 個指令一次搞懂

Node.js 除了能在伺服器端執行 JavaScript，更帶來了 npm（Node Package Manager）生態系，讓開發者能以數十萬個開源套件加速開發。而 npx 則讓我們能在不全局安裝的前提下執行 npm 套件中的命令。三者組合起來，構成現代 JavaScript 開發的基石。

本文整理 Node.js、npm、npx 的核心概念與 60 個常用指令，從環境安裝到套件管理、專案初始化到布署，一次學會。

Node.js 基礎概念

Node.js 是一個基於 V8 引擎的 JavaScript 伺服器執行環境。它使用事件驅動、非阻塞 I/O 模型，輕量且高效，非常適合 I/O 密集型應用。

版本管理

💡 nvm（Node Version Manager） 讓你在同一台電腦上管理多個 Node.js 版本，避免不同專案對版本的依賴衝突。

執行 JavaScript 檔案

Node.js 模組系統

Node.js 支援 CommonJS（require）與 ES Modules（import）兩種模組語法。

npm 核心概念

npm 由三部分組成：CLI（命令列界面）、Registry（全球最大的 JavaScript 套件倉庫）、Website（套件資訊查詢）。npm 會在專案中建立 node_modules 資料夾存放所有依賴。

npm init — 初始化專案

在專案根目錄執行 npm init 會引導式建立 package.json 檔案。

# 互動式建立 package.json（問答題）
npm init

# 跳過問答，使用預設值
npm init -y

# 使用指定初始化器（等同 npm exec create-foo）
npm init vue@latest

npm install — 安裝套件

npm install 是最常用的指令，用於安裝專案依賴。

# 安裝 package.json 中的所有依賴
npm install

# 安裝指定套件到 dependencies
npm install lodash

# 安裝指定套件到 devDependencies
npm install --save-dev jest
npm i -D jest

# 安裝套件的指定版本
npm install react@18

# 安裝特定 tag版本 (beta / latest / next)
npm install react@beta

# 全域安裝（不推薦，尤其是工具）
npm install -g typescript

# 安裝 .tgz 檔案
npm install ./package.tgz

# 從 GitHub 安裝
npm install username/repo
npm install github:user/repo#v1.0.0

⚠️ npm ci 與 npm install 的差別： npm ci 會刪除原有的 node_modules 並根據 package-lock.json 進行完整安裝，速度快且確保環境一致性，非常適合 CI/CD 流程。

npm uninstall / update / outdated — 管理套件版本

npm ls — 查看依賴樹

npm run — 執行腳本

npm 可以在 package.json 的 scripts 區塊定義指令腳本，並透過 npm run 執行。

// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "jest",
    "lint": "eslint ."
  }
}

# 執行腳本
npm run dev
npm run build
npm test      # 等同 npm run test

# 列出所有可用的腳本
npm run

# 執行前顯示指令（不執行）
npm run dev --dry-run

npm test — 執行測試

npm publish — 發布套件

⚠️ 發布前請三思： npm publish 一旦完成就無法撤回，發布前記得檢查版本號和是否已發布過。

# 發布流程範例
npm login
npm version patch
npm publish

npm cache / npm config / npm doctor

npx 完整攻略

npx 是 npm 5.2.0 版本 bundled 的一個工具。它的存在解決了一個問題：在執行 npm 套件中的命令時不需要全局安裝，只需透過 npx 下載到快取並執行。

npx 的三種主要用途

1. 執行已發布的 npm 套件命令

💡 最佳實踐： 當你不確定專案會不會長期使用某個工具時，盡量用 npx 執行，而非全局安裝。

# 執行 create-react-app，不需全局安裝
npx create-react-app my-app

# 指定版本
npx create-react-app@5 my-app

# 加上 --yes 自動確認安裝
npx create-react-app my-app --yes

# 使用 --package 指定套件來源
npx --package=vue-cli vue --version

2. 執行本地已安裝的套件命令

如果套件已在本地 node_modules/.bin 中，npx 會直接執行，無需重新下載。

# 在本地安裝 jest 後執行
npx jest

# 執行本地 vite（不需全局安裝）
npx vite build

3. 執行 GitHub 上或本地的包

# 從 GitHub 執行
npx github:owner/repo

# 從本地檔案執行
npx ./package.tgz

🎯 npx vs npm exec： npx 和 npm exec 在本質上是相同的，npm exec 只是將 npx 整合到 npm 工作流程中。兩者可以互換使用，npx 保留是為了向後兼容。

npx 常見使用場景

# 初始化專案（React）
npx create-react-app my-app

# 初始化專案（Vue）
npx @vue/cli create my-vue-app

# 升級 TypeScript 編譯器
npx tsc --version

# 使用 ESLint 檢查
npx eslint .

# 運行 Storybook
npx storybook dev -p 6006

# 執行 Prisma 資料庫遷移
npx prisma migrate dev

# 初始化 Vite
npx vite

package.json 結構

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "我的專案描述",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "keywords": ["node", "express"],
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "jest": "^29.0.0"
  }
}

版本號語義

npm 使用 語義化版本 (SemVer)：major.minor.patch，例如 1.2.3。

開發工作流程總結

一個典型的 Node.js 專案開發流程如下：

# 1. 初始化專案
npm init -y

# 2. 安裝依賴
npm install express
npm i -D nodemon jest

# 3. 新增腳本
npm pkg set scripts.dev="nodemon app.js"
npm pkg set scripts.test="jest"

# 4. 開發 & 測試
npm run dev
npm test

# 5. 檢查過時套件
npm outdated
npm update

# 6. 發布 (若為函式庫)
npm version patch
npm publish

常見問題與技巧

npm 報錯：ERESOLVE 依賴衝突

當遇到依賴衝突（兩個套件需要不同版本的同一套件）：

# 嘗試使用 --legacy-peer-deps 繞過
npm install --legacy-peer-deps

npm 報錯：npm ERR! 無法移除 node_modules

# 手動刪除 node_modules 和 lock 檔案
rm -rf node_modules package-lock.json
npm install

npm 速度慢？切換 registry

# 使用 npmmirror (npm 中國鏡像)
npm config set registry https://registry.npmmirror.com

# 恢復官方 registry
npm config set registry https://registry.npmjs.org

# 或使用 nrm 管理 registry
npm i -g nrm
nrm use npmmirror

🎯 快速回顧： npm 用於管理依賴（packages），npx/npx exec 用於臨時執行套件命令；npm ci 適合部署時使用；npm run 管理專案腳本；npm publish 發布函式庫。養成使用 nvm 管理版本的習慣，能大幅減少環境問題。