1. SpringDoc OpenAPI UI与Nginx反向代理的那些坑最近在项目里用SpringDoc OpenAPI UI做接口文档本地测试一切正常结果上了Nginx反向代理就疯狂报404。这应该是很多开发者都会遇到的经典问题——明明本地能访问/v3/api-docs怎么通过Nginx就加载不了Swagger UI了先说几个常见症状浏览器控制台报Failed to load remote configuration查看网络请求发现/v3/api-docs接口返回404Swagger UI页面能打开但接口文档加载失败我用的环境是Spring Boot 2.6.13 SpringDoc OpenAPI UI 1.6.15Nginx版本是1.18。这个问题其实和版本关系不大核心在于反向代理的路径处理。下面我就把踩坑经历和解决方案详细分享给大家。2. 问题根源分析2.1 为什么本地能访问而Nginx不行本地直接访问Spring Boot应用时请求路径是这样的http://localhost:8080/v3/api-docs但通过Nginx代理后请求路径可能变成http://your-domain.com/your-context/v3/api-docs这里的关键点在于Nginx默认不会转发原始请求路径SpringDoc根据请求头中的Host和X-Forwarded-*头来构建文档链接如果缺少必要的代理头SpringDoc会生成错误的文档URL2.2 反向代理的常见配置错误我见过最多的错误配置是这种location /api/ { proxy_pass http://localhost:8080/; }这种配置会导致请求/api/v3/api-docs被转发到/v3/api-docs但SpringDoc生成的文档链接仍然是/api/v3/api-docs最终形成死循环3. 完整解决方案3.1 Spring Boot应用配置首先要在application.yml中添加server: forward-headers-strategy: framework这个配置的作用是让Spring Boot自动处理X-Forwarded-*头适用于Spring Boot 2.6.x及以上版本不需要额外引入依赖3.2 Nginx正确配置姿势完整的Nginx配置应该是这样location /your-context/ { proxy_pass http://localhost:8080/; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Prefix /your-context; }关键点说明X-Forwarded-Prefix必须与location匹配所有代理头都要正确设置结尾的/不能省略3.3 验证配置是否生效可以通过curl测试curl -v http://your-domain.com/your-context/v3/api-docs检查响应头中是否包含X-Forwarded-Prefix: /your-context4. 高级场景处理4.1 多级路径代理如果需要代理多级路径比如/prefix1/prefix2/api配置应该是location /prefix1/prefix2/api/ { proxy_pass http://localhost:8080/; proxy_set_header X-Forwarded-Prefix /prefix1/prefix2/api; }4.2 HTTPS特殊处理如果使用HTTPS需要确保proxy_set_header X-Forwarded-Proto https;4.3 自定义OpenAPI路径如果想修改默认的/v3/api-docs路径可以在Spring Boot中配置springdoc: api-docs: path: /custom-api-docs对应的Nginx配置也要同步修改。5. 常见问题排查5.1 仍然报404怎么办按这个顺序检查直接访问后端服务http://localhost:8080/v3/api-docs是否正常检查Nginx日志error.log是否有报错使用curl测试代理路径是否正确检查响应头是否包含X-Forwarded-*系列头5.2 Swagger UI加载失败如果Swagger UI页面能打开但文档加载失败检查浏览器控制台报错查看网络请求的URL是否正确确认没有跨域问题5.3 性能优化建议对于生产环境建议启用Nginx缓存限制/v3/api-docs的访问频率考虑使用静态文档导出功能6. 最佳实践总结经过多次实践我总结出几个关键点始终设置forward-headers-strategy: frameworkNginx配置中必须包含X-Forwarded-Prefix代理路径的/要特别注意测试时先直接用后端地址验证最后分享一个我常用的完整配置模板location ~ ^/api(/.*)?$ { proxy_pass http://backend:8080$1$is_args$args; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Prefix /api; }这个配置可以处理大多数场景包括带查询参数的请求。在实际项目中根据这个模板调整基本都能解决问题。