执行npm run dev后Node.js卡顿，求助排查Next.js启动问题

可能的原因及修复步骤： #

1. 降级Next.js版本 #

13.1.x部分版本存在Fast Refresh兼容性问题，建议切换到稳定版本：

• 卸载当前版本：npm uninstall next
• 安装13.0.x稳定版：npm install next@13.0.8
• 重新启动项目：npm run dev

2. 排查VS Code插件冲突 #

第三方插件可能干扰Next.js编译流程：

• 暂时禁用所有非核心插件（保留ESLint、Prettier即可）
• 重启VS Code后再次执行npm run dev

3. 清理项目缓存与依赖 #

残留缓存或损坏的依赖可能引发异常：

• 删除.next文件夹：rm -rf .next（Windows系统执行rd /s /q .next）
• 删除node_modules和锁文件：rm -rf node_modules package-lock.json
• 重新安装依赖：npm install
• 启动项目：npm run dev

4. 检查端口占用与Node.js版本 #

• 确认3000端口未被占用：lsof -i :3000（Windows执行netstat -ano | findstr :3000），若被占用则终止对应进程，或修改启动端口（在package.json中将dev命令改为next dev -p 3001）
• 升级Node.js到LTS版本（18.x或20.x），Next.js 13要求Node.js 16.8以上，高版本兼容性更优

5. 临时禁用Fast Refresh验证 #

在next.config.js中添加配置关闭Fast Refresh，确认是否为该功能导致卡顿：

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  fastRefresh: false,
}

module.exports = nextConfig

保存后执行npm run dev观察终端状态

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