mod_rewrite.html.en

Apache官方在今天放出产品系列2.2的最新版本2.2.11的源码包 最流行的HTTP服务器软件之一

<div class="note"><h3>Note</h3>
When using the NOT character to negate a pattern, you cannot include 
grouped wildcard parts in that pattern. This is because, when the 
pattern does NOT match (ie, the negation matches), there are no 
contents for the groups. Thus, if negated patterns are used, you
cannot use <code>$N</code> in the substitution string!
</div>

      <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
      rewrite rule is the string that replaces the original URL-path that
      was matched by <em>Pattern</em>.  The <em>Substitution</em> may
      be a:</p>

      <dl>

        <dt>file-system path</dt>

        <dd>Designates the location on the file-system of the resource
        to be delivered to the client.</dd>

        <dt>URL-path</dt> 

        <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
        resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
        tries to guess whether you have specified a file-system path
        or a URL-path by checking to see if the first segment of the
        path exists at the root of the file-system. For example, if
        you specify a <em>Substitution</em> string of
        <code>/www/file.html</code>, then this will be treated as a
        URL-path <em>unless</em> a directory named <code>www</code>
        exists at the root or your file-system, in which case it will
        be treated as a file-system path. If you wish other
        URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
        resulting URL-path, use the <code>[PT]</code> flag as
        described below.</dd>

        <dt>Absolute URL</dt>

        <dd>If an absolute URL is specified,
        <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
        hostname matches the current host. If it does, the scheme and
        hostname are stripped out and the resulting path is treated as
        a URL-path. Otherwise, an external redirect is performed for
        the given URL. To force an external redirect back to the
        current host, see the <code>[R]</code> flag below.</dd>

        <dt><code>-</code> (dash)</dt>

        <dd>A dash indicates that no substitution should be performed
        (the existing path is passed through untouched). This is used
        when a flag (see below) needs to be applied without changing
        the path.</dd>

      </dl>

      <p>In addition to plain text, the <em>Substition</em> string can include</p>

      <ol>
        <li>back-references (<code>$N</code>) to the RewriteRule
        pattern</li>

        <li>back-references (<code>%N</code>) to the last matched
        RewriteCond pattern</li>

        <li>server-variables as in rule condition test-strings
        (<code>%{VARNAME}</code>)</li>

        <li><a href="#mapfunc">mapping-function</a> calls
        (<code>${mapname:key|default}</code>)</li>
      </ol>

      <p>Back-references are identifiers of the form 
	      <code>$</code><strong>N</strong>
      (<strong>N</strong>=0..9), which will be replaced
      by the contents of the <strong>N</strong>th group of the
      matched <em>Pattern</em>. The server-variables are the same
      as for the <em>TestString</em> of a <code>RewriteCond</code>
      directive. The mapping-functions come from the
      <code>RewriteMap</code> directive and are explained there.
      These three types of variables are expanded in the order above.</p>

      <p>As already mentioned, all rewrite rules are
      applied to the <em>Substitution</em> (in the order in which 
      they are defined
      in the config file). The URL is <strong>completely
      replaced</strong> by the <em>Substitution</em> and the
      rewriting process continues until all rules have been applied,
      or it is explicitly terminated by a
      <code><strong>L</strong></code> flag.</p>

     <div class="note"><h3>Modifying the Query String</h3>
      <p>By default, the query string is passed through unchanged. You
      can, however, create URLs in the substitution string containing
      a query string part. Simply use a question mark inside the
      substitution string to indicate that the following text should
      be re-injected into the query string. When you want to erase an
      existing query string, end the substitution string with just a
      question mark. To combine new and old query strings, use the
      <code>[QSA]</code> flag.</p> 
     </div>


      <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by 
      appending <strong><code>[</code><em>flags</em><code>]</code></strong>
      as the third argument to the <code>RewriteRule</code>
      directive. <em>Flags</em> is a comma-separated list, surround by square 
      brackets, of any of the following flags: </p>

      <dl>
        <dt>'<code>B</code>' (escape backreferences)</dt>
        <dd><p>Apache has to unescape URLs before mapping them,
        so backreferences will be unescaped at the time they are applied.
        Using the B flag, non-alphanumeric characters in backreferences
        will be escaped.  For example, consider the rule:</p>
        <pre><code> RewriteRule ^(.*)$ index.php?show=$1 </code></pre>
        <p>This will map <code>/C++</code> to <code>index.php?show=/C++</code>.
        But it will also map <code>/C%2b%2b</code> to
        <code>index.php?show=/C++</code>, because the <code>%2b</code>
        has been unescaped.  With the B flag, it will instead map to
        <code>index.php?show=/C%2b%2b</code>.</p>
        <p>This escaping is particularly necessary in a proxy situation,
        when the backend may break if presented with an unescaped URL.</p>
        </dd>

        <dt>'<code>chain|C</code>'
        (chained with next rule)</dt><dd>
         This flag chains the current rule with the next rule
        (which itself can be chained with the following rule,
        and so on). This has the following effect: if a rule
        matches, then processing continues as usual - 
        the flag has no effect. If the rule does
        <strong>not</strong> match, then all following chained
        rules are skipped. For instance, it can be used to remove the
        ``<code>.www</code>'' part, inside a per-directory rule set,
        when you let an external redirect happen (where the
        ``<code>.www</code>'' part should not occur!).</dd>

        <dt>'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]]'
        (set cookie)</dt><dd>
        This sets a cookie in the client's browser.  The cookie's name
        is specified by <em>NAME</em> and the value is
        <em>VAL</em>. The <em>domain</em> field is the domain of the
        cookie, such as '.apache.org', the optional <em>lifetime</em>
        is the lifetime of the cookie in minutes, and the optional 
        <em>path</em> is the path of the cookie. If <em>secure</em>
        is set to 'secure', 'true' or '1', the cookie is only transmitted via secured
        connections. If <em>httponly</em> is set to 'HttpOnly', 'true' or '1', the
        <code>HttpOnly</code> flag is used, making the cookie not accessible
        to JavaScript code on browsers that support this feature.</dd>

        <dt>
        '<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
        (set environment variable)</dt><dd>
        This forces an environment variable named <em>VAR</em> to
        be set to the value <em>VAL</em>, where <em>VAL</em> can
        contain regexp backreferences (<code>$N</code> and
        <code>%N</code>) which will be expanded. You can use this
        flag more than once, to set more than one variable. The
        variables can later be dereferenced in many situations, most commonly
	from within XSSI (via <code>&lt;!--#echo
        var="VAR"--&gt;</code>) or CGI (<code>$ENV{'VAR'}</code>). 
	You can also dereference the variable in a later RewriteCond pattern, using
        <code>%{ENV:VAR}</code>. Use this to strip 
        information from URLs, while maintaining a record of that information.</dd>

        <dt>'<code>forbidden|F</code>' (force URL
        to be forbidden)</dt><dd>
        This forces the current URL to be forbidden - it immediately 
	sends back a HTTP response of 403 (FORBIDDEN). 
	Use this flag in conjunction with
        appropriate RewriteConds to conditionally block some
        URLs.</dd>

        <dt>'<code>gone|G</code>' (force URL to be
        gone)</dt><dd>
        This forces the current URL to be gone - it
        immediately sends back a HTTP response of 410 (GONE). Use
        this flag to mark pages which no longer exist as gone.</dd>

        <dt>
        '<code>handler|H</code>=<em>Content-handler</em>'
        (force Content handler)</dt><dd>
         Force the Content-handler of the target file to be
        <em>Content-handler</em>. For instance, this can be used to
        simulate the <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directive
	<code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, 
	which internally forces all files
        inside the mapped directory to have a handler of
        ``<code>cgi-script</code>''.</dd>

        <dt>'<code>last|L</code>'
        (last rule)</dt><dd> Stop the rewriting process
        here and don't apply any more rewrite rules. This corresponds
        to the Perl <code>last</code> command or the
        <code>break</code> command in C. Use this flag to prevent the
        currently rewritten URL from being rewritten further by
        following rules. Remember, however, that if the
        <code class="directive">RewriteRule</code> generates an internal
        redirect (which frequently occurs when rewriting in a
        per-directory context), this will reinject the request and
        will cause processing to be repeated starting from the first
        <code class="directive">RewriteRule</code>.</dd>

        <dt>'<code>next|N</code>'
        (next round)</dt><dd>
        Re-run the rewriting process (starting again with the
        first rewriting rule). This time, the URL to match is no longer
        the original URL, but rather the URL returned by the last rewriting rule.
        This corresponds to the Perl <code>next</code> command or
        the <code>continue</code> command in C. Use
        this flag to restart the rewriting process -
        to immediately go to the top of the loop.
         <strong>Be careful not to create an infinite
        loop!</strong></dd>

        <dt>'<code>nocase|NC</code>'
        (no case)</dt><dd>
        This makes the <em>Pattern</em> case-insensitive,
        ignoring difference between 'A-Z' and
        'a-z' when <em>Pattern</em> is matched against the current
        URL.</dd>

        <dt>
          '<code>noescape|NE</code>'
          (no URI escaping of
          output)</dt><dd>
          This flag prevents mod_rewrite from applying the usual URI
          escaping rules to the result of a rewrite. Ordinarily,
          special characters (such as '%', '$', ';', and so on)
          will be escaped into their hexcode equivalents ('%25',
          '%24', and '%3B', respectively); this flag prevents this
          from happening. This allows percent symbols to appear in
          the output, as in 
