6.2 常見錯誤情境與一句話解決方案
執行與環境
| 情境 | 解法 |
command not found: node | 沒裝或 nvm 未載入：nvm use 或重開終端機 |
| 不同專案需要不同 Node 版本 | 每個專案放 .nvmrc，進專案 nvm use |
EADDRINUSE: port 已被占用 | 殺掉舊程序：lsof -i :3000 找到 PID 後 kill <PID> |
套件與依賴
| 情境 | 解法 |
MODULE_NOT_FOUND | 沒裝套件：npm install；或 import 路徑打錯 |
| node_modules 壞了或狀態怪異 | 刪掉重裝：rm -rf node_modules && npm install |
| 裝錯了，裝到 dependencies | npm uninstall <pkg> 再 npm install -D <pkg> |
| 升級套件後壞掉 | 看 package-lock 回退：npm install <pkg>@<舊版號> |
| 全域安裝造成版本衝突 | 改用 npx <tool> 或裝在專案的 devDependencies |
非同步與錯誤
| 情境 | 解法 |
await is only valid in async function | 函式前面加上 async |
| Promise 錯誤沒被接住（UnhandledPromiseRejection） | 加 try/catch 或 .catch() |
| 讀檔讀不到（ENOENT） | 確認路徑：用 path.join(__dirname, ...) 拼絕對路徑 |
| 非同步順序錯亂（值還沒回來就用了） | 依序就 await；平行就 Promise.all |
Express 與設定
| 情境 | 解法 |
req.body 是 undefined | 忘了加 app.use(express.json()) |
| 路由 404 | 檢查路徑與方法是否一致、路由註冊順序 |
| 環境變數讀不到 | 忘了 import "dotenv/config" 或 .env 檔不在根目錄 |
| 機密不小心 commit 了 | 立刻更換該機密（改密碼、作廢 Key），歷史裡的刪不掉 |
測試
| 情境 | 解法 |
node --test 找不到測試 | 測試檔名要有 .test.js |
| 測試要連真實資料庫，又慢又不穩 | 依賴注入 + mock 取代真實依賴 |
| 測試之間互相影響 | 每個測試要獨立，不要共用可變狀態 |
| supertest 掛住不結束 | app.js 拆開：只 import app，不要在測試中 listen |
終極保險：先看清錯誤訊息的第一行與檔案行號，再決定下一步。80% 的錯誤訊息本身就寫著答案。