Next.js 13中next-swagger-doc预渲染/api-doc页面失败求助

我用next-swagger-doc集成Swagger文档，本地能正常渲染使用，但在Docker容器或Vercel部署时构建失败，代码完全复刻自官方「Usage Case 1」。

渲染时出现如下警告：

- warn ./node_modules/swagger-jsdoc/src/utils.js
Critical dependency: the request of a dependency is an expression

Import trace for requested module:
./node_modules/swagger-jsdoc/src/utils.js
./node_modules/swagger-jsdoc/src/specification.js
./node_modules/swagger-jsdoc/src/lib.js
./node_modules/swagger-jsdoc/index.js
./node_modules/next-swagger-doc/dist/index.js
./swagger.ts
./app/api-doc/page.tsx

有两个疑问：

1. 我们使用Node 16，选择npm还是Yarn会有影响吗？
2. 如何解决部署时出现的TypeError？

完整错误日志：

41.42 TypeError: Class extends value undefined is not a constructor or null
41.42     at /app/.next/server/chunks/334.js:28855:816054
41.42     at /app/.next/server/chunks/334.js:28855:1386511
41.42     at /app/.next/server/chunks/334.js:28855:1386527
41.42     at webpackUniversalModuleDefinition (/app/.next/server/chunks/334.js:28855:70)
41.42     at Object.20404 (/app/.next/server/chunks/334.js:28855:76)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42     at Object.93670 (/app/.next/server/chunks/334.js:34301:69)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42     at Module.6054 (/app/.next/server/app/api-doc/page.js:336:74)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42 
41.42 Error occurred prerendering page "/api-doc". Read more: https://nextjs.org/docs/messages/prerender-error
41.42 TypeError: Class extends value undefined is not a constructor or null
41.42     at /app/.next/server/chunks/334.js:28855:816054
41.42     at /app/.next/server/chunks/334.js:28855:1386511
41.42     at /app/.next/server/chunks/334.js:28855:1386527
41.42     at webpackUniversalModuleDefinition (/app/.next/server/chunks/334.js:28855:70)
41.42     at Object.20404 (/app/.next/server/chunks/334.js:28855:76)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42     at Object.93670 (/app/.next/server/chunks/334.js:34301:69)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42     at Module.6054 (/app/.next/server/app/api-doc/page.js:336:74)
41.42     at __webpack_require__ (/app/.next/server/webpack-runtime.js:25:43)
41.42 - info Generating static pages (24/33)

1. Node 16下npm/Yarn的影响 #

包管理器本身（npm或Yarn）不会直接导致构建失败，但有两点需要注意：

• 依赖版本一致性：如果本地用Yarn、部署用npm（或反之），锁文件（yarn.lock/package-lock.json）不匹配会导致安装的依赖版本差异，可能触发兼容性问题。建议统一使用同一种包管理器，并提交锁文件到代码仓库，确保部署环境和本地依赖完全一致。
• Node 16兼容性：Node 16已进入维护期，next-swagger-doc的依赖（如swagger-jsdoc）新版本可能不再支持Node 16，这才是核心风险，和包管理器无关。

2. 解决TypeError的方案 #

这个错误是预渲染时类继承的父类未定义，结合swagger-jsdoc的动态依赖警告，本质是swagger-jsdoc在Next.js SSR/静态生成环境下的兼容性问题，可按以下步骤解决：

方案1：降级swagger-jsdoc版本 #

新版本的swagger-jsdoc（如v7+）可能依赖更高Node版本，或使用了Next.js打包不兼容的动态导入逻辑。降级到v6.x版本（比如6.2.8），执行命令：

# npm
npm install swagger-jsdoc@6.2.8 --save

# Yarn
yarn add swagger-jsdoc@6.2.8

方案2：禁用Swagger页面的SSR #

Swagger UI仅需客户端渲染，不需要预渲染。修改app/api-doc/page.tsx，用Next.js的dynamic导入禁用SSR：

import dynamic from 'next/dynamic';
import { getSwaggerDoc } from '../../swagger';

// 动态导入swagger-ui-react，禁用SSR
const SwaggerUI = dynamic(() => import('swagger-ui-react'), { ssr: false });

export default function APIDocPage() {
  const swaggerDoc = getSwaggerDoc();
  return <SwaggerUI spec={swaggerDoc} />;
}

方案3：升级Node版本（推荐） #

Node 16已停止维护，升级到Node 18或20（LTS版本），可解决大部分依赖兼容性问题，同时获得更好的性能和安全性。

方案4：确保部署环境依赖一致 #

提交package-lock.json或yarn.lock到代码仓库，部署时不要忽略锁文件，确保安装的依赖版本和本地完全一致，避免因依赖版本差异导致的构建失败。

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