定义:伪静态规则迁移的含义
Nginx rewrite 指 nginx 的 ngx_http_rewrite_module 提供的地址改写能力,在 server 或 location 配置段内按书写顺序执行;伪静态规则迁移则是把 Apache 侧依赖 .htaccess(按目录生效、可被上层 AllowOverride 覆盖的分布式配置文件)与 mod_rewrite 模块实现的重写逻辑,逐条改写为 nginx 配置的过程。两者目标相同:把 /index.php?p=123 这类带查询参数的动态地址,呈现为 /sample-post/ 的静态外观,服务器内部依然执行 PHP。
差异在于生效位置与匹配时机。Apache 在每个请求到达时按目录层级读取 .htaccess,再按顺序比对 RewriteCond 与 RewriteRule;nginx 在启动时把配置编译成 location 匹配结构,rewrite 指令只在命中的 server 或 location 内执行。这条差异决定了规则不能逐行照抄,既有 .htaccess 伪静态用法可参见 .htaccess 伪静态的实际运用。
特点:执行模型与指令语义的差异
从技术架构上看,两套重写体系并非一一对应,主要区别集中在四处:
- 配置粒度:Apache 的 .htaccess 按目录生效,同一份规则可被多个虚拟主机复用;nginx 只有 http、server、location 三层,目录级规则需要改写成独立的 location 块。
- 条件判断:mod_rewrite 用 RewriteCond 组合变量条件,支持 [OR]、[AND] 连接;nginx 的 if 只允许出现在 server 与 location 内,且不宜多层嵌套。
- 标记含义:Apache 的 [L] 表示本轮最后一条规则,nginx 的 last 会重新发起 location 查找,break 只终止当前 location 内的 rewrite,混用是循环重写的主要来源。
- 文件判断:Apache 用 %{REQUEST_FILENAME} 配合 !-f、!-d 排除真实文件与目录;nginx 通常由 try_files 一次完成,判断顺序为文件、目录、回退目标。
这层结构差异也带来性能上的不同代价。Apache 在 AllowOverride 打开时,每次请求都要沿目录链读取并解析 .htaccess,规则条目越多,stat 与解析开销越明显;nginx 只在启动或 reload 时解析一次配置,运行期按已编译的匹配结构处理,单请求几乎没有额外文件读取。代价是规则改动必须 reload 才生效,无法像 .htaccess 那样上传即应用,这也是托管面板普遍把伪静态入口做成”保存后自动重载”的原因。
工作原理:请求进入 Nginx 后的处理顺序
请求到达后,nginx 先按 server_name 选定虚拟主机,再用 location 匹配 URI,命中后依次执行该段内的 rewrite、if 与 try_files。rewrite 只改写内部 URI,浏览器地址栏保持不变;只有附带 redirect 或 permanent 标记时才向客户端返回 301 或 302。WordPress 单站点的规范配置因此写成下面这样,PHP 处理交给 FastCGI,静态请求由 root 直接响应。
server {
listen 80;
server_name example.com;
root /var/www/example;
index index.php;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}
}
try_files 的三个参数构成与 Apache 两条 RewriteCond 等价的判断:$uri 对应磁盘上真实存在的文件,$uri/ 对应真实目录,两者都不成立时才回退到 /index.php?$args。末尾的 $args 保留原始查询串,遗漏它会让分页、搜索与跟踪参数在跳转后全部丢失,表现为第二页固定返回首页内容。同类配置的演进过程可参考 Nginx 环境下为 WordPress 设置 rewrite 规则。

迁移对照:逐条改写的方法
稳妥的做法是先把源规则登记成清单,按”源写法、目标指令、边界条件”三列逐条对照,再动手改配置。常见写法的对应关系如下:
| Apache(.htaccess + mod_rewrite) | Nginx 对应写法 | 迁移注意点 |
|---|---|---|
| RewriteEngine On | 无对应开关 | rewrite 模块随 nginx 默认编译加载,删掉该行即可 |
| RewriteBase /blog/ | location /blog/ { … } | 路径基准改由 location 前缀表达,块内 URI 相对前缀 |
| RewriteRule ^old\.html$ /new.html [R=301,L] | rewrite ^/old\.html$ /new.html permanent; | permanent 等价 301,匹配串需含前导斜杠 |
| RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC] | 独立 server 块 + server_name 与 return 301 | 主机名判断交给 server_name,不要塞进 if |
| RewriteCond %{REQUEST_FILENAME} !-f | try_files $uri $uri/ /index.php?$args; | 一次完成文件、目录与回退三重判断 |
带查询串的规则需要额外留意参数传递:Apache 的 RewriteRule 默认丢弃原查询串,除非加 [QSA];nginx 的 rewrite 在不写 ? 结尾时会自动保留原参数,写了问号则清空,回退目标里因此要显式拼上 $args。同样地,Apache 的 RewriteCond %{QUERY_STRING} 判断在 nginx 中通常改用 map 指令在 http 层预先映射变量,比在 location 内堆叠 if 更稳定。
以 WordPress 默认规则为例,Apache 的原始写法与迁移后的 nginx 写法的对比如下,两段代码承担同一职责:
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
location / {
try_files $uri $uri/ /index.php?$args;
}
第一行 RewriteRule ^index\.php$ - [L] 在 nginx 中无需显式写出:location ~ \.php$ 已把 PHP 请求交给 FastCGI,location / 的 try_files 只在文件与目录都不存在时回退,不会反过来改写 index.php 自身。这也是两套体系最容易产生”看似多余、删掉就坏”错觉的位置。

