linux swagger为何乱码

在 Linux 下 Swagger 页面出现乱码，通常不是 Swagger 本身的问题，而是字符编码、HTTP 响应头或文件本身编码不一致导致的。下面按常见原因给你逐一排查。

一、最常见原因：字符编码不一致（UTF‑8）

1️⃣ Swagger UI 页面是 UTF‑8，但后端返回了其他编码

现象

接口说明、中文注释变问号 ???
或显示成 çç 这种乱码

原因

Java / Spring Boot 默认 UTF‑8，但 Linux 环境中：
- LANG 不是 UTF‑8
- Tomcat / Jetty 未指定 UTF‑8
- 返回 JSON 时 Content-Type 没带 charset=utf-8

解决

✅ 检查 Linux 语言环境

locale

如果不是 UTF-8，建议设置：

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

✅ Spring Boot 示例（强制 UTF‑8）

server:
  tomcat:
    uri-encoding: UTF-8
spring:
  http:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

二、Swagger JSON 本身是乱码

2️⃣ 接口返回的 JSON 已乱码

打开浏览器开发者工具 → Network → 找到 swagger-resources 或 /v2/api-docs

如果这里已经乱码，说明问题在后端序列化，不是 Swagger UI。

常见原因

接口返回 ISO-8859-1
使用了 StringHttpMessageConverter 且未指定 UTF‑8

✅ Spring MVC 解决方式

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        StringHttpMessageConverter converter =
                new StringHttpMessageConverter(StandardCharsets.UTF_8);
        converters.add(0, converter);
    }
}

三、Swagger UI 静态资源编码问题

3️⃣ Swagger UI 被反向代理（Nginx / 网关）

现象

页面标题、按钮正常
接口描述、说明乱码

原因

Nginx 未指定 charset
gzip + 编码不一致

✅ Nginx 配置

charset utf-8;

location / {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header Accept-Encoding "";
}

四、YAML / JSON 文件本身编码错误

4️⃣ Swagger 文件不是 UTF‑8

如果你用的是 swagger.yaml 或 openapi.yaml：

file swagger.yaml

如果是：

ISO-8859 text

✅ 转换为 UTF‑8：

iconv -f ISO-8859-1 -t UTF-8 swagger.yaml -o swagger_utf8.yaml

五、Docker 场景（非常常见）

5️⃣ Docker 容器默认 locale 是 POSIX

现象

本地正常
Docker 里乱码

✅ Dockerfile 示例

ENV LANG=en_US.UTF-8
ENV LC_ALL=en_US.UTF-8

或在 docker run 时：

docker run -e LANG=en_US.UTF-8 ...

六、快速自检清单 ✅

你可以按顺序检查：

✅ locale 是否为 UTF‑8
✅ /v2/api-docs 是否 UTF‑8
✅ Content-Type: application/json; charset=utf-8
✅ Nginx / 网关是否指定 charset
✅ 文件本身是否 UTF‑8
✅ Docker 是否设置 locale

七、如果你愿意，我可以直接帮你定位

你可以贴出：

✅ 使用的 Swagger 版本（Swagger2 / OpenAPI3）
✅ 后端语言（Java / Go / Node / Python）
✅ 是否使用 Docker / Nginx
✅ 一张乱码截图或示例 JSON

我可以直接给你精确到配置项的解决方案。