如何在 ServBay 中啟用與使用 npm（Node.js 套件管理器）

npm（Node Package Manager）是 Node.js 官方的套件管理工具，也是全球規模最大的開源軟體庫之一。對於 Node.js 開發者來說，npm 是不可或缺的工具，可協助您輕鬆安裝、分享並管理專案中的各種依賴。透過 ServBay 提供的整合環境，您可以立即開始使用 npm 進行開發。

前置條件

在使用 npm 前，您需要先在 ServBay 中安裝 Node.js。

1. 開啟 ServBay 應用程式。
2. 前往「套件」（Packages）面板。
3. 找到 Node.js 套件並確認已安裝且正在執行中。

ServBay 會自動配置好 Node.js 環境，其中就已包含 npm。

確認 npm 已安裝且可用

透過 ServBay 安裝的 Node.js 已經內建 npm，並預設啟用。您可以透過終端機快速檢查 npm 是否正確安裝且可供使用。

1. 開啟您的終端機應用程式（如 macOS 的 Terminal）。

2. 輸入以下指令查詢 npm 版本：

   npm -v

   若指令成功執行並顯示版本號（例如 10.2.0 或更高），就代表 npm 已正確安裝並可在目前環境下直接使用。

   # 範例輸出
   10.2.0

   如果您看到「command not found: npm」等錯誤，請確認您已透過 ServBay 安裝 Node.js 套件，並且 ServBay 的環境變數已正確載入（通常重啟終端機或電腦可解決此問題）。

升級 npm

雖然 ServBay 所安裝的 Node.js 版本通常已集成穩定版 npm，但 npm 本身仍會獨立於 Node.js 頻繁更新。若想獲得最新功能與修補，您可透過 npm 自行升級：

npm install -g npm@latest

這條指令會全域安裝最新版的 npm。-g 參數代表全域安裝，讓您在任何目錄下都能使用新版本的 npm 指令。

升級完成後，可再次執行 npm -v 來確認版本號：

npm -v

npm 核心功能與常用操作

npm 最大強項在於其龐大的開源生態系與靈活的依賴管理能力。以下整理幾個日常開發常見情境與對應指令：

初始化新的 Node.js 專案

在空目錄中啟動全新 Node.js 專案時，您可以使用 npm init 指令建立 package.json 檔案。這個檔案記錄專案基本資料、依賴資訊與可執行指令稿。

cd /Applications/ServBay/www/my-new-project.servbay.demo
npm init

npm init 會引導您填寫專案名稱、版本、描述、主檔案等資料。若想快速建立預設 package.json，可直接用 npm init -y。

安裝專案依賴

在專案根目錄（含有 package.json 檔的目錄）下，可執行 npm install 安裝所有必要依賴。

cd /Applications/ServBay/www/my-project.servbay.demo
npm install

此指令會讀取 package.json 內的 dependencies 與 devDependencies 欄位，自動下載套件到專案的 node_modules 目錄。

新增依賴套件

當您需要在專案導入新函式庫或框架時，可用 npm install <package-name> 安裝：

# 安裝執行環境依賴，例如 Express 框架
npm install express

# 安裝開發時依賴，例如測試用的 Mocha
npm install mocha --save-dev

預設情況下，npm install <package-name> 會將套件安裝至 node_modules，並自動更新 package.json 的 dependencies 欄位。若加上 --save-dev 參數，則會寫入 devDependencies，這用於開發、測試或建置工具。

移除依賴套件

如果專案不再需要某個套件，可用 npm uninstall <package-name> 將其移除。

npm uninstall express

套件會從 node_modules 移除，同時更新 package.json。

升級專案依賴

為確保專案依賴維持最新（在 package.json 允許範圍內），可用 npm update：

npm update

該指令將根據 package.json 版本限制，更新 node_modules 內的套件至最新相容版本。

使用 npm 指令稿（Scripts）

package.json 裡的 scripts 欄位，讓您自定專案用來自動化重複工作的指令稿，例如啟動伺服器、執行測試或專案建置等。

舉例，您可以在 package.json 增加下列 scripts 設定：

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js",
    "test": "mocha test/**/*.js",
    "build": "webpack --config webpack.config.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "mocha": "^10.2.0",
    "webpack": "^5.89.0"
  }
}

接下來，即可用 npm run <script-name> 執行這些腳本：

# 啟動應用程式
npm start

# 執行測試
npm test

# 執行專案建置
npm run build

特別注意，像 start、test、install、restart、stop 等少數預設腳本名稱，可以省略 run，直接使用 npm start、npm test 等。

常見 npm 指令速查

除了上列重點用法外，npm 還有下列常見輔助指令：

• 安裝全域套件：可安裝系統任意地方可用的 CLI 工具。

  npm install -g <package-name>
  # 例如安裝可用於臨時執行指令的 npx（通常 Node.js 已自帶）
  npm install -g npx
  # 例如安裝常用 CLI 工具 nodemon，自動重新啟動應用
  npm install -g nodemon

• 執行臨時指令（npx）：npx 是 npm 5.2+ 內建工具，可方便執行 node_modules/.bin 指令，或臨時下載並運行特定套件命令，無需全域安裝。

  # 不必全域安裝 create-react-app 也能創建新 React 應用
  npx create-react-app my-react-app

• 檢視全域已安裝套件：列出所有全域安裝套件及版本。

  npm list -g --depth=0

• 清除 npm 快取：有些安裝錯誤可能與快取有關，可嘗試清空快取以排除問題。

  npm cache clean --force

• 查看套件資訊：查詢特定套件詳細資料，包括版本、依賴、Git 倉庫網址等。

  npm view <package-name>

• 搜尋套件：於 npm 套件庫搜尋特定關鍵字的套件。

  npm search <keyword>

疑難排解

• npm command not found：確保您已透過 ServBay 安裝 Node.js 套件，且終端機 session 可讀取 Node.js 與 npm 路徑。通常重啟終端機或電腦可解決路徑問題。
• 依賴安裝失敗：請確認網路連線。有些公司的代理伺服器可能會影響 npm 安裝，需設定 npm 的代理。也可先清除 npm 快取（npm cache clean --force）再重試。
• 權限問題：在 macOS 上，全域安裝（npm install -g）有時會遇到權限不足。建議使用 Node Version Manager（nvm），或確認 ServBay 已正確配置安裝路徑，盡量避免直接用 sudo 全域安裝，否則易導致其他權限問題。ServBay 內建 Node.js 通常已解決相關權限，允許您在 ServBay 目錄下自由操作。

結語

透過 ServBay，您可在本機輕鬆取得完整的 Node.js 開發環境，並立即開始運用強大的 npm 工具進行套件管理與專案開發。熟悉 npm 基本操作與常用指令，將大幅提升您的開發效率。隨著您更深度探索 Node.js 生態系，npm 也將成為您不可或缺的好夥伴。