ngx_http_random_index_module 是 Nginx 官方轻量模块，用于在目录请求中随机选取一个非隐藏常规文件作为索引页返回，需编译启用、配置在 location 块中且优先于 index 指令。
ngx_http_random_index_module 是 Nginx 官方提供的一个轻量模块，用于在请求目录（如 / 或 /images/）时，从该目录下**随机选取一个文件作为索引页返回**，替代默认的 `index` 指令的固定顺序匹配行为。它不依赖外部脚本，纯 C 实现，性能高，适合做简单 A/B 页面轮播、静态资源随机展示等场景。
启用模块并确认支持
该模块自 Nginx 0.7.22 起内置，但**默认不编译进大多数发行版二进制包**（如 Ubuntu apt 安装的 nginx-core）。需确认是否启用：
- 运行
nginx -V 2>&1 | grep -o with-http-random-index-module，若无输出，说明未启用 - Ubuntu/Debian 用户可安装
nginx-full（通常含该模块），或自行编译时添加--with-http-random-index-module - Alpine 用户可用
apk add nginx-mod-http-random-index并在配置中load_module modules/ngx_http_random_index_module.so;
基本配置语法与位置限制
random_index on; 必须放在 location 块中，且该 location 需满足两个前提：
- 匹配的是**目录路径**（以
/结尾，或 URI 本身对应一个真实目录） - 目录下存在至少一个普通文件（不能全是子目录或隐藏文件；
.和..会被跳过）
示例配置：
location /gallery/ {
alias /var/www/static/gallery/;
random_index on;
}
当访问 https://example.com/gallery/ 时，Nginx 会读取 /var/www/static/gallery/ 目录内容，随机挑选一个文件（如 beach.jpg、snow.png）返回，响应状态码为 200，响应体即该文件内容。
与 index 指令共存及行为差异
random_index 和 index 互斥：同一 location 中若同时存在，random_index on 优先生效，index 指令被忽略。
关键区别：
-
index a.html b.html：按顺序查找，找到第一个存在即返回 -
random_index on：扫描目录所有**非隐藏、非目录的常规文件**，等概率随机选一个返回（不关心扩展名） - 它不生成目录列表（不像
autoindex on），也不重写 URI，只是内部“假装”用户请求了那个随机文件
注意：若目录为空或只含子目录，Nginx 返回 403 Forbidden（因无合法候选文件）。
实用技巧与注意事项
-
控制候选范围：模块不支持过滤扩展名。如只想随机返回图片，需确保目录下只有
.jpg/.png等目标文件，其他文件（如README.txt）会参与随机 -
避免缓存干扰：浏览器或 CDN 可能缓存某次随机结果。可在响应头加
Cache-Control: no-cache（用add_header）或配合 ETag 使用 -
调试方法：开启
error_log /path/to/log debug;，观察日志中 “random index: picked file ‘xxx’” 类似条目 -
权限要求：Nginx worker 进程必须对目标目录有读取和执行（
x）权限，否则无法遍历目录内容
