Windows 10下执行npm run dev后Next.js项目自动终止求助

1. 检查Node.js版本兼容性 #

Next.js对Node.js版本有明确要求，当前稳定版需要Node.js 18.17+或20.x及以上版本。执行以下命令查看当前版本：

node -v

若版本不达标，直接下载对应LTS版本安装，重启终端后重试启动命令。

2. 清理依赖缓存并重装依赖 #

• 删除项目目录下的node_modules文件夹和package-lock.json文件
• 执行缓存清理命令：

npm cache clean --force

• 重新安装依赖：

npm install

完成后再次运行npm run dev

3. 排查端口占用 #

Next.js默认使用3000端口，若该端口被其他程序占用，会导致启动失败后终止。执行命令查看端口占用情况：

netstat -ano | findstr :3000

若有结果，记下对应的PID，打开任务管理器结束该进程；也可以直接指定其他端口启动：

npm run dev -- -p 3001

4. 查看详细启动日志 #

添加verbose参数获取完整启动日志，定位具体错误：

npm run dev -- --verbose

根据日志中的错误关键词（如模块缺失、配置错误、权限提示等）针对性处理。

5. 以管理员身份运行终端 #

右键终端选择“以管理员身份运行”，再执行npm run dev，避免因系统权限不足导致进程被强制终止。

6. 临时禁用防火墙/杀毒软件测试 #

部分Windows防火墙或杀毒软件会拦截Next.js进程，临时关闭后重试启动。若问题解决，将项目文件夹添加到安全软件的信任列表。

7. 创建新空白项目验证 #

用相同命令创建全新项目：

npx create-next-app test-new

进入新项目执行npm run dev，若能正常启动，说明原项目文件可能损坏，对比两个项目的package.json、next.config.js等配置文件找出差异。

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