Nginx 配置最佳实践：实现公共目录静态资源直通 + 全局 PHP 路由捕获-php教程-PHP中文网

Nginx 配置最佳实践：实现公共目录静态资源直通 + 全局 PHP 路由捕获

本文提供一种简洁、健壮的 Nginx 配置方案，通过 try_files 与命名 location（@fallback）协同工作，在保持 /public 为默认 root 的前提下，精准放行 CSS/JS 等静态资源和指定 PHP 文件（如 /test.php），并将其余所有请求统一交由 /private/routes.php 处理，彻底规避重复 root 定义与嵌套 PHP location 的陷阱。

本文提供一种简洁、健壮的 nginx 配置方案，通过 `try_files` 与命名 location（`@fallback`）协同工作，在保持 `/public` 为默认 root 的前提下，精准放行 css/js 等静态资源和指定 php 文件（如 `/test.php`），并将其余所有请求统一交由 `/private/routes.php` 处理，彻底规避重复 root 定义与嵌套 php location 的陷阱。

在构建现代 PHP 应用（如微框架或自定义路由系统）时，常需将 Web 根目录（root）设为 public/ 以提升安全性，同时将所有动态请求集中交由单一入口文件（如 private/routes.php）统一调度。但直接使用传统 location ~ \.php$ 块会导致“例外逻辑”难以维护——例如你希望 /public/test.php 直接执行，而 /admin.php 或 /api/v1/users 则必须走路由；又如 /css/main.css 应作为静态文件返回，而非被 PHP 处理器拦截。

以下是最推荐的配置结构，它基于 责任分离原则：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

location / 负责静态资源匹配与 fallback；
location ~ \.php$ 负责显式 PHP 文件的独立执行；
location @fallback 专用于兜底路由，不依赖 root 重定义，语义清晰且无歧义。

server {
    listen 80;
    listen [::]:80;
    server_name domain.com;

    # ✅ 主 root 严格限定为 public，符合安全最佳实践
    root /var/www/domain.com/public;

    # ? 静态资源：优先匹配真实文件，否则跳转至路由入口
    location / {
        try_files $uri $uri/ @fallback;
    }

    # ? 显式 PHP 文件：仅处理实际存在的 .php 文件，否则也 fallback
    location ~ \.php$ {
        try_files $uri @fallback;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }

    # ? 兜底路由：所有未命中静态/显式 PHP 的请求，均交由 routes.php 统一处理
    location @fallback {
        include fastcgi_params;
        # ⚠️ 关键：直接指定绝对路径，无需修改 root
        fastcgi_param SCRIPT_FILENAME /var/www/domain.com/private/routes.php;
        # 可选：若 routes.php 依赖 REQUEST_URI 或 PATH_INFO，此设置已足够
        # 如需完全模拟传统 PHP 执行上下文，可补充：
        # fastcgi_param SCRIPT_NAME /private/routes.php;
        # fastcgi_param DOCUMENT_URI /private/routes.php;
        # fastcgi_param DOCUMENT_ROOT /var/www/domain.com;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }
}

✅ 为什么这样更优？

无重复 root：全程只声明一次 root，@fallback 中通过绝对路径指定 SCRIPT_FILENAME，避免因 root 变更导致的 $document_root 错乱；
无嵌套 location：彻底移除 location / { ... location ~ \.php$ { ... } } 这类易出错的嵌套结构，逻辑扁平、调试直观；
精准 fallback：try_files $uri @fallback 确保只有真实不存在的 URI（或 PHP 文件）才进入路由，/nonexistent.php 不再返回 404，而是由 routes.php 决定响应（如 404 页面或重定向）；
兼容性更强：不依赖 Debian/Ubuntu 特有的 snippets/fastcgi-php.conf（其内置 try_files 会与我们自定义逻辑冲突），改用标准 fastcgi_params，移植性更高。

⚠️ 注意事项

若 routes.php 中依赖 $_SERVER['SCRIPT_NAME'] 或 $_SERVER['DOCUMENT_ROOT']，请按上方注释启用对应 fastcgi_param 覆盖；
确保 /var/www/domain.com/private/routes.php 具有正确的文件权限（PHP-FPM 进程可读）；

如需支持 domain.com/subdir/ 自动解析为 subdir/index.php，请将 location / 块改为：

location / {
    index index.php;
    try_files $uri $uri/ /index.php?$query_string;
    # 注意：此处仍需保留 @fallback 逻辑，仅当 $uri/ 也不存在时才触发
    # 实际建议仍用：try_files $uri $uri/ @fallback;
}

该方案兼顾安全性、可维护性与语义明确性，是现代 PHP 应用 Nginx 路由配置的推荐范式。