Если вы хоть раз настраивали заголовки в Nginx, то почти наверняка сталкивались с «пропадающим» HSTS на редиректе, отсутствующим CORS на 4xx/5xx или неожиданным исчезновением ранее заданных заголовков внутри конкретного location. Виноваты не «глюки», а специфика директивы add_header, ее наследования и параметр always. Ниже — подробный разбор с практическими схемами и шаблонами.
Что именно делает add_header и чего не делает
add_header добавляет заголовок в ответ сервера. По умолчанию заголовок добавляется только к «успешным» ответам, а для ответов-ошибок он не добавляется. В результате security- и CORS-заголовки часто теряются как раз в те моменты, когда они нужны сильнее всего — при ошибках и служебных ответах.
Параметр
alwaysговорит Nginx добавлять заголовок ко всем финальным ответам, включая 4xx/5xx и ответы, сформированные черезerror_page.
Важно не путать add_header с proxy_set_header. Первое — про заголовки ответа клиенту, второе — про заголовки запроса, который Nginx отправляет во внутренний апстрим. Если вы перепутали их назначение, эффект будет нулевым: клиент не увидит нужного заголовка.
Когда нужен параметр always
Почти всегда, когда речь про:
- HSTS (Strict-Transport-Security) — иначе заголовок теряется на части ответов;
- CORS (Access-Control-Allow-*) — ошибки тоже должны возвращать корректные CORS-заголовки;
- Безопасность и приватность:
X-Frame-Options,X-Content-Type-Options,Referrer-Policy,Permissions-Policy,Cross-Origin-*.
Условно, если заголовок влияет на политику безопасности или кэширования со стороны клиента, его отсутствие на ошибках и редиректах — потенциальная брешь.
Контексты: http, server, location и if in location
add_header можно объявлять в контекстах http, server, location, а также внутри if при условии, что это if in location. От контекста зависит, где сработает правило и как оно наследуется.
Тонкая настройка Nginx чаще всего делается на собственной машине. Если вам нужна изоляция, руут-доступ и стабильная производительность, рассмотрите VDS — так проще воспроизводимо держать единый набор заголовков для всех проектов.
Ключевое правило наследования
Директивы
add_headerнаследуются с верхнего уровня только если на текущем уровне нет ни одной собственной директивыadd_header. Как только вы объявили хотя бы одинadd_headerв более узком контексте, вы «обрубили» все наследование и должны перечислить все нужные заголовки заново.
Это самый частый источник сюрпризов. Например, вы задали общий набор заголовков в server, а затем в одном из location добавили одиночный add_header для CORS. Результат: в этом location останется только CORS, а все security-заголовки «пропадут», потому что наследование было сброшено фактом наличия локальной директивы.
Проверка себя: мини-чек на наследование
- Хотите общий набор заголовков на весь виртуальный хост? Объявляйте их на уровне
server. - Нужно в
locationдобавить один-единственный заголовок? Либо дублируйте весь набор, либо вынесите общий набор в отдельный include и подключайте его везде, где вы добавляете локальные заголовки. - Используете
ifвlocation? Заголовки там работают, но правило наследования остается прежним.

