Linux运行Swagger出错咋办

在 Linux 上运行 Swagger 出错 可能原因很多，下面按最常见场景给你一个排查思路。你可以对照看看，也可以把具体报错贴出来，我帮你精确定位。

一、先确认你用的是哪种 Swagger

常见有 3 种：

1. Swagger UI（前端）
2. Swagger Editor
3. Spring Boot / Java 项目集成 Swagger（springfox / springdoc-openapi）
4. Node.js 项目用 swagger-jsdoc / swagger-ui-express

不同情况，解决方法不一样。

二、常见问题 & 解决方案

✅ 1. 端口被占用（最常见）

报错示例：

EADDRINUSE: address already in use :::8080

解决：

# 查看端口占用
lsof -i:8080

# 杀掉进程
kill -9 PID

或换个端口：

java -jar swagger.jar --server.port=9090

✅ 2. Java 环境没装 / 版本不对

报错示例：

java: command not found

解决：

java -version

如果没有 Java：

# Ubuntu / Debian
sudo apt update
sudo apt install openjdk-17-jdk

# CentOS
sudo yum install java-17-openjdk

⚠ Swagger 2.x 推荐 Java 8–17

✅ 3. 权限不足

报错示例：

Permission denied

解决：

chmod +x swagger.jar
# 或
sudo ./swagger

✅ 4. Swagger UI 页面打不开（404 / 白屏）

可能原因：

• 路径不对
• 静态资源没加载

Spring Boot 常见正确路径：

http://localhost:8080/swagger-ui.html
或
http://localhost:8080/swagger-ui/index.html

如果是 springdoc-openapi：

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

✅ 5. Linux 防火墙拦截

现象：

• 本地能访问
• 其他机器访问不了

解决：

# 查看防火墙
sudo ufw status

# 开放端口
sudo ufw allow 8080

或 CentOS：

firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

✅ 6. Node.js 项目 Swagger 报错

报错示例：

Cannot find module 'swagger-ui-express'

解决：

rm -rf node_modules package-lock.json
npm install

✅ 7. Docker 运行 Swagger 出错

报错示例：

docker: command not found

解决：

docker ps
docker logs 容器ID

或使用：

docker run -p 8080:8080 swaggerapi/swagger-ui

三、快速定位（你可以直接照做）

请直接把下面信息发我，我能立刻判断：

1. ✅ Linux 发行版

cat /etc/os-release

2. ✅ Swagger 类型

• Spring Boot？
• 单独 Swagger UI？
• Docker？

3. ✅ 完整报错信息 （复制终端里的错误）

四、一句话总结

Linux 上 Swagger 出错，90% 是 Java / 端口 / 权限 / 防火墙问题。

你可以直接贴报错，我帮你一步步修 ✅