alias用于替换location匹配的url前缀，需末尾带/且location路径建议以/结尾，避免路径错位；不可与root混用，不适用于location /，正则中慎用，适用于url与物理路径名称不一致的映射场景。

在 location 块中使用 alias，核心是“替换前缀”，不是拼接路径。它把 location 匹配到的 URL 部分整个去掉，再把剩下的 URI 直接拼到 alias 指定的目录后面。

alias 的基本用法

必须满足两个硬性条件：

• alias 值末尾必须带 /（例如 /var/www/admin/，不能写成 /var/www/admin）
• location 路径建议以 / 结尾（例如 /admin/，不推荐 /admin）

否则容易因斜杠缺失导致路径错位，比如请求 /admin/js/app.js 变成 /var/www/adminjs/app.js —— 少一个斜杠就 404。

典型配置示例

假设磁盘上有 /opt/swagger-ui/index.html，你想通过 /api/docs/ 访问：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

location /api/docs/ {
    alias /opt/swagger-ui/;
}

这时：

• 请求 /api/docs/ → 查找 /opt/swagger-ui/index.html
• 请求 /api/docs/favicon.ico → 查找 /opt/swagger-ui/favicon.ico

/api/docs/ 这段被完全剥离，不参与路径构造。

常见错误与避坑点

• 不能和 root 混用：同一 location 块内同时出现 root 和 alias，Nginx 启动直接报错
• 不支持 location / 配合 alias：匹配所有请求时，alias 无法安全剥离前缀，应改用 root
• 正则 location 中慎用 alias：虽新版支持捕获变量（如 location ~ ^/static/(?<type>css|js)/(.*)$ { alias /data/assets/$type/$2; }</type>），但稳定性不如普通前缀匹配，生产环境优先选明确路径
• try_files 回退路径要带前缀：例如 try_files $uri $uri/ /admin/index.html; 中的 /admin/index.html 必须包含 /admin/，否则 Vue Router history 模式无法正确加载入口文件

什么时候该用 alias

当你需要把某个 URL 路径“映射”到一个物理路径，且两者名称不一致时：

• 挂载 Swagger UI：/api/v1/docs/ → /opt/swagger-ui/
• 部署子应用：/admin/ → /srv/my-admin/dist/
• 共享资源库：/assets/icons/ → /mnt/shared/icons/

只要 URL 前缀和磁盘目录名对不上，alias 就是更干净、更可控的选择。