mod_rewrite.html.en

Apache HTTP Server 是一个功能强大的灵活的与HTTP/1.1相兼容的web服务器.这里给出的是Apache HTTP服务器的源码。

          receive the key to lookup as a newline-terminated string
          on <code>stdin</code>. It then has to give back the
          looked-up value as a newline-terminated string on
          <code>stdout</code> or the four-character string
          ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
          is no corresponding value for the given key). A trivial
          program which will implement a 1:1 map (<em>i.e.</em>,
          key == value) could be:</p>

<div class="example"><pre>
#!/usr/bin/perl
$| = 1;
while (&lt;STDIN&gt;) {
    # ...put here any transformations or lookups...
    print $_;
}
</pre></div>

          <p>But be very careful:</p>

          <ol>
            <li>``<em>Keep it simple, stupid</em>'' (KISS), because
            if this program hangs it will hang the Apache server
            when the rule occurs.</li>

            <li>Avoid one common mistake: never do buffered I/O on
            <code>stdout</code>! This will cause a deadloop! Hence
            the ``<code>$|=1</code>'' in the above example...</li>

            <li>Use the <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive to
            define a lockfile mod_rewrite can use to synchronize the
            communication to the program. By default no such
            synchronization takes place.</li>
          </ol>
        </li>
      </ul>
      <p>The <code class="directive">RewriteMap</code> directive can occur more than
      once. For each mapping-function use one
      <code class="directive">RewriteMap</code> directive to declare its rewriting
      mapfile. While you cannot <strong>declare</strong> a map in
      per-directory context it is of course possible to
      <strong>use</strong> this map in per-directory context. </p>

<div class="note"><h3>Note</h3> For plain text and DBM format files the
looked-up keys are cached in-core until the <code>mtime</code> of the
mapfile changes or the server does a restart. This way you can have
map-functions in rules which are used for <strong>every</strong>
request.  This is no problem, because the external lookup only happens
once!
</div>


</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteOptions MaxRedirects=10</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is available in Apache 2.0.45 and
later</td></tr>
</table>

      <p>The <code class="directive">RewriteOptions</code> directive sets some
      special options for the current per-server or per-directory
      configuration. The <em>Option</em> strings can be one of the
      following:</p>

      <dl>
      <dt><code>inherit</code></dt>
      <dd>This forces the current configuration to inherit the
      configuration of the parent. In per-virtual-server context
      this means that the maps, conditions and rules of the main
      server are inherited. In per-directory context this means
      that conditions and rules of the parent directory's
      <code>.htaccess</code> configuration are inherited.</dd>

      <dt><code>MaxRedirects=<var>number</var></code></dt>
      <dd>In order to prevent endless loops of internal redirects
      issued by per-directory <code class="directive"><a href="#rewriterule">RewriteRule</a></code>s, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> aborts
      the request after reaching a maximum number of such redirects and
      responds with an 500 Internal Server Error. If you really need
      more internal redirects than 10 per request, you may increase
      the default to the desired value.</dd>
      </dl>

</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
      <em>Pattern</em> <em>Substitution</em></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
</table>
      <p>The <code class="directive">RewriteRule</code> directive is the real
      rewriting workhorse. The directive can occur more than once.
      Each directive then defines one single rewriting rule. The
      <strong>definition order</strong> of these rules is
      <strong>important</strong>, because this order is used when
      applying the rules at run-time.</p>

      <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
      a perl compatible <a id="regexp" name="regexp">regular
      expression</a> which gets applied to the current URL. Here
      ``current'' means the value of the URL when this rule gets
      applied. This may not be the originally requested URL,
      because any number of rules may already have matched and made
      alterations to it.</p>

      <p>Some hints about the syntax of regular expressions:</p>

<div class="note"><pre>
<strong>Text:</strong>
  <strong><code>.</code></strong>           Any single character
  <strong><code>[</code></strong>chars<strong><code>]</code></strong>     Character class: One  of chars
  <strong><code>[^</code></strong>chars<strong><code>]</code></strong>    Character class: None of chars
  text1<strong><code>|</code></strong>text2 Alternative: text1 or text2

<strong>Quantifiers:</strong>
  <strong><code>?</code></strong>           0 or 1 of the preceding text
  <strong><code>*</code></strong>           0 or N of the preceding text (N &gt; 0)
  <strong><code>+</code></strong>           1 or N of the preceding text (N &gt; 1)

<strong>Grouping:</strong>
  <strong><code>(</code></strong>text<strong><code>)</code></strong>      Grouping of text
              (either to set the borders of an alternative or
              for making backreferences where the <strong>N</strong>th group can 
              be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>)

