[ PROMPT_NODE_24704 ]
nodejs
[ SKILL_DOCUMENTATION ]
# Node.js 错误模式
常见的 Node.js 错误及其诊断与解决方案。
## 模块错误
### MODULE_NOT_FOUND
Error: Cannot find module 'package-name'
**原因**：
1. 未安装包
2. 导入/引用时拼写错误
3. node_modules 损坏
4. 相对路径错误
**解决方案**：
bash
# 安装缺失的包
npm install package-name
# 如果 node_modules 损坏
rm -rf node_modules package-lock.json
npm install
# 检查包是否存在
npm ls package-name
**预防**：在 CI/CD 中使用 `npm ci`，并添加安装后检查。
---
### ERR_MODULE_NOT_FOUND (ESM)
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'x' imported from y
**原因**：
1. ESM 导入时缺少文件扩展名
2. 包不支持 ESM
3. package.json 中缺少 `"type": "module"`
**解决方案**：
javascript
// 本地导入需添加文件扩展名
import { foo } from './utils.js' // 而不是 './utils'
// 对于 CommonJS 包，使用 createRequire
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
const pkg = require('commonjs-package')
---
## 网络错误
### ECONNREFUSED
Error: connect ECONNREFUSED 127.0.0.1:3000
**原因**：
1. 服务器未运行
2. 端口错误
3. 防火墙拦截
**诊断**：
bash
# 检查端口是否被占用
lsof -i :3000
netstat -an | grep 3000
# 检查服务是否在运行
ps aux | grep node
**解决方案**：
1. 先启动服务器
2. 验证端口号是否匹配
3. 检查防火墙规则
---
### ENOTFOUND
Error: getaddrinfo ENOTFOUND hostname
**原因**：
1. 主机名/URL 无效
2. DNS 解析失败
3. 无网络连接
**诊断**：
bash
# 测试 DNS 解析
nslookup hostname
dig hostname
# 测试连通性
ping hostname
curl -I https://hostname
**解决方案**：
1. 检查 URL 拼写
2. 尝试使用 IP 地址代替主机名
3. 检查 /etc/hosts 文件
4. 检查 DNS 设置
---
### ETIMEDOUT
Error: connect ETIMEDOUT
**原因**：
1. 网络过慢
2. 服务器负载过高
3. 防火墙静默丢包
**解决方案**：
javascript
// 增加超时时间
const axios = require('axios')
axios.get(url, { timeout: 30000 })
// 使用 fetch
const controller = new AbortController()
setTimeout(() => controller.abort(), 30000)
fetch(url, { signal: controller.signal })
---
## 文件系统错误
### ENOENT
Error: ENOENT: no such file or directory, open 'path/to/file'
**原因**：
1. 文件不存在
2. 路径错误（相对路径 vs 绝对路径）
3. 拼写错误
粤公网安备44030002003366号