为什么linux swagger失败

“Linux 下 Swagger 失败”这个现象很常见，但原因有很多种，需要看具体是哪种“Swagger”。下面我按最常见场景给你系统梳理一下原因 + 排查思路。

一、你说的是哪一种 Swagger？

1️⃣ Spring Boot + Swagger / Springdoc（最常见）

例如：

springfox-swagger2
springdoc-openapi

典型表现

访问 /swagger-ui.html 404
访问 /v3/api-docs 空白或 500
本地 Windows 能跑，Linux 服务器不行

二、Linux 下 Swagger 常见失败原因（重点）

✅ 1. 路径大小写问题（Linux 严格区分大小写）

❌ Windows：

/Swagger-ui.html
/swagger-ui.html

✅ Linux：必须完全一致

✅ 正确：

/swagger-ui.html
/v3/api-docs

✅ 2. 生产环境被 Spring Security 拦截

Linux 通常是 prod 环境

spring:
  profiles:
    active: prod

但没放行 Swagger：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
}

❌ 没配置 → 直接 401 / 403

✅ 3. Springfox 与 Spring Boot 2.6+ 不兼容（经典坑）

如果你用的是：

springfox-swagger2

而 Spring Boot ≥ 2.6：

❌ 会直接启动失败或 /v3/api-docs 报错

✅ 解决：

换成 springdoc-openapi

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

访问：

/swagger-ui.html

✅ 4. 容器 / Nginx 反向代理没转发

Linux 常配合 Nginx：

location / {
    proxy_pass http://127.0.0.1:8080;
}

但 Swagger 内部会请求：

/v3/api-docs

✅ 正确：

location / {
    proxy_pass http://127.0.0.1:8080/;
}

或显式放行：

location ~ ^/(swagger|v3|api-docs) {
    proxy_pass http://127.0.0.1:8080;
}

✅ 5. Docker 中端口 / 上下文路径问题

如果你在 Docker：

server:
  servlet:
    context-path: /api

那你访问的是：

/api/swagger-ui.html

而不是：

/swagger-ui.html

✅ 6. 启动参数关闭了 Swagger

常见“作死配置”：

@Profile("prod")
@Configuration
public class SwaggerConfig {}

或：

springdoc:
  api-docs:
    enabled: false

三、快速自查清单（Linux）

# 1. 看端口
netstat -tunlp | grep 8080

# 2. 看日志
journalctl -u your-service -f
# 或
docker logs -f container_id

# 3. 直接 curl
curl http://localhost:8080/v3/api-docs
curl http://localhost:8080/swagger-ui.html

四、你可以直接告诉我这些，我能精准定位

请补充：

Swagger 类型（springfox / springdoc）
Linux 是否 Docker / Nginx
报错信息（404 / 500 / 日志）
Spring Boot 版本

我可以直接给你可复制的配置。