Xiuno伪静态失效？一键排障全攻略

52JinY 助手

这两天在给老站做搬家升级，顺手把 xiuno 的伪静态也理了一遍，结果遇到个熟悉又抓狂的问题：明明 Nginx 已经加了 rewrite，后台也勾了“启用伪静态”，前台依旧是 index.php? 的参数形式，甚至部分页面 404。折腾半天，总结几条血泪经验，给后来者避坑。

先说排查思路。

别盯着“哪里不生效”，先确认“谁该接手”。xiuno 的 URL 路由其实很简单：当你在后台开启伪静态，它期望 Web 服务器把所有非真实文件的请求都转发给 index.php。也就是说，核心不在“把 query 去掉”，而是“统一入口”。所以第一步用 curl -I 或者浏览器调试看请求链路：/thread

/123 这种路径，是不是被 200 转到了 index.php（可在响应头里找 X-Powered-By、Set-Cookie 或看 access log 的 upstream 日志）。若直接 404，多半是 rewrite 根本没命中，或命中了却又被后续规则覆盖。

再看 Nginx 配置的层级。常见坑是把 rewrite 放在 server 外面、或写在了错误的 location 里。xiuno 的典型写法是：在站点

block 里定义一个统一的 location /，再配合 try_files，把不存在的路径丢给 index.php。很多人抄来抄去只抄了半句，结果是静态资源也被转了，前端一片红。一个相对稳妥的片段是：

- 根目录要正确：root /path/to/xiuno/public;（有的人把代码丢在更上一层，导致 index.php 找不到资源）
- 静态资源先行：location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff2?|ttf|eot)$ { try_files $uri =404; expires 30d; access_log off; } 保证这些直接命中文件，不走 PHP。
- 动态统一入口：location / { try_files $uri $uri/ /index.php?$query_string; }
- PHP 处理：location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/run/php/php8.1-fpm.sock; } 这里最容易错的是 SCRIPT_FILENAME，用错成 $request_filename 会在子目录或别名下踩坑。