debian swagger为啥报错

“Debian 上 Swagger 报错”这个范围比较广，因为 Swagger 本身不是 Debian 的一个软件包，而是通常在 Web 项目（Spring Boot / Node / Python 等）里集成使用的。
所以报错原因通常和 运行环境、依赖、配置、权限 有关，而不是 Debian 本身。

下面我按最常见情况帮你梳理一下：

一、常见报错原因汇总（Debian 场景）

1️⃣ Java / Spring Boot + Swagger 报错

这是最常见的一类。

典型报错：

• Failed to start bean 'documentationPluginsBootstrapper'
• Unable to infer base url
• No mapping for GET /swagger-ui.html
• 404 swagger-ui

常见原因：

• Swagger 版本与 Spring Boot 版本不兼容
  • Spring Boot 3 ❌ springfox-swagger2（已废弃）
  • Spring Boot 3 ✅ springdoc-openapi
• 缺少 @EnableSwagger2 或配置类
• 安全框架（Spring Security）拦截了 /swagger-ui/**

解决办法：

• Spring Boot 2：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>3.0.0</version>
</dependency>

• Spring Boot 3（推荐）：

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

访问：

/swagger-ui/index.html

2️⃣ Debian 上端口 / 防火墙问题

Swagger 能启动，但浏览器打不开。

检查：

curl http://localhost:8080/swagger-ui.html

如果 curl 能通，浏览器不行：

• 防火墙

sudo ufw status

• 云服务器安全组
• 只监听了 127.0.0.1

3️⃣ Node.js + Swagger UI Express 报错

典型报错：

• Cannot find module 'swagger-ui-express'
• EACCES: permission denied

原因：

• 没装依赖
• npm 全局权限问题（Debian 常见）

解决：

sudo npm install -g npm
npm install swagger-ui-express

建议不要 sudo npm install

4️⃣ Python（FastAPI / Flask + Swagger）

FastAPI 自带 Swagger：

/docs

常见报错：

• 打不开 /docs
• JS 加载失败

原因：

• Nginx 没代理静态资源
• Debian 上用了反向代理但配置不全

5️⃣ 权限 / 路径问题（Debian 特有）

• /tmp 权限异常
• 项目在 /root 下运行（不推荐）
• systemd 服务用户无权限

二、请你补充信息，我可以精准定位

你可以直接告诉我：

1. Swagger 用在什么项目？
   • Spring Boot / Node / Python / 其他
2. Debian 版本

   cat /etc/os-release
   

3. 完整报错信息（最重要）
4. 访问地址
   • http://ip:port/swagger-ui.html？

如果你愿意，把报错日志直接贴出来，我可以直接告诉你哪一行错了、怎么改。