Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_rewrite_module.xml @ 1387:afe06879971a
Donor added.
author | Maxim Konovalov <maxim@nginx.com> |
---|---|
date | Tue, 13 Jan 2015 09:19:14 +0000 |
parents | cb63563024eb |
children | 065978f4ece1 |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_rewrite_module" link="/ru/docs/http/ngx_http_rewrite_module.html" lang="ru" rev="5"> <section id="summary"> <para> Модуль <literal>ngx_http_rewrite_module</literal> позволяет изменять URI запроса с помощью регулярных выражений, делать перенаправления и выбирать конфигурацию по условию. </para> <para> Директивы модуля <literal>ngx_http_rewrite_module</literal> обрабатываются в следующем порядке: <list type="bullet"> <listitem> последовательно выполняются директивы этого модуля, описанные на уровне <link doc="ngx_http_core_module.xml" id="server"/>; </listitem> <listitem> в цикле: <list type="bullet"> <listitem> ищется <link doc="ngx_http_core_module.xml" id="location"/> по URI запроса; </listitem> <listitem> последовательно выполняются директивы этого модуля, описанные в найденном location; </listitem> <listitem> цикл повторяется, если URI запроса <link id="rewrite">изменялся</link>, но не более <link doc="ngx_http_core_module.xml" id="internal">10 раз</link>. </listitem> </list> </listitem> </list> </para> </section> <section id="directives" name="Директивы"> <directive name="break"> <syntax/> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal>. </para> <para> Если директива указана внутри <link doc="ngx_http_core_module.xml" id="location"/>, дальнейшая обработка запроса продолжается в этом location. </para> <para> Пример: <example> if ($slow) { limit_rate 10k; break; } </example> </para> </directive> <directive name="if"> <syntax block="yes">(<value>условие</value>)</syntax> <default/> <context>server</context> <context>location</context> <para> Проверяется указанное <value>условие</value>. Если оно истинно, то выполняются указанные в фигурных скобках директивы этого модуля и запросу назначается конфигурация, указанная внутри директивы <literal>if</literal>. Конфигурации внутри директив <literal>if</literal> наследуются с предыдущего уровня конфигурации. </para> <para> В качестве условия могут быть заданы: <list type="bullet"> <listitem> имя переменной; ложными значениями переменной являются пустая строка или “<literal>0</literal>”; <note> До версии 1.0.1 ложным значением также являлась любая строка, начинающаяся на “<literal>0</literal>”. </note> </listitem> <listitem> сравнение переменной со строкой с помощью операторов “<literal>=</literal>” и “<literal>!=</literal>”; </listitem> <listitem> соответствие переменной регулярному выражению с учётом регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”. В регулярных выражениях можно использовать выделения, которые затем доступны в виде переменных <var>$1</var>..<var>$9</var>. Также можно использовать отрицательные операторы “<literal>!~</literal>” и “<literal>!~*</literal>”. Если в регулярном выражении встречаются символы “<literal>}</literal>” или “<literal>;</literal>”, то всё выражение следует заключить в одинарные или двойные кавычки. </listitem> <listitem> проверка существования файла с помощью операторов “<literal>-f</literal>” и “<literal>!-f</literal>”; </listitem> <listitem> проверка существования каталога с помощью операторов “<literal>-d</literal>” и “<literal>!-d</literal>”; </listitem> <listitem> проверка существования файла, каталога или символической ссылки с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”; </listitem> <listitem> проверка исполняемости файла с помощью операторов “<literal>-x</literal>” и “<literal>!-x</literal>”. </listitem> </list> </para> <para> Примеры: <example> if ($http_user_agent ~ MSIE) { rewrite ^(.*)$ /msie/$1 break; } if ($http_cookie ~* "id=([^;]+)(?:;|$)") { set $id $1; } if ($request_method = POST) { return 405; } if ($slow) { limit_rate 10k; } if ($invalid_referer) { return 403; } </example> <note> Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. </note> </para> </directive> <directive name="return"> <syntax><value>код</value> [<value>текст</value>]</syntax> <syntax><value>код</value> <value>URL</value></syntax> <syntax><value>URL</value></syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Завершает обработку и возвращает клиенту указанный <value>код</value>. Нестандартный код 444 закрывает соединение без передачи заголовка ответа. </para> <para> Начиная с версии 0.8.42 можно задать либо URL перенаправления (для кодов 301, 302, 303 и 307), либо <value>текст</value> тела ответа (для остальных кодов). В тексте тела ответа и URL перенаправления можно использовать переменные. Как частный случай, URL перенаправления может быть задан как URI, локальный для данного сервера, при этом полный URL перенаправления формируется согласно схеме запроса (<var>$scheme</var>) и директивам <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> и <link doc="ngx_http_core_module.xml" id="port_in_redirect"/>. </para> <para> Кроме того, в качестве единственного параметра можно указать <value>URL</value> для временного перенаправления с кодом 302. Такой параметр должен начинаться со строк “<literal>http://</literal>”, “<literal>https://</literal>” или “<literal>$scheme</literal>”. В <value>URL</value> можно использовать переменные. </para> <para> <note> До версии 0.7.51 можно было возвращать только следующие коды: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. </note> <note> До версий 1.1.16 и 1.0.13 код 307 не обрабатывался как перенаправление. </note> </para> <para> См. также директиву <link doc="ngx_http_core_module.xml" id="error_page"/>. </para> </directive> <directive name="rewrite"> <syntax> <value>regex</value> <value>замена</value> [<value>флаг</value>]</syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Если указанное регулярное выражение соответствует URI запроса, URI изменяется в соответствии со строкой замены. Директивы <literal>rewrite</literal> выполняются последовательно, в порядке их следования в конфигурационном файле. С помощью флагов можно прекратить дальнейшую обработку директив. Если строка замены начинается с “<literal>http://</literal>” или “<literal>https://</literal>”, то обработка завершается и клиенту возвращается перенаправление. </para> <para> Необязательный параметр <value>флаг</value> может быть одним из: <list type="tag"> <tag-name><literal>last</literal></tag-name> <tag-desc> завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal>, после чего ищется новый location, соответствующий изменённому URI; </tag-desc> <tag-name><literal>break</literal></tag-name> <tag-desc> завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal> аналогично директиве <link id="break"/>; </tag-desc> <tag-name><literal>redirect</literal></tag-name> <tag-desc> возвращает временное перенаправление с кодом 302; используется, если заменяющая строка не начинается с “<literal>http://</literal>” или “<literal>https://</literal>”; </tag-desc> <tag-name><literal>permanent</literal></tag-name> <tag-desc> возвращает постоянное перенаправление с кодом 301. </tag-desc> </list> Полный URL перенаправлений формируется согласно схеме запроса (<var>$scheme</var>) и директив <link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> и <link doc="ngx_http_core_module.xml" id="port_in_redirect"/>. </para> <para> Пример: <example> server { ... rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; return 403; ... } </example> </para> <para> Если же эти директивы поместить в location “<literal>/download/</literal>”, то нужно заменить флаг <literal>last</literal> на <literal>break</literal>, иначе nginx сделает 10 циклов и вернёт ошибку 500: <example> location /download/ { rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; return 403; } </example> </para> <para> Если в строке замены указаны новые аргументы запроса, то предыдущие аргументы запроса добавляются после них. Если такое поведение нежелательно, можно отказаться от этого добавления, указав в конце строки замены знак вопроса, например: <example> rewrite ^/users/(.*)$ /show?user=$1? last; </example> </para> <para> Если в регулярном выражении встречаются символы “<literal>}</literal>” или “<literal>;</literal>”, то всё выражение следует заключить в одинарные или двойные кавычки. </para> </directive> <directive name="rewrite_log"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <context>if</context> <para> Разрешает или запрещает записывать в <link doc="../ngx_core_module.xml" id="error_log"/> на уровне <literal>notice</literal> результаты обработки директив модуля <literal>ngx_http_rewrite_module</literal>. </para> </directive> <directive name="set"> <syntax><value>$переменная</value> <value>значение</value></syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Устанавливает значение указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации. </para> </directive> <directive name="uninitialized_variable_warn"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>on</default> <context>http</context> <context>server</context> <context>location</context> <context>if</context> <para> Определяет, нужно ли писать в лог предупреждения о неинициализированных переменных. </para> </directive> </section> <section id="internals" name="Внутреннее устройство"> <para> Директивы модуля <literal>ngx_http_rewrite_module</literal> компилируются на стадии конфигурации во внутренние инструкции, интерпретируемые во время обработки запроса. Интерпретатор представляет из себя простую стековую виртуальную машину. </para> <para> Например, директивы <example> location /download/ { if ($forbidden) { return 403; } if ($slow) { limit_rate 10k; } rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; } </example> будут транслированы в такие инструкции: <example> переменная $forbidden проверка на ноль возврат 403 завершение всего кода переменная $slow проверка на ноль проверка регулярного выражения копирование "/" копирование $1 копирование "/mp3/" копирование $2 копирование ".mp3" завершение регулярного выражения завершение всего кода </example> </para> <para> Обратите внимание, что инструкций для директивы <link doc="ngx_http_core_module.xml" id="limit_rate"/> нет, поскольку она не имеет отношения к модулю <literal>ngx_http_rewrite_module</literal>. Для блока <link id="if"/> создаётся отдельная конфигурация. Если условие истинно, запрос получает эту конфигурацию, и в ней <literal>limit_rate</literal> равен 10k. </para> <para> Директиву <example> rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; </example> можно сделать на одну инструкцию меньше, если в регулярном выражении перенести первый слэш внутрь скобок: <example> rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; </example> Тогда соответствующие инструкции будут выглядеть так: <example> проверка регулярного выражения копирование $1 копирование "/mp3/" копирование $2 копирование ".mp3" завершение регулярного выражения завершение всего кода </example> </para> </section> </module>