Nginx 全局路由捕获与静态资源例外处理最佳实践-php教程-PHP中文网

Nginx 全局路由捕获与静态资源例外处理最佳实践

本文介绍如何在 Nginx 中优雅实现「所有请求默认交由私有路由入口（如 /private/routes.php）统一处理，同时精准放行 CSS/JS 等静态资源及指定 PHP 文件」的配置方案，避免重复 root、嵌套 location 和 try_files 误用等常见陷阱。

本文介绍如何在 nginx 中优雅实现「所有请求默认交由私有路由入口（如 `/private/routes.php`）统一处理，同时精准放行 css/js 等静态资源及指定 php 文件」的配置方案，避免重复 root、嵌套 location 和 try_files 误用等常见陷阱。

在构建基于 PHP 的现代 Web 应用时，常需采用「前端控制器（Front Controller）」模式：所有 HTTP 请求统一由一个入口文件（如 private/routes.php）调度，以实现路由解析、中间件、权限控制等逻辑。但与此同时，CSS、JS、图片等静态资源，以及少数需直通执行的公开 PHP 脚本（如 /public/test.php），必须绕过该路由层，直接响应以保障性能与安全性。

传统配置中常见的误区包括：滥用 root 指令导致上下文混乱、嵌套 location ~ \.php$ 引发优先级冲突、错误依赖 fastcgi-php.conf（其内置 try_files 与自定义逻辑冲突），以及对 @named_location 回退机制理解不足。以下为推荐的清晰、健壮且可维护的解决方案：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

✅ 推荐配置（精简可靠版）

server {
    listen 80;
    listen [::]:80;
    server_name domain.com;
    root /var/www/domain.com/public;  # 统一以 public 为文档根

    # 静态资源：存在则直接服务，否则回退至路由入口
    location /css/ { try_files $uri =404; }
    location /js/  { try_files $uri =404; }
    location /images/ { try_files $uri =404; }

    # 显式放行特定 PHP 文件（如 test.php）
    location = /test.php {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$uri;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }

    # 所有其他 PHP 请求：存在则执行，否则回退
    location ~ \.php$ {
        try_files $uri @fallback;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$uri;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }

    # 默认非 PHP 请求：存在则服务，否则回退
    location / {
        try_files $uri $uri/ @fallback;
    }

    # 【核心】全局回退入口：强制交由 private/routes.php 处理
    location @fallback {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /var/www/domain.com/private/routes.php;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
        # 可选：模拟原始请求上下文（若 routes.php 依赖 $_SERVER['SCRIPT_NAME'] 等）
        # fastcgi_param SCRIPT_NAME /private/routes.php;
        # fastcgi_param DOCUMENT_URI /private/routes.php;
        # fastcgi_param DOCUMENT_ROOT /var/www/domain.com;
    }
}

? 关键设计说明

单一 root 声明：全程使用 root /var/www/domain.com/public，避免因 location 内重置 root 导致 $document_root 不一致问题；
@fallback 命名 location 替代嵌套：将兜底逻辑集中于 @fallback，消除 location / { root ... } + 内部 location ~ \.php$ 的耦合与歧义；
try_files 分层控制：
- 静态路径（/css/, /js/）：直接 try_files $uri =404，不触发 PHP；
- 显式 PHP 路径（/test.php）：用 = 精确匹配，确保仅该路径生效；
- 通配 PHP（~ \.php$）：先检查文件是否存在，再回退——解决了原问题中“不存在的 PHP 文件未被 catch-all 捕获”的核心缺陷；
- 根路径 /：支持目录索引（$uri/），并最终回退至 @fallback；
脱离 fastcgi-php.conf 依赖：手动 include fastcgi_params 并显式设置 SCRIPT_FILENAME，规避其内置 try_files 冲突，完全掌控执行逻辑。

⚠️ 注意事项与增强建议

若 routes.php 中需还原原始请求路径（如 $_SERVER['REQUEST_URI'] 已被 Nginx 正确传递，无需额外处理），但若依赖 SCRIPT_NAME 或 DOCUMENT_URI，请按注释启用对应 fastcgi_param 覆盖；

如需支持子目录下的 index.php（例如访问 /admin/ 自动执行 /public/admin/index.php），将 location / 块改为：

location / {
    index index.php;
    try_files $uri $uri/ /index.php?$query_string;
    # ❌ 错误：此处不能直接 fallback，应统一走 @fallback
    # ✅ 正确：保留原结构，仅添加 index 支持
    try_files $uri $uri/ @fallback;
}