Next.js 11升级至Next.js 12后页面运行报错问题求助

架构老林

2026-8-30

Next.js 11升12运行时报错修复方案

按以下顺序操作即可解决：

先修核心依赖兼容问题
你安装的@wpengine/headless@0.6.3最高仅支持Next.js 11，和Next 12的运行时API存在兼容冲突，这是编译能通过、打开页面就报错的最常见诱因。直接升级到适配Next 12的版本即可：
```
npm i @wpengine/headless@^0.7.0
```
升级完成后对照版本变更调整下初始化参数就行，业务代码基本不需要改动。
移除冗余转译依赖、修正配置
Next.js 12原生内置了transpilePackages转译配置能力，不需要额外引入next-transpile-modules第三方包，先卸载该冗余依赖：
```
npm uninstall next-transpile-modules
```
打开项目根目录的next.config.js，删除之前包裹配置的withTM相关逻辑，把原来需要转译的包名直接写入原生支持的transpilePackages配置项即可，参考写法：
```
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 原有的sass配置、reactStrictMode等自定义配置全部保留
  transpilePackages: ['@wpengine/headless'] // 之前传给withTM的转译包列表挪到这里
}
module.exports = nextConfig
```
清理缓存后重启验证
上述修改完成后，删除项目根目录下的.next缓存文件夹、node_modules文件夹以及package-lock.json锁文件，重新执行依赖安装：
```
npm install
```
安装完成后重启开发服务，页面基本就能正常加载。
极端场景兼容处理
如果完成上述操作后仍报SWC相关编译错误，可以临时在next.config.js中添加如下配置，关闭SWC压缩回退到Terser验证问题：
```
const nextConfig = {
  // 其他原有配置保持不变
  swcMinify: false
}
```
你当前使用的React 17.0.2、TypeScript 4.3.2版本均满足Next.js 12.1.6的版本要求，不需要额外升级。