NextJS项目执行npm run dev连接后终止，本地服务器无法访问

问题现象 #

创建Next.js项目后执行npm run dev，终端短暂显示连接信息后直接回到命令提示符，浏览器无法访问本地开发服务器；但npm run build和npm run start可正常运行。

已尝试的操作：

• 重新创建新项目，问题依然存在
• 使用VS Code外部终端执行命令，无改善
• 验证Node.js版本符合要求
• 删除.next、node_modules、package-lock.json后重新执行npm install和npm run dev，问题未解决

排查与解决方案 #

1. 检查端口占用情况 #

开发服务器默认使用3000端口，可能被其他进程占用：

• Windows：执行netstat -ano | findstr :3000找到占用端口的PID，打开任务管理器结束对应进程
• macOS/Linux：执行lsof -i :3000获取PID，再执行kill -9 <PID>终止进程
  也可以直接指定其他端口启动：

npm run dev -- -p 3001

2. 确认版本兼容性 #

检查Node.js版本与项目Next.js版本是否匹配：

• 查看package.json中next的版本号，对应官方要求的Node.js版本（例如Next.js 13+需Node.js 16.8+）
• 版本不匹配时，用nvm等工具升级/降级Node.js

3. 排查环境变量配置 #

检查项目根目录的.env/.env.local文件，是否存在语法错误：

• 暂时重命名环境变量文件，执行npm run dev测试是否恢复正常
• 若正常，逐步排查每个环境变量的格式问题（比如引号未闭合、变量名非法）

4. 获取启动日志详情 #

添加调试参数执行命令，查看具体错误：

npm run dev -- --debug

也可以直接查看.next/server/logs目录下的日志文件，定位启动失败原因

5. 重置npm配置 #

执行以下命令清理缓存并重置代理配置：

npm config delete proxy
npm config delete https-proxy
npm cache clean --force

之后重新执行npm install和npm run dev

内容的提问来源于stack exchange，提问作者Michael