Swagger UI 在 Vercel 部署时的样式加载问题解决方案

问题背景

在使用 Node.js 应用程序部署到 Vercel 平台时，许多开发者遇到了 Swagger UI 界面显示为空白的问题。这是一个常见的技术挑战，主要原因是 Vercel 的特殊部署环境导致 Swagger UI 所需的 CSS 和 JavaScript 资源无法正确加载。

问题分析

Swagger UI 是一个流行的 API 文档工具，它依赖于特定的样式表(CSS)和脚本文件(JS)来渲染界面。当部署到 Vercel 时，这些静态资源可能由于以下原因无法正常加载：

1. 路径解析问题：Vercel 的路由机制可能导致资源请求被重定向或拦截
2. 内容分发网络访问限制：某些部署配置可能阻止了对公共内容分发网络资源的访问
3. 缓存策略：Vercel 的边缘缓存可能导致资源更新不及时

解决方案

方法一：直接引入内容分发网络资源

对于 Express 应用，可以通过修改 Swagger UI 的配置，直接引用公共内容分发网络上的资源：

const swaggerOptions = {
  customCssUrl: 'https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui.min.css',
  customJs: [
    'https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-bundle.min.js',
    'https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-standalone-preset.min.js'
  ]
};

方法二：配置 Vercel 路由规则

对于 Nest.js 或其他框架的应用，可以通过修改 vercel.json 配置文件，添加特定的路由规则：

{
  "routes": [
    {
      "src": "/api/swagger-ui.css",
      "dest": "https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui.min.css"
    },
    {
      "src": "/api/swagger-ui-bundle.js",
      "dest": "https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-bundle.min.js"
    },
    {
      "src": "/api/swagger-ui-standalone-preset.js",
      "dest": "https://cdnjs.example.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-standalone-preset.min.js"
    }
  ]
}

技术原理

这两种解决方案的核心思想都是确保 Swagger UI 能够访问到它所需的静态资源。Vercel 作为无服务器平台，有其独特的资源加载机制：

1. 内容分发网络直连方案：绕过本地资源加载，直接从公共内容分发网络获取所需文件，确保资源可用性
2. 路由重定向方案：利用 Vercel 的路由功能，将特定路径的请求转发到正确的资源地址

最佳实践建议

1. 版本锁定：在使用内容分发网络资源时，建议锁定特定版本，避免因自动更新导致兼容性问题
2. 本地测试：在部署前，先在本地测试 Swagger UI 的显示效果
3. 缓存控制：考虑添加适当的缓存头，平衡加载速度和更新需求
4. 安全考虑：确保使用的内容分发网络是可信来源，避免引入安全风险

总结

在 Vercel 上部署包含 Swagger UI 的应用时，资源加载问题是一个常见但容易解决的挑战。通过理解 Vercel 的路由机制和资源加载原理，开发者可以灵活选择最适合自己项目的解决方案。无论是直接配置内容分发网络链接还是通过路由重定向，都能有效解决 Swagger UI 显示空白的问题。