Конспект: map вместо if

«If is evil» - и чем его заменяют.

Почему if опасен

if внутри location создаёт неявный вложенный location: сработавшее условие забирает обслуживание запроса себе, и часть директив перестаёт наследоваться.

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

if ($request_method = POST) { return 405; }          # безопасно
if ($http_user_agent ~* "(bot|spider)") {            # безопасно
    rewrite ^ /robots-only.html last;
}

location /images/ {
    add_header X-Site shop;
    if ($request_method = GET) {
        add_header X-Cached yes;      # ← первый заголовок исчезнет
    }
}

Замер по трём случаям одного блока:

Что проверяется при старте, а что нет

"try_files" directive is not allowed here

А вот proxy_pass внутри if рядом с внешним proxy_pass конфиг принимает. Замер: один и тот же location отдал бэкенду /внешний/cart без параметра и /api/cart?x=1 с параметром. На nginx -t как на защиту от if полагаться нельзя.

Чем заменять

map

map $http_user_agent $is_bot {
    hostnames;                 # для доменных имён: маски .example.com и *.example.com
    volatile;                  # не кешировать результат на запрос
    default            0;
    "~*(bot|spider)"   1;
}

Порядок поиска: точные ключи → маски имён → регулярки сверху вниз → default. Точное значение сильнее регулярки, даже если та написана выше - проверено.

Регистр складывается только на латинице. Abc, abc, ABC попадают в один точный ключ; Точное и точное - в разные, и ~*^БОЛЬШИЕ$ не ловит большие. То же верно для location ~*.

geo - родственник для адресов: тот же принцип, но ключ - IP.

Ловушки джокера

• Два if подряд выполняются ОБА. Замер с двумя set даёт r=AB: это не «первый выигравший», а последовательное выполнение на фазе rewrite.
• if с proxy_pass внутри - один блок, два разных адреса на бэкенде.
• Значение карты кешируется на запрос. После rewrite обычная карта по $uri отдаёт значение, посчитанное ДО перезаписи; лечится volatile.
• Переменная в proxy_pass отменяет подстановку хвоста: http://$куда/ отправит бэкенду ровно /. Хвост дописывают через $request_uri.
• CVE-2026-42533: переполнение буфера в map с регулярками и захватами, закрыт в 1.31.3 (и 1.30.4). В 1.31.0 закрывали heap overflow в самом ngx_http_rewrite_module (CVE-2026-42945).