alias不是虚拟目录替代，而是路径映射机制；其与PHP配合出错主因是未重设SCRIPT_FILENAME，导致PHP-FPM加载错误路径而404或空白页。
alias 在 Nginx 中不是“虚拟目录”的等价替代，它只是路径映射的重写机制；用错场景会直接导致 PHP 文件 404 或空白页——尤其当你试图用 alias 挂载含 PHP 脚本的子路径时。
为什么 alias + PHP 脚本常出 404 或 502
根本原因在于：alias 不改变 $document_root，但 PHP-FPM 的 SCRIPT_FILENAME 默认依赖 $document_root 构造。当 location /api/ { alias /var/www/api/; } 时，请求 /api/index.php 实际映射到 /var/www/api/index.php，但 Nginx 若未显式重设 fastcgi_param SCRIPT_FILENAME，PHP-FPM 仍会尝试加载 $document_root/api/index.php（即错误路径）。
- 现象：返回 404、空白页，或 error log 中出现
Primary script unknown - 关键点：
alias后的路径必须与fastcgi_param SCRIPT_FILENAME手动拼接一致 - 不能复用
root下的通用fastcgi-php.conf片段，必须单独覆盖SCRIPT_FILENAME
正确配置 alias + PHP 的 location 块
以 /admin/ → /opt/app/admin/ 为例，且该目录下有 index.php：
location /admin/ {
alias /opt/app/admin/;
index index.php;
<pre class="brush:php;toolbar:false;">location ~ \.php$ {
# 必须显式设置 SCRIPT_FILENAME，用 $request_filename 替代 $document_root
fastcgi_param SCRIPT_FILENAME $request_filename;
# 其他 fastcgi 参数保持标准
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
# 防止路径穿越（可选但推荐）
fastcgi_intercept_errors on;
}}
PHP 8.5.12 RC 1
下载
PHP 8.5.12 RC 1 候选版修复 BZ2、DOM、PDO、Opcache/JIT 和扩展内存安全问题，改进 Unicode 字素处理、URL 解析、TLS 流状态、信号分发及会话错误处理。
立即学习“PHP免费学习笔记（深入）”；
-
$request_filename是 Nginx 内部变量，表示磁盘上最终解析出的完整文件路径，它已受alias影响，因此安全可靠 - 不要用
$document_root$fastcgi_script_name—— 这是root模式下的写法，alias下会错位 - 注意末尾斜杠：
alias值和location路径都带斜杠，否则路径拼接会出错（如alias /path+location /a→/patha/file.php）
alias 和 root 的选择边界在哪
简单判断原则：
- 用
root：整个站点根目录统一，子路径只是 URL 前缀（如/blog/对应/var/www/blog/），且你希望复用全局index、try_files等逻辑 - 用
alias：某个 URL 路径需要**完全跳转到另一个物理位置**，且该位置与主root无关（如把/static/映射到/mnt/nas/assets/，或/legacy/指向旧系统部署目录） - PHP 场景优先选
root：绝大多数后台管理、API 子服务，其实更适合用独立server块或location+root，更可控、不易出错
真正容易被忽略的是：alias 下的 PHP 请求，Nginx 不会自动继承外层 location 的 index 指令行为——你必须在嵌套的 location ~ \.php$ 外再包一层非正则 location 来触发 index 和 try_files，否则 /admin/ 访问会直接 403 或 404，连 index.php 都不会自动补全。
