Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_rewrite_module.xml @ 487:2406529bc838
nginx-1.1.19, nginx-1.0.15
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Thu, 12 Apr 2012 13:23:53 +0000 |
parents | 1702722eca07 |
children | 95a970603b0f |
line wrap: on
line source
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_rewrite_module" link="/ru/docs/http/ngx_http_rewrite_module.html" lang="ru"> <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">сервера</link>; </listitem> <listitem> ищется location для запроса; </listitem> <listitem> выполняются директивы этого модуля, описанные в выбранном <link doc="ngx_http_core_module.xml" id="location"/>, и если они изменяли URI, то ищется новый location для уже нового URI. Этот цикл может повторяться до 10 раз, после чего возвращается ошибка <http-status code="500" text="Internal Server Error"/>. </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> Пример: <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>”; </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></syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Завершает обработку и возвращает клиенту указанный <value>код</value>. Можно возвращать следующие коды: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. Кроме того, нестандартный код 444 закрывает соединение без передачи заголовка ответа. </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>; </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> </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="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>