Nginx Alias 映射多级子目录如何写

nginx的alias指令通过完全替换location匹配部分实现路径映射，需确保location与alias尾部斜杠一致，并手动对齐层级；多级子目录映射须精确配置location前缀和alias目标根目录，正则location中禁用alias，动态层级推荐root+try_files。

nginx 的 alias 指令本身不支持“自动拼接多级子目录”，它会完全替换 location 匹配的部分，所以写法关键在于：location 路径要精确匹配你希望暴露的 URL 前缀，而 alias 后面要写成对应的真实文件系统路径，且二者长度和层级需手动对齐。

理解 alias 的替换逻辑

alias 不是追加，而是“用后面的路径，替换掉 location 中已匹配的部分”。比如：

1. location /static/ → alias /var/www/assets/：访问 /static/js/app.js 实际读取 /var/www/assets/js/app.js
2. location /v1/api/ → alias /opt/backend/prod/：访问 /v1/api/users 实际读取 /opt/backend/prod/users

注意：location 末尾的斜杠必须和 alias 末尾斜杠保持一致（都带或都不带），否则容易出错。推荐统一带尾部斜杠。

映射多级子目录的正确写法

假设你想把 URL /app/v2/docs/guide.pdf 映射到磁盘路径 /srv/share/docs/v2/guide.pdf，核心是让 location 匹配前缀，alias 指向目标根目录：

location /app/v2/docs/ {alias /srv/share/docs/v2/;}

这样：

– 请求 /app/v2/docs/guide.pdf → 去掉 /app/v2/docs/ → 剩余 guide.pdf → 拼到 /srv/share/docs/v2/ → 得到 /srv/share/docs/v2/guide.pdf

如果想映射整个 /app/ 下所有多级结构（如 /app/v2/docs/、/app/v3/data/）到不同物理目录，不能只靠一个 alias，需要分层配置或改用 root + try_files。

避免常见错误

1. location 和 alias 尾部斜杠不一致：比如 location /data（无斜杠）配 alias /home/files/（有斜杠），会导致路径错位
2. 误用 root 替代 alias：root 是拼接，alias 是替换；root /a + location /b/ → 访问 /b/file 对应 /a/b/file；而 alias /a/ + location /b/ → 对应 /a/file
3. 正则 location 中混用 alias：nginx 最新文档明确说明，alias 在正则 location（~ 或 ~*）中行为不可靠，应避免

替代方案：用 root + try_files 处理动态层级

如果 URL 层级不确定（如 /api/v1/xxx、/api/v2/yyy），且后端目录结构与 URL 严格对应，用 root 更自然：

location /api/ {root /opt/services;try_files $uri =404;}

访问 /api/v1/users → 查找 /opt/services/api/v1/users。

若需重写路径再转发（比如去掉 /api/ 前缀），可用 rewrite 配合 proxy_pass，而非 alias。