<strong>Anchors:</strong>
  <strong><code>^</code></strong>           Start of line anchor
  <strong><code>$</code></strong>           End   of line anchor

<strong>Escaping:</strong>
  <strong><code>\</code></strong>char       escape that particular char
              (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>)
</pre></div>

      <p>For more information about regular expressions have a look at the
      perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
      perlre</a>"). If you are interested in more detailed
      information about regular expressions and their variants
      (POSIX regex <em>etc.</em>) have a look at the
      following dedicated book on this topic:</p>

      <p class="indent">
        <em>Mastering Regular Expressions, 2nd Edition</em><br />
         Jeffrey E.F. Friedl<br />
         O'Reilly &amp; Associates, Inc. 2002<br />
         ISBN 0-596-00289-0<br />
      </p>

      <p>Additionally in mod_rewrite the NOT character
      ('<code>!</code>') is a possible pattern prefix. This gives
      you the ability to negate a pattern; to say, for instance:
      ``<em>if the current URL does <strong>NOT</strong> match this
      pattern</em>''. This can be used for exceptional cases, where
      it is easier to match the negative pattern, or as a last
      default rule.</p>

<div class="note"><h3>Notice</h3>
When using the NOT character
          to negate a pattern you cannot have grouped wildcard
          parts in the pattern. This is impossible because when the
          pattern does NOT match, there are no contents for the
          groups. In consequence, if negated patterns are used, you
          cannot use <code>$N</code> in the substitution
          string!
</div>

      <p><a id="rhs" name="rhs"><em>Substitution</em></a> of a
      rewriting rule is the string which is substituted for (or
      replaces) the original URL for which <em>Pattern</em>
      matched. Beside plain text you can use</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 <code>$</code><strong>N</strong>
      (<strong>N</strong>=0..9) identifiers 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 of
      the above list. </p>

      <p>As already mentioned above, all the rewriting rules are
      applied to the <em>Substitution</em> (in the order of
      definition in the config file). The URL is <strong>completely
      replaced</strong> by the <em>Substitution</em> and the
      rewriting process goes on until there are no more rules
      unless explicitly terminated by a
      <code><strong>L</strong></code> flag - see below.</p>

      <p>There is a special substitution string named
      '<code>-</code>' which means: <strong>NO
      substitution</strong>! Sounds silly? No, it is useful to
      provide rewriting rules which <strong>only</strong> match
      some URLs but do no substitution, <em>e.g.</em>, in
      conjunction with the <strong>C</strong> (chain) flag to be
      able to have more than one pattern to be applied before a
      substitution occurs.</p>

<div class="note"><h3>Query String</h3>
      <p>The <em>Pattern</em> will not match against the query string.
      Instead, you must use a <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
      <code>%{QUERY_STRING}</code> variable.  You can, however, create
      URLs in the substitution string containing a query string
      part. Just use a question mark inside the substitution string to
      indicate that the following stuff should be re-injected into the
      query string. When you want to erase an existing query string,
      end the substitution string with just the question mark.  To
      combine a new query string with an old one, use the
      <code>[QSA]</code> flag (see below).</p>
</div>

<div class="note"><h3>Substitution of Absolute URLs</h3>
          <p>There is a special feature:
          When you prefix a substitution field with
          <code>http://</code><em>thishost</em>[<em>:thisport</em>]
          then <strong>mod_rewrite</strong> automatically strips it
          out. This auto-reduction on implicit external redirect
          URLs is a useful and important feature when used in
          combination with a mapping-function which generates the
          hostname part. Have a look at the first example in the
          example section below to understand this.</p>

          <p><strong>Remember:</strong> An unconditional external
          redirect to your own server will not work with the prefix
          <code>http://thishost</code> because of this feature. To
          achieve such a self-redirect, you have to use the
          <strong>R</strong>-flag (see below).</p>
</div>

      <p>Additionally you can set special flags for
      <em>Substitution</em> by appending</p>

      <p class="indent">
        <strong><code>[</code><em>flags</em><code>]</code></strong>
      </p>
      <p>
      as the third argument to the <code>RewriteRule</code>
      directive. <em>Flags</em> is a comma-separated list of the
      following flags: </p>

      <ul>
        <li>
          '<strong><code>redirect|R</code>
          [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
           Prefix <em>Substitution</em> with
          <code>http://thishost[:thisport]/</code> (which makes the
          new URL a URI) to force a external redirection. If no
          <em>code</em> is given a HTTP response of 302 (MOVED
          TEMPORARILY) is used. If you want to use other response
          codes in the range 300-400 just specify them as a number
          or use one of the following symbolic names:
          <code>temp</code> (default), <code>permanent</code>,
          <code>seeother</code