Конспект раздела: язык конфига

Раздел про сам язык: как устроен конфиг, что откуда наследуется и откуда берутся значения, зависящие от запроса.

Три темы

СИНТАКСИС      аргументы читаются до ; или { - отсюда всё остальное
НАСЛЕДОВАНИЕ   вниз по контекстам, ближайшее побеждает + три исключения
ПЕРЕМЕННЫЕ     $uri против $request_uri, $http_*, свои через set и map

Что нужно помнить дословно

1. Аргументы директивы читаются, пока не встретится ; или {. Номер строки в ошибке - место, где разбор остановился, а не где ошибка.
2. Директива работает только в своих контекстах, и ставить её надо в самый узкий из разрешённых.
3. Директивы-списки замещаются целиком: один add_header в location отменяет все унаследованные. С 1.29.3 чинится строкой add_header_inherit merge; на уровне http.
4. Обработчик содержимого не наследуется: вложенный location внутри location с proxy_pass не проксирует.
5. $uri меняется, $request_uri - нет. Редирект пишут через второй.
6. Своя переменная - только через set или map.

Отладочные приёмы раздела

nginx -T                                # итоговый конфиг со всеми include
nginx -t                                # синтаксис и номер строки
curl -I http://shop.local/path/         # какие заголовки реально пришли

add_header X-Debug "$uri | $request_uri | $host" always;   # временно, чтобы увидеть

Ошибки, которые ищут дольше всего

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

• Почему ошибка синтаксиса показывает не ту строку и когда её нет вовсе.
• Чем контекст http отличается от server и почему шире не значит надёжнее.
• Три исключения из правила наследования и что все три включает добавление строки.
• Что делает add_header_inherit merge и с какой версии она есть.
• Разницу $uri и $request_uri и когда она проявляется.
• Как за минуту проверить, действует ли директива в конкретном блоке.