alias指令通过完全替换location匹配的URL前缀实现精准路径映射，如location /api/docs/配alias /opt/swagger-ui/，则请求/api/docs/index.html对应文件/opt/swagger-ui/index.html；必须严格匹配末尾斜杠，且不支持正则捕获变量拼接。
直接用 alias 指令就能把某个 URL 路径映射到任意物理目录，不依赖网站根目录（root），关键在于理解它“替换前缀”的行为——不是追加，而是替代。
alias 的核心逻辑：用指定路径完全替换 location 前缀
当 Nginx 匹配到 location /api/docs/ 时，alias /opt/swagger-ui/; 表示：把请求 URI 中的 /api/docs/ 这一段整个去掉，剩下的路径直接拼到 /opt/swagger-ui/ 后面找文件。
比如请求 /api/docs/index.html → 实际读取 /opt/swagger-ui/index.html；
请求 /api/docs/v1/swagger.json → 实际读取 /opt/swagger-ui/v1/swagger.json。
这和 root 完全不同：root /opt/swagger-ui; 会去找 /opt/swagger-ui/api/docs/index.html，显然不对。
必须注意的末尾斜杠规则
alias 路径末尾的 / 和 location 路径末尾的 / 必须严格匹配，否则容易 404：
- 如果
location以/结尾（如location /static/ { ... }），那么alias也必须以/结尾（alias /var/www/assets/;） - 如果
location不以/结尾（如location /favicon.ico { ... }），alias就不能带尾部/，且需指向具体文件（alias /var/www/favicon.ico;）
错配会导致路径拼接错误。例如 location /static/ { alias /data/files; }（缺尾斜杠）→ 请求 /static/logo.png 会去找 /data/fileslogo.png，而不是 /data/files/logo.png。
多级路径与正则 location 的配合要点
正则表达式 location（如 location ~ ^/api/v\d+/docs/）中使用 alias 时，alias 本身不支持捕获变量拼接。也就是说，下面写法是无效的：
location ~ ^/api/(?<version>v\d+)/docs/ { alias /opt/swagger-ui/$version/; }</version>
正确做法有两种：
- 用
rewrite提前重写 URI，再配合普通alias（推荐） - 改用
try_files+alias组合，或转向root+ 目录结构对齐
例如，想把 /api/v2/docs/ 映射到 /opt/swagger-ui/v2/，可先 rewrite：
location ~ ^/api/(?<v>v\d+)/docs/(.*)$ {<br> rewrite ^/api/.*/docs/(.*)$ /$v/$1 break;<br> alias /opt/swagger-ui/;<br>}
安全与调试建议
alias 易暴露非 web 根目录下的文件，务必限制范围：
- 避免使用
alias /;或模糊路径，始终用绝对路径 - 配合
internal;防止外部直接访问敏感映射（如日志、配置目录） - 启用
log_not_found on;，结合 error log 查看真实路径是否命中 - 测试时用
curl -I看响应头，确认返回的是预期文件而非 404 或 403
不复杂但容易忽略细节，理清“替换”而非“追加”，再盯住斜杠，基本就不会出错。
