前言伪静态URL rewrite地址重写不生效症状通常高度一致本地开发环境因为跑的是php -S或者 Apache 带.htaccess/article/123这样的地址访问得好好的换到线上 nginx 之后所有漂亮路由一律 404但带index.php的老地址/index.php?rarticle/viewid123又完全正常。于是很多人第一反应是PHP 版本不对或者框架坏了去翻composer.json、去重装扩展方向全跑偏了。真相是伪静态是 Web 服务器nginx / Apache / IIS的职责PHP 7.4 在这件事上只是一个下游消费者。请求在到达 PHP 之前就已经被服务器的 URL 匹配规则决定好了要交给谁。规则没命中PHP-FPM 进程根本不知道有这次请求自然也不会报错——你只会看到一个干净的 404错误日志里什么都没有。本文给出一条十分钟定位到层的排查路径覆盖 nginx、Apache 两种主流部署附一个能直接打印出路由相关$_SERVER变量的探针脚本以及一份高频踩坑清单。一、第一步判断请求到底走到哪一层不要先改配置先取证。三条curl就能把问题定位到具体层# 1) 漂亮地址如果这里 404 而下一步正常说明问题在服务器重写规则 curl -i -s http://example.com/article/123 | head -n 20 # 2) 显式带入口文件的等价地址这一步正常说明 PHP 与框架路由本身没问题 curl -i -s http://example.com/index.php?rarticle/viewid123 | head -n 20 # 3) 用 PATH_INFO 形态再试一次用来区分没重写和重写了但没传 PATH_INFO curl -i -s http://example.com/index.php/article/123 | head -n 20三次结果组合起来结论非常明确第 1 次第 2 次第 3 次结论404200200重写规则没生效nginxtry_files/ ApacheRewriteRule没命中404200404重写生效了但PATH_INFO没传给 PHP-FPM404404404与伪静态无关先查站点根目录、root指令、PHP-FPM 是否在跑200200200服务器层没问题去看框架路由匹配顺序路由前缀、大小写敏感等关键技巧是看 404 的响应头而不是响应体。nginx 自己产生的 404 通常带Server: nginx且没有X-Powered-ByPHP 产生的 404 一般会带上框架的特征头。这一眼就能区分请求没到 PHP和到了 PHP 但路由没匹配。# 用 -v 看清请求头与响应头确认请求确实被改写成了 /index.php curl -v -s http://example.com/article/123 21 | grep -E ^(|) # 看上游到底收到了什么 URI关键字段是 access log 里的 $request 与 $upstream_... tail -n 50 /var/log/nginx/access.log二、nginx 侧最常见的三类失效1.try_files的最后一段把查询串吃掉了这是最高频的一条。很多教程里抄来的写法是# ❌ 少了一个字符末尾是 /index.php 而不是 /index.php? location / { try_files $uri $uri/ /index.php; }try_files的最后一个参数是内部重定向的目标 URI。写成/index.php时nginx 会把原始请求的查询串丢弃于是?rarticle/viewid123到了 PHP 那边就变成了空。用户看到的现象就是页面能打开但永远是首页/空数据。# ✅ 推荐写法一显式保留查询串$is_args 在有查询串时是 ?否则是空串 location / { try_files $uri $uri/ /index.php$is_args$args; } # ✅ 推荐写法二Laravel 文档中常见的等价写法 location / { try_files $uri $uri/ /index.php?$query_string; }$query_string是$args的别名?直接写死也没关系——查询串为空时目标就是/index.php?nginx 会忽略这个空查询串。2.location ~ \.php$匹配不到带 PATH_INFO 的地址$表示字符串结尾所以/index.php/article/123根本不会命中下面这个块nginx 会直接 404# ❌ 只匹配以 .php 结尾的 URI location ~ \.php$ { include fastcgi_params; }# ✅ 同时匹配 .php 之后还有路径的情况并把 PATH_INFO 传下去 location ~ [^/]\.php(/|$) { fastcgi_split_path_info ^(.?\.php)(/.*)$; include fastcgi_params; # 提供 SCRIPT_NAME、QUERY_STRING 等 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_pass unix:/run/php/php7.4-fpm.sock; }fastcgi_split_path_info用两个捕获组把 URI 拆成脚本路径和路径信息第二个捕获组通过$fastcgi_path_info传给PATH_INFO。少了这一行PHP 里$_SERVER[PATH_INFO]就是空的——这正是第 3 次curl失败、第 2 次成功的那个组合。3. 规则被更靠前的location抢先匹配nginx 的匹配顺序是先找最长前缀匹配的location记住它再按配置文件中的出现顺序逐个尝试正则location一旦命中就立即采用^~修饰符可以阻止正则继续匹配。很多人把location ~* \.(js|css|png)$写在前面又把location /写在后面结果静态资源的规则把动态地址也截走了。# ❌ 正则 location 放在最前面会盖掉后面的 location / location ~* \.(js|css|png|jpg)$ { expires 30d; } location / { try_files $uri $uri/ /index.php$is_args$args; }# ✅ 前缀 location 在前或用 ^~ 明确命中前缀就不要再看正则 location / { try_files $uri $uri/ /index.php$is_args$args; } location ^~ /static/ { expires 30d; } location ~* \.(js|css|png|jpg)$ { expires 30d; }改完配置别用nginx -s reload前先自检并确认线上加载的确实是这份文件nginx -t # 语法检查 nginx -T | grep -n -A6 location / # 打印合并后的完整配置确认规则真的在其中 systemctl reload nginxnginx -T会把 include 进来的所有片段合并输出是排查我明明改了配置文件却不生效改错文件、被别的 include 覆盖的最快手段。三、Apache 侧.htaccess写了却没反应Apache 上伪静态不生效几乎只有一个原因.htaccess根本没被读取。再往下分三种# 1) mod_rewrite 没启用 —— RewriteRule 会被当成未知指令直接 500 或忽略 apachectl -M | grep rewrite # Debian/Ubuntu 系启用 a2enmod rewrite systemctl restart apache2 # 2) 站点配置里 AllowOverride 是 None —— .htaccess 被完全忽略且不报错 # 检查站点 conf grep -n -A5 Directory /etc/apache2/sites-enabled/000-default.conf# ❌ AllowOverride None.htaccess 内容被彻底无视也不会有任何提示 Directory /var/www/html AllowOverride None /Directory# ✅ 至少给到 FileInfo重写规则才生效 Directory /var/www/html AllowOverride FileInfo Options -MultiViews /Directory第 3 种更隐蔽ModNegotiation 的 MultiViews。开了 MultiViews 之后Apache 会把/article/123这种看起来像目录的请求先做一轮内容协商尝试匹配article.php之类的文件。表现是路由偶尔对、偶尔错非常难查。用Options -MultiViews关掉它。规则本身也要写对特别注意[L]与[QSA]# ❌ 缺少条件判断连真实存在的静态文件也会被丢给 index.php RewriteRule ^(.*)$ index.php [L] # ❌ 忘记 QSA原始查询串被 rewrite 的目标覆盖掉 RewriteRule ^ index.php?r$1 [L]# ✅ 标准写法先排除真实文件与真实目录再重写并用 QSA 保留原查询串 IfModule mod_rewrite.c RewriteEngine On RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^ index.php [L,QSA] /IfModuleRewriteBase /在站点部署在子目录比如/shop/时是必须的少了它会导致重写目标指向错误的位置。四、实战一个路由探针脚本不管用哪种服务器先放一个探针文件上去把 PHP 侧真正收到的东西打出来比猜快得多。?php // router-probe.php —— PHP 7.4 兼容 // 放到站点根目录访问 /router-probe.php/article/123?a1 观察输出 // 排查完请立刻删除该文件 $keys [ REQUEST_URI, // 原始请求行里的 URI含查询串永远最可信 SCRIPT_NAME, // 当前执行的脚本路径重写后通常是 /index.php PHP_SELF, // 含 PATH_INFO 的脚本路径 PATH_INFO, // 重写规则传入的额外路径nginx 需要 fastcgi_param 才会出现 QUERY_STRING, // 查询串被 try_files 吃掉时这里为空 ORIG_PATH_INFO, DOCUMENT_ROOT, REQUEST_METHOD, ]; header(Content-Type: text/plain; charsetutf-8); foreach ($keys as $k) { printf(%-16s : %s\n, $k, isset($_SERVER[$k]) ? $_SERVER[$k] : (未设置)); } // 把 URL 解析成路由片段的常见做法优先用 REQUEST_URI而不是 PATH_INFO $path parse_url($_SERVER[REQUEST_URI] ?? /, PHP_URL_PATH); $path trim(rawurldecode($path), /); $segments $path ? [] : explode(/, $path); echo str_repeat(-, 40), \n; echo rewritten path : /, implode(/, $segments), \n; echo controller : , $segments[0] ?? (home), \n; echo action : , $segments[1] ?? index, \n; echo params : , json_encode(array_slice($segments, 2), JSON_UNESCAPED_UNICODE), \n; // 顺带打印服务器层信息帮助确认是哪一层在应答 printf( sapi%s php%s server_software%s\n, PHP_SAPI, PHP_VERSION, $_SERVER[SERVER_SOFTWARE] ?? (未知) );访问/router-probe.php/article/123?a1与/article/123?a1后者走伪静态两条地址对比输出可以立刻分辨两者输出一致 → 重写完全正常问题在前端路由/框架。后者QUERY_STRING为空而前者不为空 → 命中了try_files ... /index.php缺少?的写法。后者PATH_INFO为空 →fastcgi_split_path_info/fastcgi_param PATH_INFO没配。后者 404 而前者 200 → 重写规则整体没命中回到第二、三节。常见坑点1. 改了.htaccess以为立即生效其实AllowOverride None让它从未被读取# ❌ 只重启服务从不去确认配置有没有被加载 systemctl restart apache2# ✅ 先确认 AllowOverride再看错误日志里是否有 .htaccess 相关告警 apachectl -t -D DUMP_RUN_CFG 21 | head tail -n 50 /var/log/apache2/error.log2. 用 nginxtry_files时把查询串丢了页面能开但没数据# ❌ try_files $uri $uri/ /index.php;# ✅ try_files $uri $uri/ /index.php$is_args$args;3. 用location ~ \.php$却要在 URL 里带额外路径# ❌ /index.php/article/123 命中不了nginx 直接 404PHP 日志里什么都没有 location ~ \.php$ { fastcgi_pass unix:/run/php/php7.4-fpm.sock; }# ✅ 允许 .php 后面还有路径并显式传 PATH_INFO location ~ [^/]\.php(/|$) { fastcgi_split_path_info ^(.?\.php)(/.*)$; fastcgi_param PATH_INFO $fastcgi_path_info; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/run/php/php7.4-fpm.sock; }4. 反代 / CDN 把重写规则抹平了本地怎么调都没用# ❌ 只看源站配置忽略了前面还有一层反代 systemctl status nginx# ✅ 直连源站 IP 与 Host 头测试剥离反代因素 curl -i -s -H Host: example.com http://10.0.0.12/article/123 | head -n 20如果直连源站正常、走域名异常问题就在反代层它可能没透传Host或把 URI 归一化成了/。5. 用户浏览器缓存了旧的 301改了规则看起来还是不生效# ❌ 改完规则用浏览器刷新看到的还是上次的 301 跳转# ✅ 用 curl 绕开一切缓存配置里也别对动态路由发永久重定向 curl -i -s http://example.com/article/123 | head -n 5 # ✅ 确实需要跳转时用 302避免 301 被浏览器长期缓存 # nginx: return 302 /new-path;6.index index.php index.html;让静态首页抢走了/# ❌ 请求 / 时先命中 index.html动态首页永远进不去 index index.php index.html;# ✅ 把动态入口排在最前或直接删掉不需要的静态首页 index index.php;7. 把重写规则写在错误的 server 块里多域名共存时# ❌ 站点有两个 server主站 移动站点规则只加在了其中一个 server { listen 80; server_name m.example.com; location / { try_files $uri /index.php$is_args$args; } }# ✅ 用 nginx -T 确认规则出现在哪个 server 块中必要时抽成公共文件 include nginx -T | grep -n -B5 try_files8. 探针文件留在生产环境// ❌ 排完问题就忘了删探针把服务器路径、SAPI、版本信息暴露给任何人 // 就像本文第四节的 router-probe.php# ✅ 排查完成后立即删除或至少在代码里加一层 IP 白名单判断后退出 rm -f /www/html/router-probe.php总结现象首选排查点典型原因漂亮地址 404带index.php正常服务器重写规则try_files未命中 /.htaccess未被读取页面能开但无数据查询串是否保留try_files /index.php少了?/index.php/xxx也 404nginx 的location正则\.php$结尾匹配不到带路径的 URI改了配置没反应加载的到底是哪个文件改错文件、被 include 覆盖、未 reload本地好线上坏部署形态差异Apache/.htaccessvs nginx或前面还有反代结论排查伪静态永远从请求到了哪一层开始而不是从 PHP 代码开始。三条curl确定层次nginx -T确认配置真的被加载探针脚本确认 PHP 收到的REQUEST_URI/PATH_INFO/QUERY_STRING是否如预期。这三步做完剩下的只是改哪一行配置的问题反过来如果不做分层直接去翻框架路由代码很可能在完全正确的 PHP 代码里找一整天。