应用场景:什么时候需要做这类迁移
迁移需求通常来自运行环境变更,而不是规则本身失效。按变更类型可以分成四类:
- 主机方案更换:从以 Apache 为默认后端的虚拟主机(多个站点共享同一台服务器资源的托管方式)迁到 nginx 或 nginx 反代 Apache 的套餐时,原 .htaccess 不再被读取,伪静态会整站失效,文章页统一返回 404。nginx 作为入口层时的请求分层可参见 反向代理与负载均衡的入口层原理。
- 静态化与缓存改造:WordPress 迁移到 nginx 加 PHP-FPM,并在前面加一层缓存时,固定链接规则必须由 try_files 承担,否则回源请求拿到的是 404,缓存层会把错误结果一并缓存。
- 域名与目录结构调整:主域与 www 合并、旧目录并入 /blog/ 时,Apache 用 RewriteRule 加 [R=301],nginx 用独立 server 块加 return 301,两者都要求只跳一次,避免链路叠加导致权重分散。
- 多站点与子目录部署:WordPress 多站点子目录模式的规则在 .htaccess 中以 RewriteBase 为基准,迁移后需按站点前缀拆成多个 location,否则子站之间会互相覆盖重写目标。
常见误区与边界条件
多数迁移故障不是语法错误,而是语义错位。以下五类情况在排查记录中出现的频率最高:
- 把 RewriteRule 的正则整段粘进 location / 且漏写 ^ 与结尾锚点,规则对 /wp-content/uploads/ 下的图片同样生效,静态资源被送进 PHP 入口后返回 404。
- 在 location / 内写 rewrite ^ /index.php last,last 会重新触发 location 匹配,命中 \.php$ 后又回到 /,error.log 中反复出现 rewrite or internal redirection cycle。
- 用 if (!-f $request_filename) 替代 try_files,if 内的 rewrite 会与外层 location 形成二次匹配,实际行为随配置书写顺序变化,难以复现。
- 忽略尾部斜杠差异:Apache 的 DirectorySlash 自动为目录补 /,nginx 需要 try_files 中的 $uri/ 显式兜底,否则目录型固定链接会跳到错误位置。
- 把 HTTP 到 HTTPS 的跳转写成 server 级 rewrite 却漏掉 ACME 验证路径,证书续期时 /.well-known/acme-challenge/ 下的校验文件被 301 走,续期任务因校验失败中断。

验证:切换流量前的四个检查动作
规则改完不宜直接切流量,按下面的顺序验证,再分批放量更为稳妥:
- 先执行
nginx -t确认语法,再用nginx -s reload平滑加载,避免重启造成连接中断与瞬时 502。 - 用
curl -I https://example.com/sample-post/检查状态码为 200,响应头不含 Location,确认固定链接没有多余跳转。 - 用
curl -I https://example.com/wp-content/uploads/2026/10/sample.webp检查返回 200 且内容类型为 image/webp,确认静态资源未被重写吞掉。 - 复查 error.log,检索 rewrite or internal redirection cycle 与 404 记录;同时比对两套环境同一时段的访问日志条数,差值超过 5% 说明仍有规则未覆盖。
若站点在过渡期仍需在 Apache 与 nginx 之间双跑,保留一份 .htaccess 作为回滚依据即可,但不要在两个入口同时启用改写,否则跳转与缓存链路会叠加,排查时难以区分是哪一层生效。
参考资料
- nginx 官方文档:ngx_http_rewrite_module,rewrite、if、return 指令的语义与执行顺序。
- nginx 官方文档:try_files 指令,文件、目录与回退参数的判断顺序。
- Apache HTTP Server 2.4 文档:mod_rewrite,RewriteCond 与 RewriteRule 的标记含义。
- WordPress 开发者资源:htaccess 说明,单站点与多站点模式的默认重写规则。

微信扫一扫打赏
支付宝扫一扫打赏