rewrite в nginx: флаги last, break, redirect и permanent
Директива rewrite меняет адрес запроса по регулярному выражению: внутри сервера или переадресацией браузера. Для простой переадресации хватит return, для адресов CMS — try_files. rewrite нужен, когда новый адрес собирается из частей старого.
Содержание 11
Что сделать прямо сейчас
- Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться) и набирайте их в том же окне.
- Откройте файл сайта:
sudo nano /etc/nginx/sites-available/example.com. Вместо example.com — имя файла вашего сайта: список покажетls /etc/nginx/sites-enabled/. Если система спросит пароль, введите пароль своего пользователя на сервере. Символы при вводе не видны — наберите пароль и нажмите Enter. - Решите, нужен ли rewrite. Страница или домен переехали целиком — хватит return: когда хватит return. CMS просит передавать все адреса в index.php — нужен try_files: адреса CMS.
- Если нужен rewrite, впишите строку в блок server, перед блоками location. Пример: раздел /catalog/ переехал в /shop/ —
rewrite ^/catalog/(.*)$ /shop/$1 permanent; - Сохраните файл — Ctrl+O, Enter, затем Ctrl+X — и проверьте настройки:
sudo nginx -t. В ответе должны быть слова syntax is ok и test is successful. Тогда примените их:sudo systemctl reload nginx. Если команда ничего не ответила, настройки применены. - Проверьте:
curl -sI https://example.com/catalog/chairs— в ответе должны быть код 301 и строка Location с адресом /shop/chairs.
Если проверка нашла ошибку, nginx назовёт файл и номер строки, а сайт продолжит работать на старых настройках. Что значит сообщение — Все ошибки nginx.
Как устроена строка rewrite
rewrite ^/catalog/(.*)$ /shop/$1 permanent;| Часть | Что значит |
|---|---|
^/catalog/(.*)$ | регулярное выражение: какие адреса менять. ^ — начало адреса, $ — конец |
(.*) | часть адреса, которую нужно перенести. В замене она называется $1, следующая пара скобок — $2 |
/shop/$1 | новый адрес |
permanent | флаг: ответить переадресацией 301 — все флаги |
Выражение сравнивается с путём запроса: без домена и без параметров после знака ?. Параметры nginx сам допишет к новому адресу. Чтобы их отбросить, поставьте ? в конце замены: rewrite ^/old$ /new? permanent;.
Если в выражении есть фигурные скобки или точка с запятой, возьмите его в кавычки: rewrite "^/photo/([0-9]{4})$" /img/$1.jpg last;. Без кавычек nginx примет скобку за начало блока, и проверка nginx -t найдёт ошибку.
Строки rewrite выполняются по порядку, в котором написаны. Писать их можно в блоках server, location и if.
Флаги
| Флаг | Что делает |
|---|---|
permanent | переадресация 301: браузер откроет новый адрес — код 301 |
redirect | переадресация 302 — временная, код 302 |
last | адрес меняется внутри сервера, браузер этого не видит. Остальные строки rewrite в блоке пропускаются, и nginx заново выбирает location для нового адреса |
break | адрес меняется внутри сервера, остальные строки rewrite пропускаются, а запрос обрабатывается в этом же location |
| без флага | выполняются следующие строки rewrite, затем nginx выбирает location для нового адреса |
Если замена начинается с http://, https:// или $scheme, nginx сразу отвечает переадресацией — 302, а с флагом permanent — 301.
last или break
В блоке server пишите last, в блоке location — break. Пример:
location /download/ {
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
}Новый адрес снова начинается с /download/. С флагом last nginx стал бы заново выбирать location и попал бы в этот же блок, а строка rewrite сработала бы ещё раз. После десяти смен адреса nginx прекращает обработку: посетитель получает ошибку 500, а в журнале ошибок появляется строка rewrite or internal redirection cycle — разбор 500.
Когда хватит return
Если адрес меняется целиком, а не по частям, rewrite не нужен — return проще и не проверяет регулярное выражение на каждом запросе:
| Задача | Строка |
|---|---|
| одна страница переехала | location = /old/ { return 301 /new/; } |
| весь сайт на https | return 301 https://example.com$request_uri; |
| старый домен на новый | return 301 https://new.ru$request_uri; |
Готовые блоки для этих случаев — Переадресация в nginx.
Адреса CMS
WordPress и другие CMS передают все адреса в один файл index.php. В Apache для этого пишут RewriteRule в .htaccess, а в nginx — строку try_files:
location / {
try_files $uri $uri/ /index.php?$args;
}nginx сначала ищет файл, потом папку и только потом передаёт запрос в index.php. Подробно — try_files в nginx, как переписать правила из .htaccess — .htaccess в nginx.
Конструкцию if (!-e $request_filename) { rewrite ... } из старых инструкций заменяйте на try_files: результат тот же, а настройка короче.
Условия в блоке if
Строку rewrite или return можно выполнить по условию:
if ($request_method = POST) {
return 405;
}| Условие | Когда истинно |
|---|---|
$переменная | переменная не пустая и не равна 0 |
= и != | переменная равна или не равна строке |
~ и ~* | совпадает с регулярным выражением: с учётом регистра букв и без него. !~ и !~* — не совпадает |
-f, -d, -e | есть файл, папка, файл или папка. С ! — нет |
Внутри if пишите только rewrite, return, set и break. Остальное лучше выносить в отдельные блоки location.
Как проверить
Переадресацию с флагами permanent и redirect покажет curl: curl -sI https://example.com/старый-адрес — смотрите код ответа и строку Location.
Смену адреса с флагами last и break браузер не видит. Чтобы увидеть её в журнале, временно добавьте в блок server две строки:
error_log /var/log/nginx/error.log notice;
rewrite_log on;Примените настройки, откройте адрес и посмотрите журнал: sudo tail -n 20 /var/log/nginx/error.log. Строка с matches покажет, какое выражение сработало, rewritten data — новый адрес. После проверки уберите обе строки и снова примените настройки.
Ошибки и как их исправить
| Что видите | Что делать |
|---|---|
ошибка 500, в журнале rewrite or internal redirection cycle | флаг last в location, и новый адрес попадает в тот же блок: замените last на break — подробнее |
| браузер пишет ERR_TOO_MANY_REDIRECTS | новый адрес снова подходит под выражение: ограничьте его знаками ^ и $ — разбор ошибки |
unknown directive "RewriteRule" | правило из .htaccess вставлено в nginx как есть: перепишите его |
nginx -t находит ошибку в строке с rewrite | в выражении фигурные скобки или точка с запятой без кавычек — возьмите выражение в кавычки |
| rewrite не срабатывает на адрес с параметрами | выражение не видит часть после ?: условие по параметру пишите через переменную, например $arg_id |
| параметры после ? задвоились или пропали | проверьте знак ? в конце замены — как это работает |
Источники
- Документация nginx: директива rewrite — флаги last, break, redirect и permanent; замена, которая начинается с http://, https:// или $scheme, сразу даёт переадресацию; знак ? в конце замены отбрасывает старые аргументы.
- Документация nginx: директива if — условия =, !=, ~, ~*, -f, -d, -e и -x.
- Документация nginx: директива rewrite_log — записи о работе rewrite на уровне notice в журнале ошибок.
- Документация nginx: Converting rewrite rules — на английском: переадресация на другое имя отдельным блоком server с return вместо if и rewrite.
- Исходный код nginx 1.24.0: ngx_http_core_module.c — после десяти смен адреса внутри одного запроса nginx пишет rewrite or internal redirection cycle и отвечает 500.
Сверено 23 октября 2026 года.
Что почитать дальше
- Настройки nginxкак устроены файлы и блоки, главные директивы.
- Переадресация в nginxготовые блоки return для https, www и нового домена.
- location в nginxкак nginx выбирает блок для адреса.
- try_files в nginxадреса CMS без rewrite.
- RewriteRule в .htaccessте же правила для Apache.