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 | |
区别只在"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 | |
请求 /download/ 时,index 会做一次内部重定向:依次尝试 /download/index.html、/download/index.htm,找到即返回;都没有则交给后续处理(通常是 403 或 autoindex)。
要点:
index是"内部跳转",access_log记在最终 location;- 若索引文件本身要走代理或 PHP,需要用
try_files或error_page配合; - 默认
index index.html;。
三、autoindex:目录列表
1 | |
autoindex_exact_size off:用 K/M/G 人类可读单位;autoindex_localtime on:用本地时区显示时间;- 生产环境慎用:暴露目录结构,必要时配合
auth_basic或allow/deny。
四、Range 断点续传
Nginx 对静态文件原生支持 Range 请求(多线程下载、视频拖动),无需额外配置:
1 | |
- 单点请求返回 200,带
Range返回 206 Partial Content; If-Range用于校验文件是否变化(配合ETag/Last-Modified);- 若响应被
gzip压缩,Range 语义会被破坏——对大文件/视频不要开压缩; max_ranges可限制单次请求的分段数(防止滥用)。
五、secure_link:时效链接
私有文件(付费下载、限时预览)需要"链接过一段时间就失效"。ngx_http_secure_link_module 用哈希校验实现,不需要后端参与:
1 | |
- 客户端 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 |
| 对大文件开 gzip | Range 语义被破坏,拖动/续传失效 |
secure_link 表达式两端不一致 | 签发与校验算法必须完全相同 |
secure_link 不绑 IP | 链接可被随意转发,按需把 $remote_addr 加入表达式 |
| 目录列表暴露 | autoindex on 需配访问控制 |
参考链接
- Nginx 官方文档:ngx_http_core_module(root / alias) —— 路径拼接语义;
- Nginx 官方文档:ngx_http_index_module —— 索引与内部重定向;
- Nginx 官方文档:ngx_http_autoindex_module —— 目录列表;
- Nginx 官方文档:ngx_http_secure_link_module —— 时效链接与签发示例;
- 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
