Заголовок HTTP Cache-Control содержит директивы (инструкции) в запросах и ответах, которые управляют кэшированием в браузерах и общих кэшах (например, прокси-серверах и CDN).

Синтаксис

Cache-Control: <directive>, <directive>, ...

Для директив кэширования действуют следующие правила:

• Директивы кэширования не чувствительны к регистру. Однако рекомендуется использовать строчные буквы, поскольку некоторые реализации не распознают директивы в верхнем регистре.
• Допускается несколько директив; их необходимо разделять запятыми (например, Cache-control: max-age=180, public).
• Некоторые директивы принимают необязательный аргумент. Если аргумент указан, его отделяют от имени директивы знаком равенства (=). Как правило, аргументы директив — это целые числа, поэтому их не заключают в кавычки (например, Cache-control: max-age=12).

Директивы кэширования

В следующей таблице перечислены стандартные директивы Cache-Control:

Примечание: Проверьте их поддержку в таблице совместимости; пользовательские агенты, которые их не распознают, должны их игнорировать.

Терминология

В этом разделе определены термины, используемые в документе, некоторые из которых взяты из спецификации.

Кэш (HTTP)

Реализация, которая хранит запросы и ответы для повторного использования в последующих запросах. Кэш может быть общим или частным.

Общий кэш

Кэш, расположенный между исходным сервером и клиентами (например, прокси-сервер или CDN). Он хранит один ответ и повторно использует его для нескольких пользователей — поэтому разработчикам следует избегать хранения персонализированного содержимого в общем кэше.

Частный кэш

Кэш, расположенный на стороне клиента. Его также называют локальным кэшем или кэшем браузера. Он может хранить и повторно использовать персонализированное содержимое для одного пользователя.

Сохранение ответа

Сохранение ответа в кэше, если ответ можно кэшировать. Однако сохранённый ответ не всегда используется повторно без изменений. (Обычно под «кэшированием» понимают сохранение ответа.)

Повторное использование ответа

Повторное использование сохранённых в кэше ответов для последующих запросов.

Повторная проверка ответа

Запрос к исходному серверу о том, остаётся ли сохранённый ответ свежим. Обычно повторная проверка выполняется с помощью условного запроса.

Свежий ответ

Указывает, что ответ является свежим. Обычно это означает, что ответ можно повторно использовать для последующих запросов в зависимости от директив запроса.

Устаревший ответ

Указывает, что ответ является устаревшим. Обычно это означает, что ответ нельзя повторно использовать без изменений. Кэш не обязан сразу удалять устаревшие ответы, поскольку после повторной проверки ответ может снова стать свежим.

Возраст

Время, прошедшее с момента создания ответа. Это критерий, определяющий, является ли ответ свежим или устаревшим.

Директивы

В этом разделе перечислены директивы, влияющие на кэширование, — директивы ответа и директивы запроса.

Директивы ответа

max-age

Директива ответа max-age=N указывает, что ответ остаётся свежим в течение N секунд после создания.

Cache-Control: max-age=604800

Указывает, что кэши могут сохранять этот ответ и повторно использовать его для последующих запросов, пока он свежий.

Обратите внимание, что max-age — это не время, прошедшее с момента получения ответа, а время, прошедшее с момента его создания на исходном сервере. Поэтому, если другой кэш или другие кэши на сетевом маршруте ответа сохранят его на 100 секунд (это указывается в поле заголовка ответа Age), браузерный кэш вычтет 100 секунд из времени актуальности ответа.

Если значение max-age отрицательное (например, -1) или не является целым числом (например, 3599.99), поведение кэширования не определено. Рекомендуется, чтобы кэши трактовали это значение как 0 (это указано в разделе Вычисление времени актуальности спецификации HTTP).

Cache-Control: max-age=604800
Age: 100

s-maxage

Директива ответа s-maxage указывает, как долго ответ остаётся свежим в общем кэше. Директива s-maxage игнорируется частными кэшами и переопределяет значение, заданное директивой max-age или заголовком Expires, для общих кэшей, если они присутствуют.

Cache-Control: s-maxage=604800

no-cache

Директива ответа no-cache указывает, что ответ можно сохранить в кэшах, но перед каждым повторным использованием его необходимо проверить на исходном сервере, даже если кэш отключён от исходного сервера.

Cache-Control: no-cache

Если вы хотите, чтобы кэши всегда проверяли наличие обновлений содержимого при повторном использовании сохранённых данных, используйте директиву no-cache. Она требует от кэшей повторно проверять каждый запрос на исходном сервере.

