新建Next.js应用报错：URL.canParse is not a function

问题详情 #

通过npx create-next-app@latest创建Next.js应用，使用版本14.2.11，执行npm run dev后触发以下错误：

Uncaught TypeError: URL.canParse is not a function
at getSocketUrl (webpack-internal:///(:3001/app-pages-browser)/./node_modules/next/dist/client/components/react-dev-overlay/internal/helpers/get-socket-url.js:23:13)

已尝试但无效的操作 #

• 执行npm update next react react-dom更新依赖
• 清除缓存：rm -rf .next
• 重启开发服务器：重新执行npm run dev

可行解决方案 #

1. 检查并升级Node.js版本 #

URL.canParse是ES2022新增的API，Next.js 14.2.11要求Node.js版本不低于18.17.0或20.6.0。执行以下命令查看当前版本：

node -v

若版本不符合要求，升级到对应LTS版本（推荐20.x系列）。

2. 重新安装依赖 #

删除现有依赖文件后重新安装，确保依赖版本匹配：

rm -rf node_modules package-lock.json
npm install

3. 临时禁用React Dev Overlay（应急方案） #

在项目根目录的next.config.js中添加以下配置，绕过错误触发点：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    reactDevOverlay: false,
  },
}

module.exports = nextConfig

注意：此为临时 workaround，优先通过升级Node.js解决根本问题。

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