Nginx 中用 alias 托管 API 文档需完全替换 location 路径，如 location /api-docs/ { alias /var/www/swagger-ui/; }，避免 root 的路径拼接问题；注意末尾斜杠一致性、权限配置、base href 修改及 SPA 路由支持。
在 Nginx 中用 alias 托管 API 文档（如 Swagger UI、Redoc 或自托管的 HTML 文档），关键在于让请求路径与本地文件系统路径正确映射，避免 root 指令常见的路径拼接问题。
理解 alias 与 root 的核心区别
alias 是**完全替换匹配的 location 路径部分**，直接指向目标目录；而 root 是在路径末尾**追加**请求 URI。托管 API 文档时，若用 root 容易导致 404（比如请求 /docs/ 却去查 /var/www/docs//index.html）。
-
location /docs/ { alias /var/www/api-docs/; }→ 请求/docs/index.html对应文件/var/www/api-docs/index.html -
location /docs/ { root /var/www; }→ 请求/docs/index.html对应文件/var/www/docs/index.html
配置 alias 托管 Swagger UI 示例
假设你已将 Swagger UI 文件解压到 /var/www/swagger-ui/（含 index.html、swagger-ui-bundle.js 等），希望通过 /api-docs/ 访问：
location /api-docs/ {
alias /var/www/swagger-ui/;
index index.html;
try_files $uri $uri/ /api-docs/index.html;
}
说明：
- 末尾斜杠
/必须与location和alias路径保持一致（alias值末尾有斜杠，表示它是一个目录） -
try_files支持单页应用（SPA）式路由，确保前端路由（如/api-docs/?url=...）也能正确加载index.html - 无需额外配置 MIME 类型，Nginx 默认支持
.html、.js、.css等
常见坑点与修复建议
配置后出现 403（Forbidden）或 404，大概率是权限或路径问题：
-
403 Forbidden：检查
/var/www/swagger-ui/目录是否对 Nginx 工作用户（如www-data或nginx）可读，执行sudo chmod -R 755 /var/www/swagger-ui并确认属主 -
404 Not Found：确认
alias路径末尾斜杠与location严格匹配；用ls -l /var/www/swagger-ui/index.html验证文件真实存在 -
CSS/JS 加载失败：打开浏览器开发者工具查看 Network 标签，确认资源请求路径是否正确（应为
/api-docs/swagger-ui.css，而非/swagger-ui.css）；若文档中硬编码了根路径，需修改其index.html中的<base href="/">为<base href="/api-docs/">
配合 API 后端的反向代理场景
如果文档中需要调用实际 API（如 https://api.example.com/v1），通常无需 Nginx 参与；但若想统一域名下调试，可为 API 单独配 proxy_pass：
location /api/ {
proxy_pass https://backend-api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
注意：/api/ 与 /api-docs/ 是两个独立 location，互不影响。Swagger UI 中的 url 字段仍填完整后端地址即可。
