Next.js本地执行dev与build命令永久卡住无报错问题求助

• 执行pnpm dev启动开发服务时，进程永久停留在ready - started server on 0.0.0.0:3000, url: http://localhost:3000阶段，无任何错误日志输出，3000端口未实际启动服务，浏览器访问地址无法加载页面
• 执行pnpm build构建生产包时，进程永久停留在info - Creating an optimized production build阶段，无后续输出
• 已尝试删除/node_modules目录与.next缓存目录后重新安装依赖，切换npm、yarn、pnpm不同包管理器执行命令，问题均未解决
• 项目部署到Vercel平台时，可正常完成构建与部署流程，无任何异常

当前项目核心依赖版本：

"dependencies": {
  "@next-auth/mongodb-adapter": "^1.0.1",
  "moment": "^2.29.4",
  "mongodb": "^4.3.1",
  "mongoose": "^6.2.1",
  "next": "^12.2.2",
  "next-auth": "^4.9.0",
  "nextjs-progressbar": "^0.0.13",
  "prettier": "^2.7.1",
  "react": "17.0.2",
  "react-cool-inview": "^2.0.9",
  "react-dom": "17.0.2",
  "react-toastify": "9.0.5",
  "react-tooltip-lite": "^1.12.0",
  "react-typeme": "^1.0.1",
  "use-clipboard-copy": "^0.2.0"
}

按概率从高到低排查，每步操作后重试启动/构建命令验证即可。

1. 修复数据库连接挂起问题 #

90%的同类问题都是这个原因：项目用到了MongoDB相关依赖，大概率在模块顶层（比如NextAuth配置文件、数据库连接工具文件、_app文件顶层）写了直接执行的数据库连接逻辑，本地要么没配Mongo连接的环境变量，要么本地Mongo服务没启动，且连接逻辑没设超时时间，进程会无限等待连接响应，直接阻塞Next的启动和编译流程。
Vercel上正常是因为平台配置了正确的数据库环境变量，能正常连通远程Mongo服务，自然不会卡住。
操作：

• 检查项目根目录是否存在.env.local文件，确认里面配置了和Vercel后台一致的MONGODB_URI等所有数据库相关环境变量，不要漏项
• 如果是连接本地MongoDB，先确认本地Mongo服务已经正常启动，连接地址和端口配置正确
• 给MongoDB连接加上超时参数，避免无限挂起，mongoose连接参考修改：

await mongoose.connect(process.env.MONGODB_URI, {
  serverSelectionTimeoutMS: 5000, // 服务选择超时5秒
  socketTimeoutMS: 45000,
})

加完配置后如果是连接问题会直接抛出明确错误，不会再无响应卡住，根据错误提示修复即可。

2. 修复SWC编译器兼容问题 #

Next 12版本默认启用SWC替代Babel做编译提速，部分系统环境下SWC会出现无响应挂起的bug，先修改next.config.js临时关闭SWC验证：

/** @type {import('next').NextConfig} */
const nextConfig = {
  swcMinify: false,
  experimental: {
    forceSwcTransforms: false,
  }
}
// 上面配置无效就加下面这行，完全切回Babel编译
// nextConfig.babel = { presets: ['next/babel'] }

module.exports = nextConfig

如果改完后能正常启动，说明是SWC和本地环境不兼容，要么把Next升级到12.x最新的补丁版本，要么把本地Node固定到16.x LTS版本即可解决。

3. 修复Node版本不兼容问题 #

Next 12.2.2官方兼容的Node版本范围是^14.18.0 || >=16.0.0，如果本地装了Node 18、20以上的大版本，会因为底层API不兼容导致进程挂起。
操作：

• 执行node -v查看当前本地Node版本，如果是18.x及以上，切换到16.x的LTS版本（推荐16.18.0、16.20.2）
• 可以在项目根目录新建.nvmrc文件，内容写16.20.2，之后执行nvm use就能自动切换到对应版本，避免后续版本混乱。

4. 修复监听地址/端口问题 #

部分系统下默认监听0.0.0.0:3000会因为IPv6优先级问题出现假启动，端口被占用时也可能无明确报错，直接指定监听地址和端口启动测试：

pnpm dev -H 127.0.0.1 -p 3001

如果这个命令能正常启动，把package.json里的dev脚本改成next dev -H 127.0.0.1即可，端口可以根据自己需求调整。

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