NodeJS Swagger2.0部署服务器报错SwaggerUIBundle未定义，本地正常求排查

问题情况 #

基于Swagger 2.0的Node.js应用本地运行正常，但部署到服务器后出现加载错误，具体报错如下：

加载来自"https://myserver/api-docs/swagger-ui-bundle.js"的脚本失败。 api-docs:70:38
Components对象已废弃，即将被移除。
未捕获的引用错误: SwaggerUIBundle is not defined
    at onload (https://myserver/api-docs/swagger-ui-init.js:373)
    at EventHandlerNonNull* (https://myserver/api-docs/swagger-ui-init.js:2)

排查步骤 #

• 验证静态文件可访问性
  直接在浏览器访问https://myserver/api-docs/swagger-ui-bundle.js，如果返回404，说明swagger-ui-express的路由配置有问题，需检查是否正确挂载了Swagger UI的静态文件服务，是否存在路由前缀冲突。

• 检查服务器文件权限
  确认服务器上swagger-ui相关静态文件（如bundle.js、init.js等）的读取权限，保证Node.js进程能正常读取这些文件，避免因权限缺失导致加载失败。

• 核对反向代理配置
  如果服务器用了Nginx之类的反向代理，检查代理规则是否正确转发/api-docs路径的请求到Node.js应用。部分代理可能会误拦截静态文件请求，导致资源无法获取。

• 确认依赖完整性
  在服务器环境重新执行npm install或yarn install，确保swagger-ui-express及其依赖完全安装，避免部署时漏装依赖导致静态文件服务异常。

• 清除缓存测试
  清除浏览器缓存后重新访问，或者在服务器临时禁用静态文件缓存，排查是否因缓存了旧的错误路径导致加载失败。

• 检查CORS覆盖范围
  虽然已设置CORS为*，但要确认该配置是否覆盖了/api-docs下的静态文件请求。部分CORS中间件可能只对API接口生效，没覆盖静态文件路由，导致跨域拦截脚本加载。

内容的提问来源于stack exchange，提问作者M. Mariscal