Обратите внимание, что no-cache не означает «не кэшировать». no-cache разрешает кэшам сохранять ответ, но требует повторно проверять его перед использованием. Если под фразой «не кэшировать» вы подразумеваете именно «не сохранять», используйте директиву no-store.

must-revalidate

Директива ответа must-revalidate указывает, что ответ можно сохранять в кэшах и повторно использовать, пока он свежий. Если ответ станет устаревшим, перед повторным использованием его необходимо проверить на исходном сервере.

Обычно must-revalidate используется вместе с max-age.

Cache-Control: max-age=604800, must-revalidate

HTTP разрешает кэшам повторно использовать устаревшие ответы, когда они отключены от исходного сервера. must-revalidate позволяет предотвратить это: сохранённый ответ либо повторно проверяется на исходном сервере, либо генерируется ответ 504 (Gateway Timeout).

proxy-revalidate

Директива ответа proxy-revalidate эквивалентна must-revalidate, но применяется только к общим кэшам.

no-store

Директива ответа no-store указывает, что никакие кэши (частные или общие) не должны сохранять этот ответ.

Cache-Control: no-store

private

Директива ответа private указывает, что ответ можно сохранить только в частном кэше (например, в локальном кэше браузера).

Cache-Control: private

Добавляйте директиву private для персонализированного содержимого, особенно для ответов, полученных после входа в систему, и для сеансов, управляемых с помощью файлов cookie.

Если вы забудете добавить private к ответу с персонализированным содержимым, такой ответ может быть сохранён в общем кэше и повторно использован для нескольких пользователей, что может привести к утечке личной информации.

public

Директива ответа public указывает, что ответ можно сохранить в общем кэше. Ответы на запросы с полями заголовка Authorization нельзя сохранять в общем кэше; однако директива public позволяет сохранять такие ответы в общем кэше.

Cache-Control: public

Как правило, при использовании на страницах Basic Auth или Digest Auth браузер отправляет запросы с заголовком Authorization. Это означает, что доступ к ответу ограничен пользователями с учётными записями, и по своей сути его нельзя кэшировать в общем кэше, даже если он содержит max-age.

Чтобы снять это ограничение, можно использовать директиву public.

Cache-Control: public, max-age=604800

Обратите внимание, что это ограничение также снимают s-maxage или must-revalidate.

Если запрос не содержит заголовка Authorization или в ответе уже используется s-maxage либо must-revalidate, директива public не нужна.

must-understand

Директива ответа must-understand указывает, что кэш должен сохранять ответ, только если ему известны требования к кэшированию, основанные на коде состояния.

Для резервного поведения must-understand следует использовать вместе с no-store.

Cache-Control: must-understand, no-store

Если кэш не поддерживает must-understand, директива будет проигнорирована. Если также указана no-store, ответ не сохраняется.

Если кэш поддерживает must-understand, он сохраняет ответ с учётом требований к кэшированию, обусловленных его кодом состояния.

no-transform

Некоторые промежуточные узлы изменяют содержимое по разным причинам. Например, некоторые из них преобразуют изображения, чтобы уменьшить объём передаваемых данных. В определённых случаях поставщику содержимого это нежелательно.

no-transform указывает, что никакие промежуточные узлы (независимо от того, реализуют ли они кэширование) не должны изменять содержимое ответа.

immutable

Директива ответа immutable указывает, что ответ не будет обновляться, пока он свежий.

Cache-Control: public, max-age=604800, immutable

Современная рекомендуемая практика для статических ресурсов — включать версии или хэши в URL и никогда не изменять ресурсы, а при необходимости обновлять их новыми версиями с новыми номерами версий или хэшами, чтобы URL отличались. Это называется шаблоном предотвращения кэширования (cache busting).

<script src="https://example.com/react.0.0.0.js"></script>

Когда пользователь перезагружает страницу в браузере, браузер отправляет условные запросы исходному серверу для проверки. Но для таких статических ресурсов повторная проверка не нужна даже при перезагрузке страницы, поскольку они никогда не изменяются. immutable сообщает кэшу, что ответ неизменяем, пока он свежий, и позволяет избежать таких ненужных условных запросов к серверу.

Если для ресурсов используется шаблон предотвращения кэширования и задаётся длительное значение max-age, можно также добавить immutable, чтобы избежать повторной проверки.

stale-while-revalidate

Директива ответа stale-while-revalidate указывает, что кэш может повторно использовать устаревший ответ, пока выполняется его повторная проверка в кэше.

