RewriteBase 到底改什么?Apache 官方:只在目录级替换相对路径时生效
一、Apache 官方对 RewriteBase 的定义只有一句话
多数人在子目录里跑 CodeIgniter、Laravel、ThinkPHP 时改伪静态,抄来一句 RewriteBase /subdir/,改错了就整站 404,但很少有人知道它在规范里到底管什么。httpd 官方手册的指令卡头就把范围限定死了:
Description: Sets the base URL for per-directory rewrites
Syntax: RewriteBase URL-path
Default: None
Context: directory, .htaccess
Override: FileInfo
Module: mod_rewrite
正文第一句:RewriteBase 指定的是"per-directory(目录级)RewriteRule 指令在替换成相对路径时所使用的 URL 前缀"。注意三个限定词 —— 只在目录级上下文(<Directory> 或 .htaccess)里参与、只影响替换目标是相对路径的规则、它给的是一个URL 前缀而不是文件系统路径。

二、什么时候必须写、什么时候可以不写
官方原文写得非常克制:当你在目录级上下文的替换部分使用相对路径时,这个指令是必需的,除非满足以下任一条件:
- 原始请求与替换目标都在 DocumentRoot 之下(而不是通过 Alias 等其它手段可达);
- RewriteRule 所适用的目录路径,加上那个相对替换后缀之后,在服务器上本身也是一个合法 URL 路径 —— 手册特意加了括号注明"这种情况很少见(this is rare)";
- 在 Apache HTTP Server 2.4.16 及更高版本中,当请求是通过
Alias或mod_userdir映射时,可以省略该指令。
这三条正好解释了两个常见困惑。第一,为什么"根目录的站点从来不写 RewriteBase 也能跑"—— 因为满足了第 1 条:请求和替换都在 DocumentRoot 下,mod_rewrite 能自己算出来。第二,为什么"我在 public_html 用软链指向另一份代码时就 404"—— 因为站点不再直接位于 DocumentRoot 下,第 1 条不成立,而多数人又停在 2.4.16 之前的版本,第 3 条也不成立,于是必须显式写 RewriteBase。
三、子目录部署的标准写法(CodeIgniter 场景)
把应用放在 https://example.com/ci4/ 下时,.htaccess 里的关键是让相对替换知道基准 URL 前缀:
<IfModule mod_rewrite.c>
RewriteEngine On
# 关键:这里是 URL 前缀,不是磁盘路径
RewriteBase /ci4/
# 把真实文件/目录直接放行
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# 替换目标是相对路径 index.php,因此必须靠 RewriteBase 补全
RewriteRule ^(.*)$ index.php/$1 [L,QSA]
</IfModule>
对照手册定义就能理解这条链路:index.php/$1 是相对路径替换,RewriteBase 提供的 /ci4/ 会被拼接进去,最终落到 /ci4/index.php/...。如果你删掉 RewriteBase,而站点又恰好通过 Alias 或软链可达(不满足上面第 1 条),重写结果就会脱离 /ci4/ 前缀、跳到根下去找 index.php —— 表现就是首页能进、二级路由全 404。
四、两个高频错法
错误 1:写成文件系统路径
RewriteBase /var/www/html/ci4/ # 错:这是磁盘路径,不是 URL 前缀
指令的语法项是 URL-path,手册的表述是"URL prefix"。任何以磁盘路径填入的写法都不会得到你想要的结果。
错误 2:斜杠不成对
RewriteBase 的值应当首尾各带一个斜杠:/ci4/。写成 /ci4(缺尾斜杠)时,相对路径替换会拼出 /ci4index.php 这类畸形地址。
五、mod_rewrite 的日志开关,2.4 以后换法了
调试这一类问题不该靠猜。手册专门说明:熟悉早期版本的开发者会去找 RewriteLog 和 RewriteLogLevel 两个指令 —— 自 httpd 2.4 起,它们已被 LogLevel 提供的按模块日志配置取代。mod_rewrite 在 trace1 到 trace8 级别输出详细动作,可以单独为该模块设置:
LogLevel alert rewrite:trace3
手册同时警告:为 mod_rewrite 使用较高的 trace 日志级别会严重拖慢 Apache HTTP Server,只在调试时使用高于 trace2 的级别。想只看重写相关的日志行,官方给的命令是:
tail -f error_log | fgrep '[rewrite:'
这条排查路径比反复改 RewriteBase 有效得多:trace3 的输出里能直接看到 RewriteBase 被解析成什么、相对替换最终展开成了哪个 URL。
六、CodeIgniter 4 的配套检查项
子目录部署失败常常不只是 RewriteBase,CI4 侧还有两处必须同步:
app/Config/App.php里的$baseURL必须写成完整绝对地址并包含子目录,例如https://example.com/ci4/;$indexPage若设为''(希望去掉 index.php),则重写规则必须能把请求真正送进 index.php,否则表单提交、资源加载会因相对路径解析错位而报错。
另外要确认 AllowOverride FileInfo(或 All)在对应 <Directory> 里开启。RewriteBase 的 Override 要求正是 FileInfo —— 如果 AllowOverride None,这个 .htaccess 会被整体忽略,症状与"RewriteBase 写错"极像但成因完全不同。
七、常见问题
Q:在虚拟主机根目录的 vhost 里写的 RewriteRule,需要 RewriteBase 吗?
A:不需要,RewriteBase 在这里也没有意义。手册明确其 Context 是 directory, .htaccess,且只针对"per-directory 规则替换相对路径"的场景。服务器级/vhost 级的规则里,替换目标本来就按完整 URL 路径处理。
Q:Apache 2.4.16+ 用 Alias 映射站点,还要写 RewriteBase 吗?
A:官方第 3 条给出可以省略的条件正是"请求经 Alias 或 mod_userdir 映射"。但这依赖版本,若你不确定线上 httpd 版本,显式写一行正确的 URL 前缀成本更低、也更可预测。
Q:RewriteBase 能写多次吗?
A:可以,作用范围是它所在的目录上下文。多份 .htaccess 分层存在时,越靠近目标目录的那份影响其下的规则。跨层调试时,日志里 RewriteBase 的实际生效值是判断依据,别靠记忆。
