Debian Node.js日志中常見錯誤及解決方案

1. 端口沖突（Error: listen EADDRINUSE :::3000）
原因：應用程序嘗試綁定的端口（如3000）已被其他進程占用，常見于多應用共存或進程未正常關閉的場景。
解決方法：

• 使用lsof -i :3000命令查找占用端口的進程ID（PID），再用kill -9 <PID>終止該進程；
• 修改應用程序的端口號（如將app.listen(3000)改為const port = process.env.PORT || 3001; app.listen(port)），避免端口沖突。

2. 依賴模塊未找到（Error: Cannot find module ‘xxx’）
原因：項目依賴的模塊未安裝（如首次運行未執行npm install），或node_modules目錄被誤刪除。
解決方法：

• 在項目根目錄下運行npm install xxx安裝缺失的模塊；
• 若依賴較多，建議運行npm install安裝package.json中定義的所有依賴，確保依賴完整性。

3. 語法錯誤（SyntaxError: Unexpected token）
原因：代碼中存在語法錯誤（如缺少括號、引號、拼寫錯誤），導致Node.js無法解析代碼。
解決方法：

• 查看錯誤日志中的堆棧跟蹤（Stack Trace），定位到具體代碼行；
• 使用文本編輯器（如VSCode）的語法檢查功能，修復拼寫或符號錯誤（如將const x = { name: 'John'補全為const x = { name: 'John' };）。

4. 未捕獲的異常（Error: Uncaught Exception）
原因：同步代碼中拋出的異常未被try-catch捕獲，或異步操作（如Promise、回調函數）中的錯誤未被處理，導致應用程序崩潰。
解決方法：

• 為同步代碼添加try-catch塊（如try { riskyOperation(); } catch (err) { console.error('Caught error:', err); }）；
• 添加全局異常處理器，捕獲未處理的異常并優雅退出（如process.on('uncaughtException', (err) => { console.error('Uncaught exception:', err); process.exit(1); })）；
• 處理異步操作的錯誤（如Promise的.catch()或async/await的try-catch）。

5. 未處理的Promise拒絕（UnhandledPromiseRejectionWarning）
原因：Promise被拒絕（如reject()或拋出錯誤），但未通過.catch()或async/await的try-catch處理，可能導致內存泄漏或意外行為。
解決方法：

• 為Promise添加.catch()（如someAsyncFunction().catch(err => console.error('Promise rejected:', err))）；
• 使用async/await時，用try-catch包裹異步代碼（如async function run() { try { await someAsyncFunction(); } catch (err) { console.error('Error:', err); } }）；
• 添加全局未處理拒絕處理器（如process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled rejection:', reason); })）。

6. 文件或目錄不存在（Error: ENOENT: no such file or directory）
原因：應用程序嘗試訪問的文件或目錄不存在（如配置文件路徑錯誤、上傳目錄未創建），或路徑拼寫錯誤。
解決方法：

• 檢查錯誤日志中的文件路徑，確認路徑是否存在（如使用ls /path/to/file）；
• 使用path.join(__dirname, 'relative/path')構建跨平臺兼容的路徑（避免硬編碼/或\）；
• 若目錄不存在，使用mkdir -p /path/to/directory創建目錄（如上傳目錄）。

7. 權限不足（Error: Permission denied）
原因：Node.js進程沒有足夠的權限訪問文件、目錄或端口（如綁定1024以下端口需要root權限，或日志目錄無寫入權限）。
解決方法：

• 避免使用root運行應用（使用sudo可能導致安全問題），改為用普通用戶運行；
• 修改文件/目錄權限（如chmod +x script.js賦予執行權限，chmod -R 755 logs/賦予日志目錄寫入權限）；
• 更改端口（如將端口改為3000以上，避免需要root權限）。

8. Node.js版本兼容性問題
原因：應用程序依賴的模塊或代碼需要特定版本的Node.js（如舊模塊不支持Node.js 18+），導致運行錯誤。
解決方法：

• 使用node -v檢查當前Node.js版本，確認是否符合應用要求；
• 使用n或nvm（Node Version Manager）切換版本（如sudo apt install n，然后sudo n 16切換到Node.js 16）；
• 更新應用依賴（如npm update），確保模塊支持當前Node.js版本。

9. 內存溢出（Error: Memory Limit Exceeded / JavaScript heap out of memory）
原因：應用程序消耗過多內存（如處理大文件、內存泄漏），超過Node.js默認的1.4GB內存限制（64位系統）。
解決方法：

• 使用--max-old-space-size標志增加內存限制（如node --max-old-space-size=4096 app.js將內存限制提升至4GB）；
• 分析內存使用情況（如使用node --inspect配合Chrome DevTools，或clinic.js工具），找出內存泄漏點（如未釋放的緩存、無限循環）；
• 優化代碼（如分塊處理大文件、避免全局變量、及時釋放資源）。

10. 流未處理的異常（Stream Unhandled Error）
原因：流（如文件流、HTTP請求流、Socket流）操作中發生錯誤（如文件讀取失敗、網絡中斷），未附加錯誤處理程序導致進程崩潰。
解決方法：

• 為流對象附加error事件處理程序（如const stream = fs.createReadStream('file.txt'); stream.on('error', (err) => { console.error('Stream error:', err); })）；
• 使用try-catch包裹同步流操作（如fs.readFileSync），捕獲可能的錯誤；
• 避免未處理的流錯誤導致進程退出（如監聽process.on('uncaughtException')作為最后防線）。