Редиректы, 304 и error_page
Служебные ответы часто рушат ожидания: вы настроили заголовки, но при return 301 или при 304 Not Modified нужного заголовка нет. Почему? По умолчанию add_header действует для «успешных» кодов, а для ошибок и некоторых служебных случаев — нет. Спасти ситуацию призван always.
Особый случай — error_page. Когда вы переопределяете код ответа через error_page, то без always заголовки могут не добавляться к исходным ошибочным ответам. С always они будут добавлены независимо от того, как ответ сформирован и какой исходный код был у запроса.
Типичный безопасный шаблон заголовков
server {
listen 443 ssl http2;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Permissions-Policy "geolocation=(), microphone=()" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Resource-Policy "same-origin" always;
# ... остальной конфиг
}
Этот блок лучше держать на уровне server для HTTPS-виртуала (на HTTP он не нужен — например, HSTS игнорируется браузером по не-HTTPS). Если только подключаете HTTPS, заранее оформите SSL-сертификаты. Если ниже в каком-то location понадобятся дополнительные заголовки — не забудьте дублировать весь набор или подключить include с общими заголовками.
CORS: почему без always нельзя
Запросы из браузера ждут корректные CORS-заголовки независимо от того, успешно ли выполнен запрос. Предположим, вы отдаете Access-Control-Allow-Origin только на 2xx. При 401/403/404 клиентская логика может «сломаться», потому что браузер заблокирует доступ к телу ответа без CORS. Поэтому CORS почти всегда настраивают с always, а также добавляют Vary, если политика зависит от Origin. Дополнительные приемы собраны в статье «CORS-заголовки: Nginx и Apache» — посмотрите материал в разделе подробный разбор CORS.
location /api/ {
# Общие security-заголовки стоит включить через include;
# Здесь — чисто CORS.
add_header Access-Control-Allow-Origin "*" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
add_header Vary "Origin" always;
if ($request_method = OPTIONS) {
add_header Content-Length 0 always;
add_header Content-Type text/plain always;
return 204;
}
# proxy_pass ...
}
Если вам нужна точная выборка по источникам, вместо * используйте $http_origin с проверкой в map (и обязательно не забывайте Vary: Origin).
Как не потерять заголовки при «точечных» переопределениях
Два рабочих подхода:
- Дублировать весь набор заголовков в каждом
location, где вы используетеadd_header. Надежно, но громоздко. - Вынести общие заголовки в файл и подключать через
include. Тогда даже в «частных»locationвы начинаете с общего набора и добавляете точечные.
# common/security_headers.conf
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Permissions-Policy "geolocation=(), microphone=()" always;
# server {...}
server {
listen 443 ssl http2;
include common/security_headers.conf;
location /static/ {
include common/security_headers.conf; # Чтобы не срезать наследование
add_header Cache-Control "public, max-age=31536000, immutable" always;
}
}
Подключение include в каждом location, где есть собственные заголовки, — самый практичный способ не наступать на грабли.
Противоречия и дубликаты: как Nginx склеивает заголовки
Nginx не «перезаписывает» одинаковые заголовки, а добавляет второй экземпляр. Браузер может объединять их по правилам конкретного заголовка (например, Cache-Control может конфликтовать). Если вы получаете заголовок и от апстрима, и от Nginx, решайте конфликт явным образом:
- Для ответов из апстрима:
proxy_hide_headerубирает конкретный заголовок из ответа апстрима. - Для заголовков, поставленных ранее в Nginx, штатного удаления нет; можно «переформатировать» поведение конфигурацией или использовать сторонние модули, если это допустимо вашей политикой.
location /api/ {
proxy_hide_header Server;
proxy_hide_header X-Powered-By;
# ...
}
Избыточные или конфликтующие заголовки — частая причина неожиданных кэшей, смешения политик безопасности и проблем с CORS.

