mod_rewrite.html.en

来自「apache的软件linux版本」· EN 代码 · 共 1,362 行 · 第 1/5 页

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, with
      each instance defining a single rewrite rule. The
      order in which these rules are defined is important - this is the order
      in which they will be applied 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 is applied to the current URL.
      ``Current'' means the value of the URL when this rule is
      applied. This may not be the originally requested URL,
      which may already have matched a previous rule, and have
      been altered.</p>

      <p>Some hints on 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: Any character of the class ``chars''
  <strong><code>[^</code></strong>chars<strong><code>]</code></strong>    Character class: Not a character of the class ``chars''
  text1<strong><code>|</code></strong>text2 Alternative: text1 or text2

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

<strong>Grouping:</strong>
  <strong><code>(</code></strong>text<strong><code>)</code></strong>      Grouping of text
              (used either to set the borders of an alternative as above, or
              to make backreferences, where the <strong>N</strong>th group can
              be referred to on the RHS of a RewriteRule as <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 the given 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://perldoc.perl.org/perlre.html">perldoc
      perlre</a>"). If you are interested in more detailed
      information about regular expressions and their variants
      (POSIX regex etc.) the following book is dedicated to 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>In mod_rewrite, the NOT character	
       ('<code>!</code>') is also available as a possible pattern 
      prefix. This enables you 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>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 which is substituted for (or
      replaces) the original URL which <em>Pattern</em>
      matched. In addition to plain text, it 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 - see below.</p>

      <p>There is a special substitution string named
      '<code>-</code>' which means: <strong>NO
      substitution</strong>! This is useful in providing
      rewriting rules which <strong>only</strong> match
      URLs but do not substitute anything for them. It is commonly used
      in conjunction with the <strong>C</strong> (chain) flag, in order
      to apply more than one pattern before substitution occurs.</p>

      <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> 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 of any of the
      following flags: </p>

      <ul>
        <li>'<strong><code>chain|C</code></strong>'
        (<strong>c</strong>hained with next rule)<br />
         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!).</li>

        <li>
		'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
        (set <strong>co</strong>okie)<br />
        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</li>

        <li>
        '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
        (set <strong>e</strong>nvironment variable)<br />
        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.</li>

        <li>'<strong><code>forbidden|F</code></strong>' (force URL
        to be <strong>f</strong>orbidden)<br />
        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.</li>

        <li>'<strong><code>gone|G</code></strong>' (force URL to be
        <strong>g</strong>one)<br />
        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.</li>

       <li>'<strong><code>last|L</code></strong>'
        (<strong>l</strong>ast rule)<br />
         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. For example, use it to rewrite the root-path URL
        ('<code>/</code>') to a real one, <em>e.g.</em>,
        '<code>/e/www/</code>'.</li>

        <li>'<strong><code>next|N</code></strong>'
        (<strong>n</strong>ext round)<br />
        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.<br />
         <strong>Be careful not to create an infinite
        loop!</strong></li>

        <li>'<strong><code>nocase|NC</code></strong>'
        (<strong>n</strong>o <strong>c</strong>ase)<br />
        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.</li>

        <li>
          '<strong><code>noescape|NE</code></strong>'
          (<strong>n</strong>o URI <strong>e</strong>scaping of
          output)<br />
           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>'. 
        </li>

        <li>
          '<strong><code>nosubreq|NS</code></strong>' (
          <strong>n</strong>ot for internal
          <strong>s</strong>ub-requests)<br />
           This f