部署在Vercel上的NestJS Swagger UI显示空白页求助

问题描述 #

本地localhost和AWS EC2服务器上，NestJS的Swagger UI均可正常显示，但部署到Vercel后，/swagger路径仅显示完全空白的页面（非CSS加载失败导致的样式异常）。相同代码仓库部署到其他环境均正常，仅Vercel出现该问题。

技术栈 #

• 主框架：NestJS
• @nestjs/swagger版本：7.0.3
• Node.js版本：18.17.0

已尝试方案 #

• 更新@nestjs/swagger版本无效
• 部署到AWS EC2等环境可正常运行，Vercel环境问题依旧

解决思路 #

• 检查Swagger环境开启逻辑：Vercel默认将NODE_ENV设为production，部分项目会在生产环境关闭Swagger。确认main.ts中是否强制开启Swagger，不受环境影响：

  const config = new DocumentBuilder()
    .setTitle('API Docs')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  // 强制挂载Swagger UI，忽略环境判断
  SwaggerModule.setup('swagger', app, document);
  

• 配置Vercel路由重写：Vercel的Serverless环境下，静态资源路径可能无法正确映射。在项目根目录创建vercel.json，添加路由规则确保Swagger相关请求转发到NestJS入口：

  {
    "rewrites": [
      { "source": "/swagger(.*)", "destination": "/api" }
    ]
  }
  

  注：如果你的NestJS在Vercel上的函数路径是/api，需对应调整destination的值。

• 设置Swagger的basePath：若Vercel部署后存在路径前缀（如自定义域名下的子路径），需在Swagger配置中指定basePath，确保静态资源请求路径正确：

  const config = new DocumentBuilder()
    .setTitle('API Docs')
    .setVersion('1.0')
    .setBasePath('/api') // 匹配Vercel的函数路径前缀
    .build();
  

• 查看Vercel函数日志：在Vercel控制台的「函数」板块，查看/swagger路径的请求日志，确认是否存在404、500等错误，或静态资源加载失败的异常信息，定位具体问题。

• 确认Vercel部署适配器配置：如果使用@vercel/node部署NestJS，需确保正确导出handler，且所有路由（包括Swagger的静态资源路由）都能被正确处理。例如：

  // main.ts
  export const handler = app.getHttpAdapter().getInstance();
  

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