npm 全域安裝造成的環境污染

STEP 1 先釐清專案狀況

• 如果你是用 npm run build 來編譯 Vue 專案，那麼答案就更清楚了：

✅ 你 需要 @vue/cli-service，而 不一定需要 @vue/cli。

因為 npm run build 背後實際執行的是：

vue-cli-service build

這個指令就是來自 @vue/cli-service，而它應該是安裝在你的專案 devDependencies 裡。

@vue/cli-service 提供整個 Vue CLI 專案的核心功能：開發伺服器（serve）、打包編譯（build）、設定 webpack、babel 等整合設定。

@vue/cli 則是提供 vue create、vue ui 等 建立專案 和圖形化介面用的工具，對已經建立好的專案沒有影響。

安裝 vue/cli-servic

分為 -D, 安裝到 devDependencies (開發環境)

沒有 D，安裝到 dependencies (正式環境)

P.S 沒有人在安裝全域的，注意!!

指令	說明	結果
npm install -D @vue/cli-service	✅ -D 是 --save-dev 的縮寫	安裝到 devDependencies（只在開發環境使用）
npm install @vue/cli-service	❌ 沒有 -D，會安裝到 dependencies	安裝到正式環境的 dependencies

---

你抓到了超關鍵的線索！

C:\Users\你的帳號\AppData\Roaming\npm

是 npm 全域安裝（-g）套件的預設執行路徑。

裡面放的 .cmd 和 .exe 會被加入 PATH，所以：

• 你跑 npm run build 時，有很高機率是呼叫了全域的 vue-cli-service.cmd，而不是你專案裡的版本。

這就像你明明想用小王的工具，卻拿到小明上週留下來的版本一樣

解法方法: 穩定專案環境這樣做：

1. 砍掉全域的 vue-cli 或 vue-cli-service

• 先查看目前的全域變數設定

npm list -g @vue/cli
npm list -g @vue/cli-service

npm uninstall -g @vue/cli
npm uninstall -g @vue/cli-service

如果你也曾裝過 vue-cli 的 GUI，可以一併移除。

2. 確認你的專案本地有裝 @vue/cli-service

• 查看本地安裝

npm list @vue/cli-service

沒看到？立刻補裝：

npm install -D @vue/cli-service

Vue CLI 項目裡的 vue-cli-service 是透過 node_modules/.bin/vue-cli-service 執行的，千萬別靠全域！

3. 重建乾淨環境（推薦）

rd /s /q node_modules
del package-lock.json
npm install

接著再試：

npm run build

• 小建議（防未來踩雷）

如果你日後要切換多種 Vue 專案（CLI、Vite 混合），強烈建議使用 nvm 管理 Node.js 版本，並在每個專案根目錄加上 .nvmrc 來指明版本，例如：

14.21.3

然後用：

nvm use

保持乾淨穩定的環境 👌

---

補充說明

nvm use

nvm use

它會去讀你資料夾裡的 .nvmrc 檔案，裡面通常只寫一行版本號，例如：

16.20.2

然後 nvm 就會切換到對應版本的 Node.js

@vue/cli 和 @vue/cli-service

指令	用途	為何建議移除
@vue/cli	全域 CLI 工具	會污染 PATH，可能導致版本不一致與衝突
@vue/cli-service	CLI 執行核心	不應全域安裝，應隨專案本地版本安裝與執行

你真正需要的是「在你的專案目錄內」安裝：

npm install -D @vue/cli-service

這樣你才能確保：

本地版 CLI 和專案相容

不會亂跑到全域版本

📦 npm install -D 說明整理

不要用 npm install 裝開發工具，會污染最終環境。

指令	全寫	安裝位置	用途與說明
npm install -D	--save-dev	devDependencies	僅開發階段使用，如編譯、測試、建置工具
npm install	--save（預設）	dependencies	會在執行時（production）被用到的程式依賴

✅ 常見適合用 -D 的套件範例

套件名稱	原因與用途
@vue/cli-service	建置用，不需進入正式環境
vite	開發與打包專用
eslint / prettier	程式碼格式與檢查工具
jest / vitest	單元測試工具
typescript	開發時轉譯 TypeScript 用

❌ 不該用 -D 的套件（會在正式環境中使用）

套件名稱	正確用法	說明
vue	npm install vue	執行期會用到
axios	npm install axios	前端發 API 用
lodash	npm install lodash	工具函式，執行時需使用

---

說明

套件	說明	比喻角色
@vue/cli	提供命令列介面（CLI）、互動式操作、插件管理、UI 工具等	🐚 shell（像 bash 或 zsh）
@vue/cli-service	執行實際任務：開發伺服器、打包、編譯、測試等核心功能	🧠 kernel（像 Linux kernel）

套件	安裝位置	每台電腦幾份？	每個專案幾份？	說明
@vue/cli	全域（global）	✅ 1 份	❌ 不存在	提供 vue 指令的 CLI 工具，用來「建立或管理專案」
@vue/cli-service	專案內（local）	❌ 沒有全域	✅ 每個專案 1 份	專案建好後的開發核心，引擎負責 serve、build、lint 等等

• @vue/cli : 像是 shell

• @vue/cli-service : 是 Vue CLI（@vue/cli）所提供的核心服務套件。簡單來說，它就是 Vue CLI 幫你 打包、開發、測試、建構專案的引擎。

==> 就是 vue-cli 的引擎。