记录每个点滴
adriano · 2007-08-02
[转]URL重写(1)apachemod_rewrite模块文档
- [
apache
]
2007-08-02
Tag:
apache
rewrite
版权声明
:转载时请以超链接形式标明文章原始出处和作者信息及
本声明
http://adriano.blogbus.com/logs/7308671.html
URL重写
"The great thing about mod_rewrite is it gives you all the configurability and flexibility of Sendmail. The downside to mod_rewrite is that it gives you all the configurability and flexibility of Sendmail."
--
Brian Behlendorf
Apache Group
" Despite the tons of examples and docs, mod_rewrite is voodoo. Damned cool voodoo, but still voodoo."
--
Brian Moore
bem@news.cmc.net
欢迎来到
mod_rewrite
,URL操作的瑞士军刀!
此模块提供了一个基于规则的(使用正则表达式分析器的)实时重写URL请求的引擎。 支持每个规则可以拥有不限数量的子规则以及附加条件规则的灵活而且强大的URL操作机制。 此URL操作可以取决于各种测试,比如服务器变量、环境变量、HTTP头、时间标记,甚至各种格式的用于匹配URL组成部分的查找数据库。
此模块可以操作URL的所有部分(包括路径信息部分),在服务器级(
httpd.conf
)和目录级(
.htaccess
)配置中都有效, 还可以生成最终的请求字符串。此重写操作的结果可以是内部子处理,也可以是外部请求的重定向,甚至还可以是内部代理处理。
但是,所有这些功能和灵活性带来一个问题,那就是复杂性,因此,不要指望一天之内就能看懂整个模块。
Apache模块 mod_rewrite
说明
一个基于一定规则的实时重写URL请求的引擎
状态
扩展(E)
模块名
rewrite_module
源文件
mod_rewrite.c
兼容性
仅在 Apache 1.3 及以后的版本中可用
概述
此模块提供了一个基于正则表达式分析器的重写引擎来实时重写URL请求。它支持每个完整规则可以拥有不限数量的子规则以及附加条件规则的灵活而且强大的URL操作机制。此URL操作可以依赖于各种测试,比如服务器变量、环境变量、HTTP头、时间标记,甚至各种格式的用于匹配URL组成部分的查找数据库。
此模块可以操作URL的所有部分(包括路径信息部分),在服务器级的(
httpd.conf
)和目录级的(
.htaccess
)配置都有效,还可以生成最终请求字符串。此重写操作的结果可以是内部子处理,也可以是外部请求的转向,甚至还可以是内部代理处理。
但是,所有这些功能和灵活性带来一个问题,那就是复杂性,因此,不要指望一天之内就能看懂整个模块。
更多的讨论、细节、示例,请查看详细的
URL重写文档
。
特殊字符的引用
在Apache 1.3.20中,
TestString
和
Substitution
中的特殊字符可以用前导斜杠(\)来实现转义(即忽略其特殊含义而视之为普通字符)。 比如,
Substitution
可以用"
\$
"来包含一个美元符号,以避免mod_rewrite把它视为反向引用。
环境变量
此模块会跟踪两个额外的(非标准)CGI/SSI环境变量,
SCRIPT_URL
和
SCRIPT_URI
。他们包含了当前资源的
逻辑
网络视图,而标准CGI/SSI变量
SCRIPT_NAME
和
SCRIPT_FILENAME
包含的是
物理
系统视图。
注意:这些变量保持的是
其最初被请求时的
URI/URL,即在任何重写操作
之前
的URI/URL。其重要性在于他们是重写操作重写URL到物理路径名的原始依据。
示例
SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
SCRIPT_URI=http://en1.engelschall.com/u/rse/
实用方案
我们提供了
URL重写指南
和
高级URL重写指南
文档,列举了许多基于URL的问题的实用方案,其中你可以找到真实有用的规则集。
RewriteBase
指令
说明
设置目录级重写的基准URL
语法
RewriteBase
URL-path
默认值
参见使用方法
作用域
directory, .htaccess
覆盖项
FileInfo
状态
扩展(E)
模块
mod_rewrite
RewriteBase
指令显式地设置了目录级重写的基准URL。在下文中,你将看到
RewriteRule
可以用于目录级的配置文件中(
.htaccess
)并在局部范围内起作用,即规则实际处理的只是剥离了本地路径前缀的一部分。处理结束后,这个路径会被自动地附着回去。默认值是"
RewriteBase
physical-directory-path
"。
在对一个新的URL进行替换时,此模块必须把这个URL重新注入到服务器处理中。为此,它必须知道其对应的URL前缀或者说URL基准。通常,此前缀就是对应的文件路径。
但是,大多数网站URL不是直接对应于其物理文件路径的,因而一般不能做这样的假定!
所以在这种情况下,就必须用
RewriteBase
指令来指定正确的URL前缀。
如果你的网站服务器URL
不是
与物理文件路径直接对应的,而又需要使用
RewriteBase
指令,则必须在每个对应的
.htaccess
文件中指定
RewriteRule
。
例如,目录级配置文件内容如下:
# /abc/def/.htaccess -- /abc/def 目录的配置文件
# 注意:/abc/def 是 /xyz 的物理路径(例如存在一条'Alias /xyz /abc/def'指令)。
RewriteEngine On
# 让服务器知道我们使用的是 /xyz 而不是物理路径 /abc/def
RewriteBase /xyz
# 重写规则
RewriteRule ^oldstuff\.html$ newstuff.html
上述例子中,对
/xyz/oldstuff.html
的请求被正确地重写为对物理文件
/abc/def/newstuff.html
的请求。
仅供Apache Hacker们参考
以下列出了内部处理的详细步骤:
请求:
/xyz/oldstuff.html
内部处理过程:
/xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
/abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
/abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
/xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
结果:
/abc/def/newstuff.html
虽然这个过程看来很繁复,但是由于目录级重写的到来时机已经太晚了,它不得不把这个(重写)请求重新注入到Apache核心中,所以Apache内部确实是这样处理的。但是:它的开销并不象看起来的那样大,因为重新注入完全在Apache服务器内部进行,而且这样的过程在Apache内部也为其他许多操作所使用。所以,你可以充分信任其设计和实现是正确的。
RewriteCond
指令
说明
定义重写发生的条件
语法
RewriteCond
TestString
CondPattern
[
flags
]
作用域
server config, virtual host, directory, .htaccess
覆盖项
FileInfo
状态
扩展(E)
模块
mod_rewrite
RewriteCond
指令定义了规则生效的条件,即在一个
RewriteRule
指令之前可以有一个或多个
RewriteCond
指令。条件之后的重写规则仅在当前URI与
Pattern
匹配
并且
满足此处的条件(
TestString
能够与
CondPattern
匹配)时才会起作用。
TestString
是一个纯文本的字符串,但是还可以包含下列可扩展的成分:
RewriteRule反向引用
,引用方法是:
$N
(0 <= N <= 9)引用当前(带有若干
RewriteRule
指令的)
RewriteCond
中的与
Pattern
匹配的分组成分(圆括号!)。
RewriteCond反向引用
,引用方法是:
%N
(1 <= N <= 9)引用当前若干
RewriteCond
条件中最后符合的条件中的分组成分(圆括号!)。
RewriteMap扩展
,引用方法是:
${mapname:key|default}
细节请参见
RewriteMap 指令
。
服务器变量
,引用方法是:
%{
NAME_OF_VARIABLE
}
NAME_OF_VARIABLE
可以是下表列出的字符串之一:
HTTP头
连接与请求
HTTP_USER_AGENT
HTTP_REFERER
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_ACCEPT
REMOTE_ADDR
REMOTE_HOST
REMOTE_PORT
REMOTE_USER
REMOTE_IDENT
REQUEST_METHOD
SCRIPT_FILENAME
PATH_INFO
QUERY_STRING
AUTH_TYPE
服务器自身
日期和时间
其它
DOCUMENT_ROOT
SERVER_ADMIN
SERVER_NAME
SERVER_ADDR
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
TIME_YEAR
TIME_MON
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_SEC
TIME_WDAY
TIME
API_VERSION
THE_REQUEST
REQUEST_URI
REQUEST_FILENAME
IS_SUBREQ
HTTPS
这些变量都对应于类似命名的HTTP MIME头、Apache服务器的C变量、Unix系统中的
struct tm
字段,其中的大多数在其他的手册或者CGI规范中都有说明。 其中为mod_rewrite所特有的变量如下:
IS_SUBREQ
如果正在处理的请求是一个子请求,它将包含字符串"true",否则就是"false"。模块为了解析URI中的附加文件,可能会产生子请求。
API_VERSION
这是正在使用中的Apache模块API(服务器和模块之间内部接口)的版本, 其定义位于include/ap_mmn.h中。此模块API版本对应于正在使用的Apache的版本(比如在Apache 1.3.14的发行版中这个值是19990320:10)。 通常,对它感兴趣的是模块的开发者。
THE_REQUEST
这是由浏览器发送的完整的HTTP请求行(比如:"
GET /index.html HTTP/1.1
")。它不包含任何浏览器发送的其它头信息。
REQUEST_URI
这是在HTTP请求行中所请求的资源(比如上述例子中的"/index.html")。
REQUEST_FILENAME
这是与请求相匹配的完整的本地文件系统的文件路径名。
HTTPS
如果连接使用了SSL/TLS,它将包含字符串"on",否则就是"off"(无论
mod_ssl
是否已经加载,该变量都可以安全的使用)。
其它注意事项:
SCRIPT_FILENAME和REQUEST_FILENAME包含的值是相同的——即Apache服务器内部的
request_rec
结构中的
filename
字段。 第一个就是大家都知道的CGI变量名,而第二个则是REQUEST_URI(
request_rec
结构中的
uri
字段)的一个副本。
特殊形式:
%{ENV:variable}
,其中的
variable
可以是任意环境变量。它是通过查找Apache内部结构或者(如果没找到的话)由Apache服务器进程通过
getenv()
得到的。
特殊形式:
%{SSL:variable}
,其中的
variable
可以是一个
SSL环境变量
的名字,无论
mod_ssl
模块是否已经加载都可以使用(未加载时为空字符串)。比如:
%{SSL:SSL_CIPHER_USEKEYSIZE}
将会被替换为
128
。
特殊形式:
%{HTTP:header}
,其中的
header
可以是任意HTTP MIME头的名称。它总是可以通过查找HTTP请求而得到。比如:
%{HTTP:Proxy-Connection}
将被替换为
Proxy-Connection:
HTTP头的值。
预设形式:
%{LA-U:variable}
,
variable
的最终值在执行一个内部(基于URL的)子请求后确定。 当需要使用一个目前未知但是会在之后的过程中设置的变量的时候,就可以使用这个方法。
例如,需要在服务器级配置(
httpd.conf
文件)中根据
REMOTE_USER
变量进行重写, 就必须使用
%{LA-U:REMOTE_USER}
。因为此变量是由URL重写(mod_rewrite)步骤
之后
的认证步骤设置的。 但是另一方面,因为mod_rewrite是通过API修正步骤来实现目录级(
.htaccess
文件)配置的, 而认证步骤
先于
API修正步骤,所以可以用
%{REMOTE_USER}
。
预设形式:
%{LA-F:variable}
,
variable
的最终值在执行一个内部(基于文件名的)子请求后确定。 大多数情况下和上述的LA-U是相同的。
CondPattern
是条件模式,即一个应用于当前
TestString
实例的正则表达式。
TestString
将被首先计算,然后再与
CondPattern
匹配。
注意:
CondPattern
是一个
perl兼容的正则表达式
,但是还有若干增补:
可以在
CondPattern
串的开头使用'
!
'(惊叹号)来指定
不匹配
。
CondPatterns
有若干特殊的变种。除了正则表达式的标准用法,还有下列用法:
'
<CondPattern
'(词典顺序的小于)
将
CondPattern
视为纯字符串,与
TestString
按词典顺序进行比较。如果
TestString
小于
CondPattern
则为真。
'
>CondPattern
'(词典顺序的大于)
将
CondPattern
视为纯字符串,与
TestString
按词典顺序进行比较。如果
TestString
大于
CondPattern
则为真。
'
=CondPattern
'(词典顺序的等于)
将
CondPattern
视为纯字符串,与
TestString
按词典顺序进行比较。如果
TestString
等于
CondPattern
(两个字符串逐个字符地完全相等)则为真。如果
CondPattern
是
""
(两个双引号),则
TestString
将与空字符串进行比较。
'
-d
'(目录)
将
TestString
视为一个路径名并测试它是否为一个存在的目录。
'
-f
'(常规文件)
将
TestString
视为一个路径名并测试它是否为一个存在的常规文件。
'
-s
'(非空的常规文件)
将
TestString
视为一个路径名并测试它是否为一个存在的、尺寸大于0的常规文件。
'
-l
'(符号连接)
将
TestString
视为一个路径名并测试它是否为一个存在的符号连接。
'
-x
'(可执行)
将
TestString
视为一个路径名并测试它是否为一个存在的、具有可执行权限的文件。该权限由操作系统检测。
'
-F
'(对子请求存在的文件)
检查
TestString
是否为一个有效的文件,而且可以在服务器当前的访问控制配置下被访问。它使用一个内部子请求来做检查,由于会降低服务器的性能,所以请谨慎使用!
'
-U
'(对子请求存在的URL)
检查
TestString
是否为一个有效的URL,而且可以在服务器当前的访问控制配置下被访问。它使用一个内部子请求来做检查,由于会降低服务器的性能,所以请谨慎使用!
注意
所有这些测试都可以用惊叹号作前缀('!')以实现测试条件的反转。
还可以在
CondPattern
之后追加特殊的标记
[
flags
]
作为
RewriteCond
指令的第三个参数。
flags
是一个以逗号分隔的以下标记的列表:
'
nocase|NC
'(忽略大小写)
它使测试忽略大小写,扩展后的
TestString
和
CondPattern
中'A-Z' 和'a-z'是没有区别的。此标记仅用于
TestString
和
CondPattern
的比较,而对文件系统和子请求的检查不起作用。
'
ornext|OR
'(或下一条件)
它以OR方式组合若干规则的条件,而不是隐含的AND。典型的例子如下:
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
RewriteCond %{REMOTE_HOST} ^host3.*
RewriteRule ... 针对这3个主机的规则集 ...
如果不用这个标记,你就必须要书写三次条件/规则对。
举例
如果要按请求头中的"
User-Agent:
"重写一个站点的主页,可以这样写:
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/$ /homepage.max.html [L]
RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
RewriteRule ^/$ /homepage.min.html [L]
RewriteRule ^/$ /homepage.std.html [L]
解释:如果你使用的浏览器识别标志是'Mozilla',则你将得到内容最大化的主页(含有Frames等等)。如果你使用的是(基于终端的)Lynx,则你得到的是内容最小化的主页(不含table等等)。如果上述条件都不满足(使用的是其他浏览器),则你得到的是一个标准的主页。
RewriteEngine
指令
说明
打开或关闭运行时的重写引擎
语法
RewriteEngine on|off
默认值
RewriteEngine off
作用域
server config, virtual host, directory, .htaccess
覆盖项
FileInfo
状态
扩展(E)
模块
mod_rewrite
RewriteEngine
指令打开或关闭运行时的重写引擎。如果设置为
off
,则此模块在运行时不执行任何重写操作, 同时也不更新
SCRIPT_URx
环境变量。
使用该指令可以使此模块无效,而无须注释所有的
RewriteRule
指令!
注意:默认情况下,重写配置是不可继承的,也就是必须在每个需要使用重写引擎的虚拟主机中设置一个
RewriteEngine on
指令。
RewriteLock
指令
说明
设置
RewriteMap
同步所使用的锁文件名
语法
RewriteLock
file-path
作用域
server config
状态
扩展(E)
模块
mod_rewrite
此指令设置mod_rewrite为了和
RewriteMap
程序
通讯而使用的同步锁文件的名称。 在需要使用重写映射表程序(rewriting map-program)时,它必须是一个本地路径(而不能是一个NFS挂接设备)。对其他类型的重写映射表(rewriting map),则无此要求。
RewriteLog
指令
说明
设置重写引擎日志的文件名
语法
RewriteLog
file-path
作用域
server config, virtual host
状态
扩展(E)
模块
mod_rewrite
RewriteLog
指令设置用于记录所有重写操作的日志文件的名称。如果此文件名不以斜杠('
/
')开头,则它是相对于
Server Root
的,此指令应该在每个服务器级别的配置中仅仅出现一次。
如果要关闭对重写操作的记录,不推荐将
Filename
设为
/dev/null
,因为,虽然重写引擎不能输出记录了,但仍会在内部建立这个日志文件,
这样会使服务器速度降低,而且对管理员毫无益处!
要关闭日志,可以删除或注解
RewriteLog
指令, 或者使用"
RewriteLogLevel 0
"的设置
安全
参见
安全方面的提示
文档,其中讲述了为什么如果存放日志的目录对除了启动服务器以外的用户是可写的会带来安全隐患。
示例
RewriteLog "/usr/local/var/apache/logs/rewrite.log"
RewriteLogLevel
指令
说明
设置重写日志的详细程度
语法
RewriteLogLevel
Level
默认值
RewriteLogLevel 0
作用域
server config, virtual host
状态
扩展(E)
模块
mod_rewrite
RewriteLogLevel
指令设置重写引擎日志的详细程度的级别。0(默认级别)意味着不记录,而9或更大的值意味着记录所有操作。
要关闭重写引擎日志,可以简单地将
Level
设为0,以关闭所有重写操作的记录。
较高的
Level
值会使Apache服务器速度急剧下降!大于2的
Level
值只用于调试目的!
示例
RewriteLogLevel 3
RewriteMap
指令
说明
定义用于关键词查找的映射函数
语法
RewriteMap
MapName
MapType
:
MapSource
作用域
server config, virtual host
状态
扩展(E)
模块
mod_rewrite
兼容性
Apache 2.0.41 及以后的版本中可以使用不同的dbm类型
RewriteMap
指令定义了一个
映射表
(Rewriting Map),映射函数将使用该表来查找关键字然后插入/替换字段。此查找操作的源可以是多种类型。
MapName
是映射表的名称,指定了一个映射函数,用于重写规则的字符串替换,它可以是下列形式之一:
${
MapName
:
LookupKey
}
${
MapName
:
LookupKey
|
DefaultValue
}
如果使用了这样的形式,则会在
MapName
中查找关键词
LookupKey
。如果找到了,则被替换成
SubstValue
; 如果没有找到,则被替换成
DefaultValue
,如果没有指定
DefaultValue
,则被替换成空字符串。
例如,你可能定义这样一个
RewriteMap
:
RewriteMap examplemap txt:/path/to/file/map.txt
然后你就可以像下面这样在
RewriteRule
中使用该映射:
RewriteRule ^/ex/(.*) ${examplemap:$1}
可以使用下列
MapType
和
MapSource
的组合:
标准纯文本
MapType:
txt
, MapSource: 有效的Unix文件系统文件名
这是重写映射表的标准形式。
MapSource
是一个纯文本文件,包含空行、注释行(以字符'#'打头),以及每行一个的替换对,如下所示:
MatchingKey
SubstValue
例子
## map.txt -- rewriting map
Ralf.S.Engelschall rse # Bastard Operator From Hell
Mr.Joe.Average joe # Mr. Average
RewriteMap real-to-user txt:/path/to/file/map.txt
随机纯文本
MapType:
rnd
, MapSource: 有效的Unix文件系统文件名
这个与上述的标准纯文本很相似,但它有一个特殊的后处理特性:查找完毕后,会解析其中包含的"
|
"符号(含义为"或")。 也就是说,会随机地选择其中之一作为返回值。虽然这看似毫无意义,但设计它的意图是在一个查找值是服务器名称的反向代理环境中实现负载平衡。
例子
映射文件
## map.txt -- rewriting map
static www1|www2|www3|www4
dynamic www5|www6
配置指令
RewriteMap servers rnd:/path/to/file/map.txt
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
散列文件
MapType:
dbm[=
type
]
, MapSource: 有效的Unix文件系统文件名
这里的源是一个二进制格式的DBM文件,包含了与
纯文本
相同的内容,但是因为它有优化了的特殊表现形式,使它的查找速度明显快得多。 此
type
可以是sdbm, gdbm, ndbm, db(由
编译时配置
决定)。如果省略
type
,则使用编译时选择的缺省值。 你可以使用任何DBM工具或者下列Perl脚本来创建这个文件,但必须保证DBM的类型正确。建立NDBM文件的例子如下:
#!/path/to/bin/perl
##
## txt2dbm -- 将 txt 映射表转换为 dbm 格式
##
use NDBM_File;
use Fcntl;
($txtmap, $dbmmap) = @ARGV;
open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
or die "Couldn't create $dbmmap!\n";
while (<TXT>) {
next if (/^\s*#/ or /^\s*$/);
$DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
}
untie %DB;
close(TXT);
$ txt2dbm map.txt map.db
内部函数
MapType:
int
, MapSource: Apache内部函数
这里的源是一个Apache的内部函数。目前,还不能由你自己建立,只能使用下列已经存在的函数:
toupper
:
转换查找关键词为大写
tolower
:
转换查找关键词为小写
escape
:
转换查找关键词中的特殊字符为十六进制编码
unescape
:
转换查找关键词中的十六进制编码为特殊字符
外部的重写程序
MapType:
prg
, MapSource: 有效的Unix文件系统文件名
这里的源是一个程序,而不是一个映射表文件。程序设计语言可以随意选择,但最终结果必须是可执行的(或者是目标代码,或者是首行为'
#!/path/to/interpreter
'的脚本)。
此程序仅在Apache服务器启动时启动一次,随后通过
stdin
和
stdout
文件句柄与重写引擎交互。 对每个映射函数的查找操作,它从
stdin
接收以回车结束的查找关键词,然后把查找的结果以回车结束反馈到
stdout
,如果查找失败,则返回四个字符的字符串"NULL"(对给定的关键词没有对应的值)。此程序的最简单形式是一个1:1的映射(即:key == value),例如:
#!/usr/bin/perl
$| = 1;
while (<STDIN>) {
# ...在这里放置转换和查找...
print $_;
}
但是必须注意:
"
简单就是美
"(KISS: Keep it simple, stupid!)。此程序的崩溃会直接导致Apache服务器的崩溃。
绝不要对
stdout
做I/O缓冲(一个常见的错误),它会导致死循环!所以上述例子中才会使用"
$|=1
"来预防。
使用
RewriteLock
指令定义一个锁文件,用于同步mod_rewrite和此程序之间的通讯。默认是没有同步操作的。
RewriteMap
指令可以多次出现。对每个映射函数都可以使用一个
RewriteMap
指令来定义其重写映射表。虽然不能在目录上下文(per-directory context)中
定义
映射表,但是完全可以在其中
使用
映射表。
注意
对于纯文本和DBM格式的文件,已经查找过的关键词会被缓存在内核中,直到映射表的
mtime
改变了或者服务器重启了。这样,你可以把
每个
请求都会用到的映射函数放在规则中,这是没有问题的,因为外部查找只进行一次。
RewriteOptions
指令
说明
为重写引擎设置一些特殊的选项
语法
RewriteOptions Options
作用域
server config, virtual host, directory, .htaccess
覆盖项
FileInfo
状态
扩展(E)
模块
mod_rewrite
兼容性
MaxRedirects
在2.1及以后的版本中已经不可用
RewriteOptions
指令为当前服务器级和目录级的配置设置一些选项。
Option
当前仅可以是如下值:
inherit
此值强制当前配置继承其父配置。在虚拟主机级配置中,它意味着主服务器的映射表、条件和规则可以被继承。在目录级配置中,它意味着其父目录的
.htaccess
中的条件和规则可以被继承。
RewriteRule
指令
说明
为重写引擎定义重写规则
语法
RewriteRule
Pattern
Substitution
[
flags
]
作用域
server config, virtual host, directory, .htaccess
覆盖项
FileInfo
状态
扩展(E)
模块
mod_rewrite
兼容性
cookie-flag在Apache 2.0.40及以后的版本中可用
RewriteRule
指令是重写引擎的根本。此指令可以多次使用。每个指令定义一个简单的重写规则。这些规则的定义顺序尤为重要——在运行时,规则是按这个顺序逐一生效的。
Pattern
是一个作用于当前URL的perl兼容的
正则表达式。"当前URL"是指该规则生效时刻的URL的值。它可能与被请求的URL截然不同,因为其他规则可能在此之前已经发生匹配并对它做了改动。
正则表达式
的一些用法示例:
文本
.
任意一个单字符
[
chars
]
字符类: "chars"中的任意一个字符
[^
chars
]
字符类: 不在"chars"中的字符
text1
|
text2 选择: text1 或 text2
量词
?
前面的字符出现 0 或 1 次
*
前面的字符出现 0 或 N 次(N > 0)
+
前面的字符出现 1 或 N 次(N > 1)
分组
(
text
)
text 组
(常用于设置一个选择的边界,或用于生成后引用:
在RewriteRule中可以用
$
N
引用第
N
个分组)
锚
^
锚定到行首
$
锚定到行尾
转义
\
c 对给定的字符c进行转义
(比如对"
.[]()
"进行转义,等等)
更多有关正则表达式的资料请参见perl正则表达式手册页("
perldoc perlre
")。另外,在mod_rewrite中,还可以使用否字符('
!
')前缀实现反转。比如:"
如果当前URL
不
与模式相匹配
"它用于使用否定式匹配模式较容易描述的某些情况,或者作为最后一条规则。
注意
使用否字符以反转匹配模式时,匹配模式中不能使用分组的通配成分。由于模式不匹配而使分组的内容是空的,所以它是不可能实现的。 因此,如果使用了否定式匹配模式,那么后继的字符串中就不能使用
$N
重写规则中的
Substitution
是当原始URL与
Pattern
相匹配时,用来替代(或替换)的字符串。除了纯文本,还可以包含:
对
Pattern
的反向引用(
$N
)
对最后匹配的
RewriteCond
的反向引用(
%N
)
规则条件测试字符串(
%{VARNAME}
)中的服务器变量
映射函数
调用(
${mapname:key|default}
)
反向引用的
$
N
(
N
=0..9)是指用
Pattern
匹配的第
N
组的内容去替换URL。服务器变量与
RewriteCond
指令的
TestString
相同。映射函数由
RewriteMap
指令决定,其说明也参见该指令。这三种类型变量按上面列表中的顺序被展开。
如上所述,所有的重写规则都是按配置文件中的定义顺序作用于
Substitution
的。URL被
Substitution
完全替换
,并继续处理直到所有规则处理完毕,除非用
L
标记显式地终结(见下文)。
'
-
'是一个特殊的替换串,意思是
不替换
。它可以用于
仅仅
匹配某些URL而无须替换的情况,比如,在发生替换前,允许以
C
(chain)标记连接的多个匹配模式同时起作用。
此外,在
Substitution
之后还可以追加
[
flags
]
标记作为
RewriteRule
指令的第三个参数。
Flags
是一个包含以逗号分隔的下列标记的列表:
'
chain|C
'(链接下一规则)
此标记使当前规则与下一个规则相链接。它产生这样的效果:如果一个规则被匹配,则继续处理其后继规则,也就是这个标记不起作用;如果该规则
不
被匹配,则其后继规则将被跳过。比如,在一个目录级规则中执行一个外部重定向时,你可能需要删除"
.www
"(此处不应该出现"
.www
")。
'
cookie|CO=
NAME
:
VAL
:
domain
[:
lifetime
[:
path
]]'(设置cookie)
在客户端设置一个cookie。cookie的名称是
NAME
,值是
VAL
。
domain
是该cookie的域,比如'.apache.org',可选的
lifetime
是cookie的有效期(分钟),可选的
path
是cookie的路径。
'
env|E=
VAR
:
VAL
'(设置环境变量)
此标记将环境变量
VAR
的值为
VAL
,
VAL
可以包含可扩展的正则表达式反向引用(
$N
和
%N
)。此标记可以多次使用以设置多个变量。这些变量可以在其后许多情况下被间接引用,通常是在XSSI(
<!--#echo var="VAR"-->
)或CGI(
$ENV{'VAR'}
)中,也可以在后继的
RewriteCond
指令的
CondPattern
参数中通过
%{ENV:VAR}
引用。使用它可以记住从URL中剥离的信息。
'
forbidden|F
'(强制禁止URL)
强制禁止当前URL,也就是立即反馈一个HTTP响应码403(被禁止的)。使用这个标记,可以链接若干个RewriteConds来有条件地阻塞某些URL。
'
gone|G
'(强制废弃URL)
强制当前URL为已废弃,也就是立即反馈一个HTTP响应码410(已废弃的)。使用这个标记,可以标明页面已经被废弃而不存在了。
'
handler|H
=
Content-handler
'(强制指定内容处理器)
强自制定目标文件的内容处理器为
Content-handler
。例如,用来模拟
mod_alias
模块的
ScriptAlias
指令,以强制映射文件夹内的所有文件都由"
cgi-script
"处理器处理。
'
last|L
'(结尾规则)
立即停止重写操作,并不再应用其他重写规则。它对应于Perl中的
last
命令或C语言中的
break
命令。这个标记用于阻止当前已被重写的URL被后继规则再次重写。例如,使用它可以重写根路径的URL('
/
')为实际存在的URL(比如:'
/e/www/
')。
'
next|N
'(从头再来)
重新执行重写操作(从第一个规则重新开始)。此时再次进行处理的URL已经不是原始的URL了,而是经最后一个重写规则处理过的URL。它对应于Perl中的
next
命令或C语言中的
continue
命令。此标记可以重新开始重写操作(立即回到循环的开头)。
但是要小心,不要制造死循环!
'
nocase|NC
'(忽略大小写)
它使
Pattern
忽略大小写,也就是在
Pattern
与当前URL匹配时,'A-Z'和'a-z'没有区别。
'
noescape|NE
'(在输出中不对URI进行转义)
此标记阻止mod_rewrite对重写结果应用常规的URI转义规则。 一般情况下,特殊字符('%', '$', ';'等)会被转义为等值的十六进制编码('%25', '%24', '%3B'等)。此标记可以阻止这样的转义,以允许百分号等符号出现在输出中,比如:
RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
可以使'
/foo/zed
转向到一个安全的请求'
/bar?arg=P1=zed
'。
'
nosubreq|NS
'(不对内部子请求进行处理)
在当前请求是一个内部子请求时,此标记强制重写引擎跳过该重写规则。比如,在
mod_include
试图搜索目录默认文件(
index.xxx
)时,Apache会在内部产生子请求。对于子请求,重写规则不一定有用,而且如果整个规则集都起作用,它甚至可能会引发错误。所以,可以用这个标记来排除某些规则。
使用原则:如果你为URL添加了CGI脚本前缀,以强制它们由CGI脚本处理,但对子请求处理的出错率(或者资源开销)很高,在这种情况下,可以使用这个标记。
'
proxy|P
'(强制为代理)
此标记使替换成分被内部地强制作为代理请求发送,并立即中断重写处理,然后把处理移交给
mod_proxy
模块。你必须确保此替换串是一个能够被
mod_proxy
处理的有效URI(比如以
http://
hostname
开头),否则将得到一个代理模块返回的错误。使用这个标记,可以把某些远程成分映射到本地服务器域名空间,从而增强了
ProxyPass
指令的功能。
注意:要使用这个功能,必须已经启用了
mod_proxy
模块。
'
passthrough|PT
'(移交给下一个处理器)
此标记强制重写引擎将内部
request_rec
结构中的
uri
字段设置为
filename
字段的值,这个小小的修改使得
RewriteRule
指令的输出能够被(从URI转换到文件名的)
Alias
,
ScriptAlias
,
Redirect
等指令进行后续处理[原文:This flag is just a hack to enable post-processing of the output of
RewriteRule
directives, using
Alias
,
ScriptAlias
,
Redirect
, and other directives from various URI-to-filename translators.]。举一个能说明其含义的例子: 如果要将
/abc
重写为
/def
, 然后再使用
mod_alias
将
/def
转换为
/ghi
,可以这样:
RewriteRule ^/abc(.*) /def$1 [PT]
Alias /def /ghi
如果省略了
PT
标记,虽然将
uri=/abc/...
重写为
filename=/def/...
的部分运作正常,但是后续的
mod_alias
在试图将URI转换到文件名时会遭遇失效。
注意:
如果需要混合使用多个将URI转换到文件名的模块时,就必须使用这个标记。
。此处混合使用
mod_alias
和
mod_rewrite
就是个典型的例子。
'
qsappend|QSA
'(追加查询字符串)
此标记强制重写引擎在已有的替换字符串中追加一个查询字符串,而不是简单的替换。如果需要通过重写规则在请求串中增加信息,就可以使用这个标记。
'
redirect|R
[=
code
]
'(强制
重定向)
若
Substitution
以
http://thishost[:thisport]/
(使新的URL成为一个URI)开头,可以强制性执行一个外部重定向。如果没有指定
code
,则产生一个HTTP响应码302(临时性移动)。如果需要使用在300-400范围内的其他响应代码,只需在此指定即可(或使用下列符号名称之一:
temp
(默认),
permanent
,
seeother
)。使用它可以把规范化的URL反馈给客户端,如将"
/~
"重写为"
/u/
",或始终对
/u/
user
加上斜杠,等等。
注意
:在使用这个标记时,必须确保该替换字段是一个有效的URL。否则,它会指向一个无效的位置!并且要记住,此标记本身只是对URL加上
http://thishost[:thisport]/
前缀,重写操作仍然会继续进行。通常,你还会希望停止重写操作而立即重定向,那么就还需要使用'L'标记。
'
skip|S
=
num
'(跳过后继规则)
此标记强制重写引擎跳过当前匹配规则之后的
num
个规则。它可以模拟if-then-else结构:最后一个规则是then从句,而被跳过的
skip=N
个规则是else从句。注意:它和'chain|C'标记是不同的!
'
type|T
=
MIME-type
'(强制MIME类型)
强制目标文件的
MIME类型
为
MIME-type
,可以用来基于某些特定条件强制设置内容类型。比如,下面的指令可以让
.php
文件在以
.phps
扩展名调用的情况下由
mod_php
按照PHP源代码的MIME类型(application/x-httpd-php-source)显示:
RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
目录级重写
为了在
.htaccess
文件中针对特定目录使用重写引擎,你必须
同时
设置"
RewriteEngine On
"和"
Options FollowSymLinks
"。如果管理员禁止了该目录的
FollowSymLinks
特性,重写引擎将不会工作,这样做的原因是处于安全方面的考虑。
在服务器级配置中,模式匹配是作用于整个URL的。但是在目录级配置文件
.htaccess
中使用重写引擎的时候,目录前缀(一般总是和特定的目录名称相同)将会在模式匹配前被自动
移除
并在替换完成后被自动
添加
回去。这个特性对于重写来说是非常重要的,否则你就被迫必须总是对父目录进行匹配,而这并不总是可行的。这里有一个例外:如果替换字符串以"
http://
"开头,则
不会
添加目录前缀,而是强制执行一个外部重定向或代理操作(如果使用了
P
标志的话)。参见
RewriteBase
指令以获得更多信息。
还可以在
<Directory>
配置段中使用重写引擎,前缀匹配规则与在
.htaccess
中使用重写引擎时完全相同,并且这种做法更加简单。然而,为了避免前缀替换复杂化,我们还是建议尽量将重写规则放置在主服务器或虚拟主机配置部分,而不是放置在
<Directory>
配置段中。
虽然重写规则在语法上允许放置在
<Location>
配置段中,但这不是必须的,并且我们也反对这样做。
注意:绝对URL的替换
当替换字段以"
http://thishost[:thisport]
"作为前缀时,
mod_rewrite
会将它自动剥离出去。在配合生成主机名部分的映射函数使用的时候,这个对隐含的外部重定向URL的简化操作是有用的而且是重要的。下面的第一个例子有助于理解这点。
谨记
:由于此功能的存在,以"
http://thishost
"为前缀的无条件外部重定向到自身所在的服务器是无效的。要实现一个到自身的重定向,必须使用
R
标记。
注意:查询字符串
Pattern
不会按照查询字符串进行匹配。为了达到这个目的,你必须使用一个带有
%{QUERY_STRING}
变量的
RewriteCond
指令。当然,你也可以在替换字符串中创建包含查询字符串的URL:在替换字符串串中使用问号,以标明其后的部分应该被重新注入到QUERY_STRING中。而要删除一个已有的请求串,则可以用问号来终结替换字符串。为了联合新旧查询字符串,请使用
[QSA]
标志。
以下是所有可能的替换组合及其含义:
在服务器级配置中(
httpd.conf
)
对给定的请求"
GET /somepath/pathinfo
":
给定的规则
得到的替换字符串
---------------------------------------------- ----------------------------------
^/somepath(.*) otherpath$1 非法,不被支持
^/somepath(.*) otherpath$1 [R] 非法,不被支持
^/somepath(.*) otherpath$1 [P] 非法,不被支持
---------------------------------------------- ----------------------------------
^/somepath(.*) /otherpath$1 /otherpath/pathinfo
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
通过外部重定向
^/somepath(.*) /otherpath$1 [P] 毫无意义,不被支持
---------------------------------------------- ----------------------------------
^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
通过外部重定向
^/somepath(.*) http://thishost/otherpath$1 [P] 毫无意义,不被支持
---------------------------------------------- ----------------------------------
^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
通过外部重定向
^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
通过外部重定向
([R]标记是多余的)
^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
通过内部代理
在
/somepath
的目录级配置中
(也就是
/physical/path/to/somepath/.htacccess
文件中含有:
RewriteBase /somepath
)
对给定的请求"
GET /somepath/localpath/pathinfo
"
随机文章:
[转]URL重写(4)高级URL重写指南
2007-08-02
[转]URL重写(3)初级URL重写指南
2007-08-02
[转]URL重写(2)简介&&技术细节
2007-08-02
rewrite重定向
2007-01-18
域名泛解析详解
2007-09-26
收藏到:
Del.icio.us
引用地址:
adriano_lee
发表于
16:54:16
|
编辑
|
继续话题
|
转发
|
推荐
发表评论
原始快照:web.archive.org