Конспект раздела: rewrite, return, map

Раздел про порядок фаз и про инструменты, которые этим порядком пользуются.

Фазы - главная схема раздела

server rewrite → find location → rewrite → preaccess → access
→ try_files → content → filters

return и rewrite

return 301 https://$host$request_uri;
return 444;                              # закрыть соединение
rewrite ^/old/(.*)$ /new/$1 permanent;   # 301
rewrite ^/api/(.*)$ /$1 break;           # переписать и остаться в location

Замена - весь новый URI: несовпавший хвост не дописывается, его переносят скобками. Голый адрес без кода в return даёт 302, а не 301. break не только оставляет запрос в блоке, но и обрывает остальные директивы фазы - return после него не выполнится.

Предел - десять перезаписей: замер цепочкой даёт 200 на десятой и 500 на одиннадцатой, со строкой rewrite or internal redirection cycle в error_log.

if и его замены

Безопасны внутри if только return, rewrite, set, break. Всё остальное:

по имени сайта      → отдельный server
по URI              → отдельный location
по методу           → limit_except
по наличию файла    → try_files
по чему угодно ещё  → map (или geo для адресов)

Ловушки раздела списком

• $uri вместо $request_uri в редиректе - пропадает строка запроса;
• rewrite … last перед proxy_pass - нужен break;
• return вместо deny - «закрытая» директория отвечает 200;
• два if подряд выполняются ОБА, последовательно (замер: r=AB);
• add_header внутри сработавшего if отменяет заголовки снаружи;
• proxy_pass внутри if конфиг принимает - и блок начинает слать на два разных адреса в зависимости от запроса;
• error_page 404 = 200 … с пробелом не грузится, верно =200;
• регистр в nginx складывается только на латинице: ~* и точные ключи map не считают большие и БОЛЬШИЕ одним значением;
• значение map кешируется на запрос и после rewrite остаётся старым - если это мешает, нужен volatile;
• переменная в proxy_pass отменяет подстановку хвоста URI.

Свежее

CVE-2026-42533 (переполнение в map с захватами) закрыт в 1.31.3 и 1.30.4; CVE-2026-42945 (heap overflow в ngx_http_rewrite_module) - в 1.31.0.

Чек-лист: что ты должен уметь объяснить

• Порядок фаз и три следствия из него.
• Чем last отличается от break.
• Почему if называют злом и какие директивы в нём безопасны.
• Как заменить сложное условие через map.
• Сколько перезаписей проходит и что видно в логе на лишней.
• Почему nginx -t не защищает от if с proxy_pass.
• Что кеширует map и когда нужен volatile.