Cache-Control: max-age=604800, stale-while-revalidate=86400

В приведённом выше примере ответ остаётся свежим в течение 7 дней (604800 с). По истечении этого срока он становится устаревшим, но кэшу разрешено использовать его для запросов в течение следующего дня (86400 с), если повторная проверка ответа выполняется в фоновом режиме.

После повторной проверки ответ снова становится свежим, поэтому клиентам кажется, что в течение этого периода он всегда оставался свежим. Таким образом, от них фактически скрывается задержка, вызванная повторной проверкой.

Если за этот период не поступило ни одного запроса, кэш становится устаревшим, и при следующем запросе повторная проверка выполняется обычным образом.

stale-if-error

Директива ответа stale-if-error указывает, что кэш может повторно использовать устаревший ответ, если вышестоящий сервер выдаёт ошибку или ошибка возникает локально. Ошибкой считается любой ответ с кодом состояния 500, 502, 503 или 504.

Cache-Control: max-age=604800, stale-if-error=86400

В приведённом выше примере ответ остаётся свежим в течение 7 дней (604800 с). После этого он становится устаревшим, но при возникновении ошибки его можно использовать ещё 1 день (86400 с).

После истечения периода stale-if-error клиент получит любую возникшую ошибку.

Директивы запроса

no-cache

Директива запроса no-cache предписывает кэшам проверять ответ на исходном сервере перед повторным использованием.

Cache-Control: no-cache

no-cache позволяет клиентам запрашивать наиболее актуальный ответ, даже если в кэше есть свежий ответ.

Обычно браузеры добавляют no-cache к запросам, когда пользователь выполняет принудительную перезагрузку страницы.

no-store

Директива запроса no-store позволяет клиенту попросить кэши не сохранять запрос и соответствующий ответ, даже если ответ исходного сервера можно сохранить.

Cache-Control: no-store

max-age

Директива запроса max-age=N указывает, что клиент допускает сохранённый ответ, созданный на исходном сервере не более N секунд назад, где N может быть любым неотрицательным целым числом (включая 0).

Cache-Control: max-age=10800

В приведённом выше случае, если ответ с Cache-Control: max-age=10800 был создан более 3 часов назад (с учётом max-age и заголовка Age), кэш не сможет использовать этот ответ повторно.

Многие браузеры используют эту директиву при перезагрузке, как описано ниже.

Cache-Control: max-age=0

max-age=0 — это обходной вариант для no-cache, поскольку многие старые реализации кэшей (HTTP/1.0) не поддерживают no-cache. В последнее время браузеры по-прежнему используют max-age=0 при «перезагрузке» для обратной совместимости, а для «принудительной перезагрузки» используют no-cache.

Если значение max-age отрицательное (например, -1) или не является целым числом (например, 3599.99), поведение кэширования не определено. Рекомендуется, чтобы кэши трактовали это значение как 0.

max-stale

Директива запроса max-stale=N указывает, что клиент допускает сохранённый ответ, который устарел не более чем на N секунд. Если значение N не указано, клиент примет устаревший ответ любого возраста.

Cache-Control: max-stale=3600

Например, запрос с указанным выше заголовком означает, что браузер примет из кэша устаревший ответ, срок актуальности которого истёк в течение последнего часа.

Клиенты могут использовать этот заголовок, если исходный сервер не работает или отвечает слишком медленно и можно принять ответы из кэшей, даже если они немного устарели.

Обратите внимание, что основные браузеры не поддерживают запросы с max-stale.

min-fresh

Директива запроса min-fresh=N указывает, что клиент допускает сохранённый ответ, который будет оставаться свежим ещё как минимум N секунд.

Cache-Control: min-fresh=600

В приведённом выше случае, если ответ с Cache-Control: max-age=3600 был сохранён в кэшах 51 минуту назад, кэш не сможет использовать этот ответ повторно.

Клиенты могут использовать этот заголовок, когда пользователь требует, чтобы ответ не только был свежим, но и оставался неизменным в течение определённого периода времени.

Обратите внимание, что основные браузеры не поддерживают запросы с min-fresh.

no-transform

Имеет тот же смысл, что и no-transform для ответа, но применяется к запросу.

only-if-cached

Клиент указывает, что следует вернуть уже сохранённый в кэше ответ. Если в кэше есть сохранённый ответ, даже устаревший, он будет возвращён. Если сохранённого ответа нет, будет возвращён ответ 504 Gateway Timeout.

stale-if-error