<div class="example"><p><code>
    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
</code></p></div>
          which would turn '<code>/foo/zed</code>' into a safe
          request for '<code>/bar?arg=P1=zed</code>'. 
        </dd>

        <dt>
          '<code>nosubreq|NS</code>'
          (not for internal
          sub-requests)</dt><dd>
          <p>This flag forces the rewriting engine to skip a
          rewriting rule if the current request is an internal
          sub-request. For instance, sub-requests occur internally
          in Apache when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> tries to find out
          information about possible directory default files
          (<code>index.xxx</code> files). On sub-requests it is not
          always useful, and can even cause errors, if
          the complete set of rules are applied. Use this flag to
          exclude some rules.</p>
          <p>To decide whether or not to use this rule: if you
          prefix URLs with CGI-scripts, to force them to be
	  processed by the CGI-script, it's likely that you 
          will run into problems (or significant overhead) on
          sub-requests. In these cases, use this flag.</p>
        </dd>

        <dt>
          '<code>proxy|P</code>' (force
          proxy)</dt><dd>
          This flag forces the substitution part to be internally
	  sent as a proxy request and immediately (rewrite 
	  processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
          sure that the substitution string is a valid URI
          (typically starting with
          <code>http://</code><em>hostname</em>) which can be
          handled by the Apache proxy module. If not, you will get an
          error from the proxy module. Use this flag to achieve a