Редиректы и HSTS: частые ошибки
Классика: на HTTPS-виртуале задан Strict-Transport-Security, но при редиректе внутри сайта он отсутствует. Причины две: либо заголовок объявлен в location, где редирект уходит раньше, либо отсутствует always. Решение — объявлять HSTS на уровне server с always и не занижать область действия излишне узким location. Подробная инструкция по выпуску HTTPS и включению HSTS — в материале HTTPS, Certbot и HSTS.
server {
listen 443 ssl http2;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
return 301 https://example.org$request_uri;
}
304 Not Modified и кэш
304 — особенный ответ без тела. Клиент может использовать заголовки, кешированные ранее, или те, что пришли с 304. Если без always нужные заголовки не попадают в 304, клиентская сторона может вести себя неконсистентно: например, считать, что у ответа нет Cache-Control или политики безопасности. Чтобы избежать сюрпризов с валидаторами и браузерами, задавайте важные заголовки с always и держите кэш-заголовки согласованными между 200 и 304.
error_page и внутренние локации
При обработке ошибок через error_page вы фактически запускаете внутренний запрос в другой location. Без always итоговый набор заголовков может зависеть от того, какой код вернулся на выходе. С always вы исключаете «просадки» заголовков на ошибочных цепочках.
error_page 404 = @fallback;
location @fallback {
add_header Cache-Control "no-store" always;
return 200 "{}";
}
Если вы используете общий набор security-заголовков, помните про правило наследования и не забывайте подключать include в таких внутренних локациях.
Отладка заголовков: как быстро понять, что пошло не так
Самое простое — смотреть «сырой» ответ:
curl -I https://example.org
curl -I -H "Origin: https://foo.example" https://example.org/api/
Чтобы ловить «дрейф» заголовков прямо в логах, добавьте в формат access-лога интересующие $sent_http_* переменные. Например, так:
log_format hdr '$remote_addr - $request "$status" '
'sts=$sent_http_strict_transport_security '
'xfo=$sent_http_x_frame_options '
'csp=$sent_http_content_security_policy '
'cors=$sent_http_access_control_allow_origin';
access_log /var/log/nginx/access.log hdr;
Теперь вы будете видеть, какие значения реально уехали клиенту. Это удобный способ выявить сброшенное наследование или конфликт с заголовками апстрима. Если параллельно решаете миграцию с редиректами 301, обратите внимание на разбор «Переезд домена, 301, HSTS и SSL» — см. чеклист переезда домена.
Content-Security-Policy: минимально безопасный старт
Полная CSP сложна и требует инвентаризации фронтенда. Но даже базовая политика уже помогает. В Nginx ее обычно задают одной строкой:
add_header Content-Security-Policy "default-src 'self'; object-src 'none'; base-uri 'self'" always;
Планомерно расширяйте политику, включая источники по мере необходимости, и обязательно тестируйте в режиме Content-Security-Policy-Report-Only на ранних этапах. Для режима report-only добавьте отдельный заголовок с тем же набором правил, но без эффектов блокировки. Не забывайте правило наследования: если вы в каком-то location добавили чисто CORS, придется повторить и CSP.
Версии Nginx и совместимость
Параметр always поддерживается в современных стабильных версиях давно. Если у вас древний Nginx, обновитесь: отсутствие always усложняет конфигурацию, а безопасность страдает. При миграции проверяйте, не «ломает» ли новое поведение ваши редиректы и кэш-цепочки (особенно 304), и валидируйте заголовки инструментами командной строки и автотестами.
Чеклист перед продом
- Где объявлены базовые security-заголовки? На уровне
serverдля HTTPS. - Включен ли
alwaysдля HSTS, CORS и базовой безопасности? Должен быть. - Есть ли локации с собственными
add_header? Если да, общий набор подключен через include или продублирован? - Проверены ли ответы на 301/302, 304, 401/403/404, 5xx? Заголовки на месте?
- Нет ли конфликтов с заголовками апстрима? При необходимости используйте
proxy_hide_header. - Логи содержат ключевые
$sent_http_*для наблюдаемости? Это помогает ловить регрессии.
Итоги
add_header в Nginx прост, пока вы не столкнетесь с наследованием и «нестандартными» кодами ответа. Две главные идеи, которые экономят часы отладки: используйте always для политик безопасности и CORS, а общий набор заголовков держите на уровне server и/или в подключаемом include, который повторяете в каждом «частном» контексте, где есть собственные add_header. Добавьте наблюдаемость через $sent_http_*, регулярно проверяйте 3xx/4xx/5xx/304 и не забывайте про конфликты с заголовками апстрима. Тогда заголовки будут предсказуемыми, а безопасность — консистентной.


