node Roadmap
Node.js / pnpm 排障专题
Node.js / pnpm 排障专题：聚合 EADDRINUSE 端口占用、pnpm install 失败、Node 内存溢出、进程管理和 PM2 残留进程等 Node.js 运维问题的完整排障路径与命令模板。
Node.js 排障先区分端口占用、依赖安装、内存溢出和进程管理四类问题，EADDRINUSE 不要简单换端口掩盖僵尸进程，pnpm install 失败先看 lockfile 和 registry 配置而不是删除重装。
Troubleshooting Path
推荐排障路线图
- 01
先确认端口占用情况
用 lsof -iTCP:<port> -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 还是换端口。
- 02
再排查依赖安装问题
pnpm install 失败先看 lockfile 是否一致、registry 是否可达、node 版本是否匹配，不要随手删除 lockfile 导致依赖版本不可控。
- 03
继续检查内存和进程状态
Node 内存溢出用 --max-old-space-size 调整堆限制，PM2 管理的进程用 pm2 list 和 pm2 logs 排查，不要手动 kill 导致进程泄漏。
- 04
最后处理信号和优雅退出
在应用中监听 SIGTERM/SIGINT 信号，正确关闭服务器和数据库连接后退出，避免 kill -9 导致连接泄漏和临时文件残留。
Common Issues
高频问题入口
Before You Change
执行前检查
- 不要简单改端口掩盖僵尸进程，长期累积会占用大量端口和内存
- kill -9 不给进程清理机会，优先用 kill（SIGTERM）
- 开发环境用 PORT 环境变量管理端口，配合 cross-env 跨平台设置
- PM2 管理的进程用 pm2 kill 清理，而不是手动 kill
Start Here
优先阅读
Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
排障Spring Boot 端口被占用怎么解决
Spring Boot 启动报 Web server failed to start: Port 8080 was already in use 时，Linux 用 lsof -iTCP:8080 -sTCP:LISTEN、Windows 用 netstat -ano | findstr :8080 找占用进程，判断是自身僵尸 Java 进程还是他人服务，再决定 kill 释放或通过 --server.port 换端口。
排障CI 构建内存不足与进程被杀排查
CI 构建时出现 JavaScript heap out of memory、Killed 或 exit code 137，先区分 Node 堆内存不足与系统 OOM，再调整 NODE_OPTIONS=--max-old-space-size、Runner 内存和并发 job，覆盖 GitHub Actions、GitLab CI 和自建 Runner 场景。
排障Linux OOM Killer 与内存不足排查
Linux 进程被 OOM Killer 杀、容器状态 OOMKilled 或 dmesg 出现 Out of memory: Killed process 时，用 dmesg -T 与 journalctl -k 查历史内核日志确认时间和被杀进程，区分宿主机 OOM 与容器 cgroup 限制，再看进程 RSS 增长趋势排查泄漏。
Latest Updates
最近更新
All Runbooks
全部相关内容
CI 构建内存不足与进程被杀排查
CI 构建时出现 JavaScript heap out of memory、Killed 或 exit code 137，先区分 Node 堆内存不足与系统 OOM，再调整 NODE_OPTIONS=--max-old-space-size、Runner 内存和并发 job，覆盖 GitHub Actions、GitLab CI 和自建 Runner 场景。
排障Docker 端口映射后外部访问不了怎么排查
Docker 用 -p 映射端口后从宿主机或外部访问不通时，先确认 docker ps 是否显示 0.0.0.0:host->container 映射，再进容器 ss -lntp 检查应用是否监听 0.0.0.0 而非 127.0.0.1，最后排查 firewalld/ufw/云安全组。
排障Linux OOM Killer 与内存不足排查
Linux 进程被 OOM Killer 杀、容器状态 OOMKilled 或 dmesg 出现 Out of memory: Killed process 时，用 dmesg -T 与 journalctl -k 查历史内核日志确认时间和被杀进程，区分宿主机 OOM 与容器 cgroup 限制，再看进程 RSS 增长趋势排查泄漏。
排障Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
排障pnpm install 失败排查：锁文件、代理和原生依赖
pnpm install 失败或 ERR_PNPM_OUTDATED_LOCKFILE 时，先区分失败发生在下载 registry、解析 pnpm-lock.yaml 还是 postinstall 原生编译阶段，检查 Node 版本、registry、HTTP_PROXY 组合，CI 用 --frozen-lockfile 复现，不要一上来就删 lockfile。
排障Redis 内存占用过高与淘汰策略排查
Redis 内存持续上涨、报 OOM command not allowed when used memory > 'maxmemory' 或 evicted_keys 飙升时，先用 INFO memory 看 used_memory/maxmemory，CONFIG GET maxmemory-policy 确认策略是否 noeviction，再用 --bigkeys 找大 key 并检查 TTL 是否缺失。
排障Spring Boot 端口被占用怎么解决
Spring Boot 启动报 Web server failed to start: Port 8080 was already in use 时，Linux 用 lsof -iTCP:8080 -sTCP:LISTEN、Windows 用 netstat -ano | findstr :8080 找占用进程，判断是自身僵尸 Java 进程还是他人服务，再决定 kill 释放或通过 --server.port 换端口。
命令lsof 查看文件句柄和端口命令
lsof 查看文件句柄、端口和网络连接占用的常用命令，lsof -iTCP:8080 -sTCP:LISTEN 找端口监听进程、lsof -p <pid> 查进程打开的所有文件、+D 递归扫描目录、+L1 找已删除但仍被打开的文件，配合 /proc/<pid>/limits 判断 nofile 限制。
命令Node/Nuxt 构建内存排查命令
Node/Nuxt/Next 构建报 JavaScript heap out of memory 或 exit code 137 时排查内存的常用命令，用 NODE_OPTIONS=--max-old-space-size=4096 扩大 V8 堆，du 查看 .nuxt/.output/.next 构建产物体积，free -h 与 dmesg 判断系统 OOM。
命令ps 查看进程和资源占用命令
Linux ps 查看进程静态快照的常用命令，ps aux --sort=-%cpu/-%mem 按 CPU 或内存排序找可疑进程，ps -ef | grep 按名称过滤，ps -o pid,ppid,stat,etime,cmd 查父子进程和状态，pstree -ap 展示进程树，动态观测配合 top/pidstat。