Директива запроса stale-if-error указывает, что браузер заинтересован в получении устаревшего содержимого при ошибке от любого промежуточного сервера для определённого источника. Ни один браузер не поддерживает эту директиву (см. раздел Совместимость с браузерами).

Примеры использования

Запрет сохранения

Если вы не хотите, чтобы ответ сохранялся в кэшах, используйте директиву no-store.

Cache-Control: no-store

Обратите внимание, что no-cache означает «ответ можно сохранить, но нельзя использовать повторно без предварительной проверки», поэтому эта директива не предотвращает сохранение ответа.

Cache-Control: no-cache

В теории, если директивы противоречат друг другу, следует применять наиболее строгую директиву. Поэтому приведённый ниже пример практически бессмыслен: private, no-cache, max-age=0 и must-revalidate противоречат no-store.

# conflicted
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate

# equivalent to
Cache-Control: no-store

Кэширование статических ресурсов с помощью «предотвращения кэширования»

При создании статических ресурсов с механизмами управления версиями или хэширования добавление версии или хэша к имени файла либо строке запроса — хороший способ управлять кэшированием.

Например:

<!-- index.html -->
<script src="/assets/react.min.js"></script>
<img src="/assets/hero.png" width="900" height="400" />

Версия библиотеки React изменится при её обновлении, а hero.png также изменится при редактировании изображения. Поэтому такие ресурсы сложно хранить в кэше с max-age.

В этом случае можно учесть потребности кэширования, используя определённую пронумерованную версию библиотеки и включив хэш изображения в его URL.

<!-- index.html -->
<script src="/assets/react.0.0.0min.js"></script>
<img src="/assets/hero.png?hash=deadbeef" width="900" height="400" />

Можно задать длительное значение max-age и immutable, поскольку содержимое никогда не изменится.

# /assets/*
Cache-Control: max-age=31536000, immutable

При обновлении библиотеки или редактировании изображения новое содержимое должно получить новый URL, и кэши не будут использоваться повторно. Это называется шаблоном «предотвращения кэширования» (cache busting).

Используйте no-cache, чтобы HTML-ответ не кэшировался. no-cache может вызвать повторную проверку, и клиент получит новую версию HTML-ответа и статических ресурсов.

# /index.html
Cache-Control: no-cache

Примечание: если index.html защищён с помощью Basic Authentication или Digest Authentication, файлы в /assets не сохраняются в общем кэше. Если файлы /assets/ можно сохранять в общем кэше, необходимо также использовать одну из директив: public, s-maxage или must-revalidate.

Всегда актуальное содержимое

Если содержимое генерируется динамически или является статическим, но часто обновляется, необходимо обеспечить получение пользователем самой актуальной версии.

Если не добавить заголовок Cache-Control, поскольку ответ не предназначен для кэширования, это может привести к неожиданному результату. Кэш может эвристически решить сохранить его, поэтому при наличии требований к кэшированию всегда указывайте их явно в заголовке Cache-Control.

Добавление no-cache к ответу приводит к его повторной проверке на сервере, поэтому каждый раз можно отправлять свежий ответ или, если у клиента уже есть актуальная версия, просто отвечать 304 Not Modified.

Cache-Control: no-cache

Большинство кэшей HTTP/1.0 не поддерживают директивы no-cache, поэтому раньше в качестве обходного решения использовалась max-age=0. Однако только max-age=0 могла привести к повторному использованию устаревшего ответа, когда кэши отключены от исходного сервера. must-revalidate предотвращает это. Поэтому приведённый ниже пример эквивалентен no-cache.

Cache-Control: max-age=0, must-revalidate

Но пока можно просто использовать no-cache.

Очистка уже сохранённого кэша

Директив для удаления уже сохранённых ответов из кэшей на промежуточных серверах не существует.

Представьте, что клиенты или кэши сохраняют свежий ответ для некоторого пути, и запрос к серверу не отправляется. Сервер не может повлиять на этот путь.

Чтобы удалить все сохранённые ответы сайта из кэша браузера, можно использовать Clear-Site-Data: cache, поэтому применяйте эту директиву с осторожностью. Обратите внимание, что она не влияет на общие или промежуточные кэши.

Спецификации

Совместимость с браузерами

См. также

• Кэширование HTTP
• Руководство по кэшированию для авторов веб-сайтов и веб-мастеров
• Рекомендации по кэшированию и подводные камни max-age
• Cache-Control для широкой аудитории
• RFC 9111 — кэширование HTTP
• RFC 5861 — расширения Cache-Control для устаревшего содержимого
• RFC 8246 — неизменяемые ответы HTTP