Nginx中的$document_root是一个在请求处理阶段被赋值的内部变量，它代表当前请求所对应的文件系统根目录。很多开发者在写fastcgi_param或做访问控制时依赖它，但并不清楚它究竟从哪里来、为什么会随配置变化。
一、$document_root的本质来源
严格来说，$document_root并不是Nginx去磁盘上“探测”出来的，也不是像环境变量那样预先设定好的常量。它的值来源于配置文件中生效的root指令（或alias指令转换后的结果）。当Nginx收到一个HTTP请求，并根据server_name、location等规则匹配到具体的处理块时，就会确定该请求使用的root路径，随后把这个路径填入$document_root变量。
这意味着，如果同一个server下不同location设置了不同的root，那么用户访问不同URI时，$document_root就会动态变成对应location里的路径。例如图片目录单独指向/storage/img，而PHP脚本目录指向/var/www/html，两者取到的$document_root完全不同。这种“动态”本质上是配置匹配后的结果，而非运行期计算。
二、root与alias对$document_root的影响
使用root指令时，$document_root等于root指定的目录，请求的URI会直接拼接到该目录后面。比如root设为/var/www，访问/api/index.php，$document_root就是/var/www，最终文件路径为/var/www/api/index.php。此时$document_root在日志或fastcgi中均显示为/var/www。
而alias指令的行为不同，它会把location匹配到的URI部分替换成alias指定的路径。若location /static/ 对应 alias /data/assets/，访问/static/a.png，实际文件是/data/assets/a.png。在这种情况下，Nginx内部会将$document_root调整为alias对应的目录，以便后端或日志正确识别基础路径。但需注意alias结尾斜杠要与location保持一致，否则容易出现路径拼接异常。
三、继承规则与常见误区
当某个location没有明确写root时，它会向上继承server块甚至http块中的root设置。若server块写了root /var/www，location /x 没写root，那么访问/x时$document_root依旧是/var/www。只有在location自己定义了root或alias后，才会覆盖上层值。
一个典型误区是认为$document_root一定等于配置文件里写死的那个root。实际上在使用了正则location、内部重写（rewrite）或error_page跳转后，请求可能落入另一个location，此时$document_root随之改变。如果PHP的SCRIPT_FILENAME仍用写死的路径拼接，就可能找不到文件。正确写法应始终用$document_root而非固定字符串。
四、配置实例对比
下面用一个简单表格说明不同配置下$document_root的实际取值：
| 配置情况 | 请求URI | $document_root值 | 实际文件路径 |
|---|---|---|---|
| server root /var/www，无location root | /a.html | /var/www | /var/www/a.html |
| server root /var/www，location /img root /data | /img/b.png | /data | /data/b.png |
| location /up alias /opt/upload/ | /up/c.jpg | /opt/upload | /opt/upload/c.jpg |
从表中可以看出，$document_root完全取决于请求最终落到的处理块所使用的根路径指令。在调试Nginx时，可通过添加return 200 "$document_root";这类临时响应来观察不同URI下的值，从而确认配置是否符合预期。
五、在后端语言中的正确用法
以PHP-FPM为例，fastcgi_param脚本文件名通常应写为fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;。这样无论location如何切换根目录，PHP都能拿到正确的文件绝对路径。如果写成固定/var/www$fastcgi_script_name，一旦某个location root变了，就会报文件不存在错误。
同样在Lua或Perl模块中读取文件，也应优先用ngx.var.document_root获取当前请求根目录，而不是依赖外部全局变量。这种写法能天然适配多站点、多根目录的复杂Nginx架构，减少因路径硬编码引发的运维故障。
总结而言，$document_root的动态获取机制是Nginx配置匹配的自然产物。掌握root与alias的区别、继承逻辑以及后端传参方式，才能真正驾驭它。
Nginxdocument_root根目录配置修改时间：2026-08-11 13:51:32