NestJS Swagger UI在Android真机可加载但「Try it out」因CORS失败

环境配置 #

• 后端IP：192.168.1.5:3000（运行在MacBook）
• 测试设备：同Wi-Fi下的真实Android手机
• 当前状态：手机浏览器可正常打开Swagger文档 http://192.168.1.5:3000/api/docs

问题现象 #

在手机端Swagger UI点击接口（如/auth/login）的「Try it out」按钮时，请求失败，提示：

TypeError: Failed to fetch
Possible reasons: CORS, Network failure, or URL scheme must be http or https

但在Android模拟器中使用http://10.0.2.2:3000可正常调用接口。

当前配置 #

main.ts中的CORS配置 #

app.enableCors({
  origin: ['http://localhost:5175'], // My Vite frontend
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
});

await app.listen(3000, '0.0.0.0');

Swagger配置 #

const swaggerConfig = new DocumentBuilder()
  .setTitle('Liaison360 API')
  .addServer('http://localhost:3000', 'Local Development')
  .addServer('http://192.168.1.5:3000', 'Local Network')
  .build();

已尝试操作 #

• 确认手机与笔记本处于同一网络
• 确认后端监听0.0.0.0
• 确认端口未被防火墙拦截（Swagger页面可正常加载）

问题原因 #

浏览器加载Swagger页面属于静态资源请求，而点击「Try it out」发起的是跨域API请求，两者的CORS校验逻辑不同：

1. Swagger页面是直接从后端服务器获取的静态文件，不存在跨域问题；
2. 手机浏览器中Swagger页面的来源是http://192.168.1.5:3000/api/docs，但当前NestJS的CORS配置仅允许http://localhost:5175作为合法来源，因此浏览器会拦截该跨域请求。

解决方法 #

1. 更新CORS配置，允许Swagger页面的来源 #

修改main.ts中的CORS配置，将手机端Swagger页面的IP加入origin数组，或临时允许所有来源（仅限测试环境）：

方式一：指定允许的来源（推荐测试环境使用）

app.enableCors({
  origin: [
    'http://localhost:5175', // Vite前端
    'http://192.168.1.5:3000', // 手机端Swagger页面来源
  ],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
});

方式二：允许所有来源（仅临时测试用，生产环境禁用）

app.enableCors({
  origin: true, // 允许所有来源
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
});

2. 确认Swagger使用正确的服务器地址 #

在手机端打开Swagger页面后，选择顶部「Servers」下拉菜单中的http://192.168.1.5:3000（Local Network），避免使用localhost地址导致请求失败。

3. 验证配置生效 #

重启NestJS后端服务，在手机端重新打开Swagger文档，再次尝试调用接口即可正常请求。

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