Nginx 工程实践 -- 17. 静态服务进阶:root/alias、index 与 secure_link

第 1 篇用 root + try_files 搭了最基础的静态服务。真实项目里,目录映射、默认索引、断点续传、防盗链之外的时效链接,都是围绕静态文件展开的高频需求。这篇把 root/alias 的替换语义讲透,再补上 index、autoindex、Range 续传和 secure_link 四块。

flowchart TD
    A["请求 /img/logo.png"] --> B{"root 还是 alias"}
    B -->|"root /var/www"| C["/var/www/img/logo.png"]
    B -->|"alias /var/www/img/"| D["/var/www/img/logo.png"]
    A2["请求目录 /download/"] --> E{"index 命中?"}
    E -->|"是"| F["内部重定向到索引文件"]
    E -->|"否"| G["autoindex 或 403"]
    H["Range 请求"] --> I["206 分段返回"]
    J["带签名 URL"] --> K{"secure_link 校验"}
    K -->|"通过"| L["放行"]
    K -->|"过期/错误"| M["403"]

一、root 与 alias 的替换语义

1
2
3
4
5
6
7
8
9
location /img/ {
root /var/www;
# 请求 /img/logo.png -> /var/www/img/logo.png
}

location /img/ {
alias /var/www/img/;
# 请求 /img/logo.png -> /var/www/img/logo.png
}

区别只在"location 前缀怎么处理":

  • root:把 root 的值整段拼在 URI 前面,location 前缀保留;
  • alias:把 URI 中匹配 location 的那部分替换成 alias 的值。

因此 alias 必须与 location 前缀对应,且通常两个都写尾斜杠。写错的表现是 404 或路径多一层。

易错点:

  • alias 用于精确前缀时,location 最好也精确(location = /img/)或写全路径;
  • 正则 location 中 alias 不能引用捕获变量(与 proxy_pass 限制类似);
  • alias 指向目录时,若 URI 以 / 结尾,Nginx 会去找该目录的索引。

二、index 与内部重定向

1
2
3
4
location /download/ {
alias /var/www/files/;
index index.html index.htm;
}

请求 /download/ 时,index 会做一次内部重定向:依次尝试 /download/index.html、/download/index.htm,找到即返回;都没有则交给后续处理(通常是 403 或 autoindex)。

要点:

  • index 是"内部跳转",access_log 记在最终 location;
  • 若索引文件本身要走代理或 PHP,需要用 try_files 或 error_page 配合;
  • 默认 index index.html;。

三、autoindex:目录列表

1
2
3
4
5
6
location /files/ {
alias /var/www/files/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}
  • autoindex_exact_size off:用 K/M/G 人类可读单位;
  • autoindex_localtime on:用本地时区显示时间;
  • 生产环境慎用:暴露目录结构,必要时配合 auth_basic 或 allow/deny。

四、Range 断点续传

Nginx 对静态文件原生支持 Range 请求(多线程下载、视频拖动),无需额外配置:

1
2
3
4
5
location /media/ {
alias /var/www/media/;
# 默认即支持 Range / If-Range
add_header Accept-Ranges bytes;
}
  • 单点请求返回 200,带 Range 返回 206 Partial Content;
  • If-Range 用于校验文件是否变化(配合 ETag/Last-Modified);
  • 若响应被 gzip 压缩,Range 语义会被破坏——对大文件/视频不要开压缩;
  • max_ranges 可限制单次请求的分段数(防止滥用)。

五、secure_link:时效链接

私有文件(付费下载、限时预览)需要"链接过一段时间就失效"。ngx_http_secure_link_module 用哈希校验实现,不需要后端参与:

1
2
3
4
5
6
7
8
9
10
11
location /private/ {
alias /var/www/private/;

# 表达式:$secure_link_md5 = base64(md5(URI + 过期时间 + 密钥))
secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

# 校验失败返回 403
if ($secure_link = "") { return 403; }
# 已过期返回 403($secure_link 为 "0")
if ($secure_link = "0") { return 403; }
}
  • 客户端 URL 形如 /private/file.zip?md5=xxxx&expires=1700000000;
  • $secure_link_md5 表达式里可组合变量(URI、过期时间、客户端 IP、密钥),用 Base64 编码的 MD5;
  • 把 $remote_addr 放进表达式可做到"绑定 IP",防止链接被转发;
  • 签发端需要自己实现同一段哈希逻辑(官方文档给出了多种语言的示例)。

六、常见坑

坑说明
alias 与 root 混用语义不同,替换规则记错就 404
alias 末尾斜杠漏写路径拼接多一层或少一层
期望 index 跳转记在原 location内部重定向,日志记在最终 location
对大文件开 gzipRange 语义被破坏,拖动/续传失效
secure_link 表达式两端不一致签发与校验算法必须完全相同
secure_link 不绑 IP链接可被随意转发,按需把 $remote_addr 加入表达式
目录列表暴露autoindex on 需配访问控制

参考链接

  1. Nginx 官方文档:ngx_http_core_module(root / alias) —— 路径拼接语义;
  2. Nginx 官方文档:ngx_http_index_module —— 索引与内部重定向;
  3. Nginx 官方文档:ngx_http_autoindex_module —— 目录列表;
  4. Nginx 官方文档:ngx_http_secure_link_module —— 时效链接与签发示例;
  5. RFC 9110:Range 与条件请求。

小结

  • root 拼接、alias 替换,两者语义必须分清;
  • index 是内部重定向,日志记在最终 location;
  • Range 原生支持,但别对大文件开 gzip;
  • secure_link 用哈希实现时效链接,表达式里可绑定 IP;
  • autoindex 要配访问控制再上线。

系列导航


Nginx 工程实践 -- 17. 静态服务进阶:root/alias、index 与 secure_link
https://bubao.github.io/posts/b7c8d9e0.html
作者
一念
发布于
2026年11月21日
许可协议