Nginx中alias映射PHP路径时文件被下载的根本原因是SCRIPT_FILENAME未正确拼接为绝对路径；必须手动设置fastcgi_param SCRIPT_FILENAME为磁盘绝对路径，如/var/www/app/api/$1，而非依赖$document_root。
在 Nginx 中使用 alias 指令映射 PHP 脚本路径时，常见问题是 PHP 文件被直接下载而非执行——根本原因在于 alias 与 fastcgi_param SCRIPT_FILENAME 的路径拼接逻辑不匹配，导致 PHP-FPM 无法定位真实文件。
alias 与 root 的关键区别
alias 是“替换整个 location 路径”，而 root 是“拼接路径”。例如：
-
location /static/ { alias /data/assets/; }→ 请求/static/logo.png对应磁盘路径/data/assets/logo.png -
location /static/ { root /data; }→ 同样请求对应/data/static/logo.png
对 PHP 处理而言，alias 下的 SCRIPT_FILENAME 必须显式构造为磁盘绝对路径，不能依赖 $document_root$fastcgi_script_name（该写法只适用于 root）。
正确配置 fastcgi_param SCRIPT_FILENAME
当使用 alias 时，必须手动拼出 PHP 文件的完整物理路径。假设：
立即学习“PHP免费学习笔记（深入）”；
location ~ ^/api/(.+\.php)$ { alias /var/www/app/api/; }- 请求为
/api/v1/user.php
则需将 $1（即 v1/user.php）拼接到 alias 目录后：
location ~ ^/api/(.+\.php)$ {
alias /var/www/app/api/;
include fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME /var/www/app/api/$1;
fastcgi_param SCRIPT_NAME /api/$1;
}
⚠️ 注意：SCRIPT_NAME 应保持 URI 路径结构（如 /api/v1/user.php），供 PHP 脚本内部识别路由；SCRIPT_FILENAME 必须是磁盘绝对路径。
避免常见权限与安全陷阱
即使路径拼接正确，仍可能因权限或配置疏漏失败：
-
PHP-FPM 进程用户需有读取 alias 目录的权限：检查
ls -ld /var/www/app/api/及其父目录，确保运行 PHP-FPM 的用户（如www-data）可遍历（x 权限）和读取（r 权限） -
禁用 auto_prepend_file 或 open_basedir 限制：若 PHP 配置了
open_basedir，需包含/var/www/app/api/；否则报 “No input file specified” -
不要混用 alias 和 try_files：alias 块内慎用
try_files $uri =404，它可能干扰 fastcgi 路由；PHP 脚本应由正则 location 精确捕获
调试技巧：快速验证路径是否正确
在 fastcgi_params 后临时添加：
fastcgi_param DEBUG_URI $uri; fastcgi_param DEBUG_FASTCGI_SCRIPT_NAME $fastcgi_script_name; fastcgi_param DEBUG_SCRIPT_FILENAME $script_filename;
再在 PHP 脚本中打印：var_dump($_SERVER['SCRIPT_FILENAME'], $_SERVER['SCRIPT_NAME']);，确认输出的是预期的磁盘路径和 URI 路径。
核心就一条：alias 下没有隐含的 document_root，SCRIPT_FILENAME 必须手动生成，且严格对应文件系统路径。配错一个斜杠或少一个目录层级，就会触发下载或 404。
