Netlify集成Node.js后Swagger页面加载失败求助

问题根源 #

报错中的Unexpected token '<'表明请求swagger-ui-bundle.js等静态资源时，返回的不是JS文件而是HTML（大概率是API的404页面）。核心原因是：

1. Netlify的重定向规则将所有/api/*请求转发到Serverless函数，但Swagger UI的静态资源请求未被正确匹配到swagger-ui-express的服务逻辑
2. Express路由顺序不合理，导致Swagger的静态资源请求被后续API路由拦截

修复步骤 #

1. 调整Express路由顺序 #

将Swagger UI路由放在所有/api相关路由最前面，确保静态资源请求优先被匹配：

const app = express();

app.use(cors());
app.options('*', cors()); 

// 优先挂载Swagger UI路由
app.use('/api/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 再挂载其他API路由
const router = Router();
router.get('/hello', (req, res) => res.send('Hello World test v1!'));
app.use("/api", router);

// 后续中间件与路由
app.use((req, res, next) => {
    res.setHeader('Access-Control-Allow-Origin', '*');
    next();
});
app.use(express.json({ limit: '50mb' }));
app.use(express.urlencoded({ limit: '50mb' }));
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

app.use(uploadRoutes);
app.use('/api', fileRoutes);
app.use(upload.single('file'));
app.use('/api', userRoutes);
app.use('/api/auth', authRoutes);

2. 修改Netlify重定向规则 #

在netlify.toml中添加Swagger路径的优先匹配规则，避免静态资源请求被通用/api/*规则错误转发：

[functions]
  external_node_modules = ["express"]
  node_bundler = "esbuild"

# 优先匹配Swagger UI相关请求
[[redirects]]
  force = true
  from = "/api/api-docs/*"
  status = 200
  to = "/.netlify/functions/api/api-docs/:splat"

# 其他API请求转发规则
[[redirects]]
  force = true
  from = "/api/*"
  status = 200
  to = "/.netlify/functions/api/:splat"

3. 移除冗余依赖导入 #

swagger-ui-express已内置SwaggerUIBundle和SwaggerUIStandalonePreset，删除以下无效导入：

import SwaggerUIBundle from 'swagger-ui-dist/swagger-ui-bundle';
import SwaggerUIStandalonePreset from 'swagger-ui-dist/swagger-ui-standalone-preset';

4. 验证Swagger Spec有效性 #

确保config.swaggerDefinition和config.apiPaths配置正确，可在本地打印生成的Spec确认：

console.log(JSON.stringify(swaggerSpec, null, 2));

内容的提问来源于stack exchange，提问作者a.p. patel