После обновления сайта пользователи иногда продолжают видеть старые CSS и JavaScript. Причина — кеш браузера: содержимое файла изменилось, а его URL остался прежним.
Принудительная перезагрузка страницы (Ctrl+Shift+R или Ctrl+F5 в распространённых настольных браузерах) может решить проблему на одном компьютере, но заставлять пользователей делать это после каждого релиза неправильно. Обычный Ctrl+R не гарантирует обход кеша.
Для решения проблемы используется версионирование статических ресурсов: при изменении содержимого меняется URL файла или его параметр версии.
В современных проектах Symfony есть несколько способов:
- AssetMapper — появился в Symfony 6.3 и предоставляет версионированные URL ресурсов без обязательной сборки через Webpack.
- Webpack Encore — может создавать файлы с хешами содержимого и
manifest.json; для разрешения адресов используетсяjson_manifest_path. - Symfony Asset Component — поддерживает простые версии и собственные реализации
VersionStrategyInterface. Этот вариант полезен для проектов без AssetMapper и сборщика либо для нестандартных сценариев публикации статики.
Ниже рассмотрим третий вариант: собственную стратегию, в которой версия меняется при развёртывании приложения.
Содержание
Что нужно сделать:
- Используем
asset()в Twig. Все ссылки на ресурсы, для которых необходимо версионирование, должны генерироваться через эту функцию:
<link rel="stylesheet" href="{{ asset('css/app.css') }}">
<script src="{{ asset('js/app.js') }}" defer></script>
<svg><use href="{{ asset('img/sprite.svg') }}#test-123"></use></svg>
- Создаём стратегию версионирования. Она читает версию из файла
var/asset_version.txtи добавляет к URL параметрv. Если в исходном URL есть якорь, параметр вставляется перед ним.
Файл src/Asset/VersionStrategy/ReleaseVersionStrategy.php:
<?php
declare(strict_types=1);
namespace App\Asset\VersionStrategy;
use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
final class ReleaseVersionStrategy implements VersionStrategyInterface
{
public function __construct(
private readonly string $versionFile,
) {
}
public function getVersion(string $path): string
{
if (!is_file($this->versionFile)) {
return '1';
}
$version = trim((string) file_get_contents($this->versionFile));
return $version !== '' ? $version : '1';
}
public function applyVersion(string $path): string
{
$version = $this->getVersion($path);
$parts = explode('#', $path, 2);
$url = $parts[0];
$fragment = $parts[1] ?? null;
$separator = str_contains($url, '?') ? '&' : '?';
$url .= $separator . 'v=' . rawurlencode($version);
return $fragment === null ? $url : $url . '#' . $fragment;
}
}
- Подключаем стратегию в Symfony. В
config/services.yamlдобавляем определение сервиса:
services:
App\Asset\VersionStrategy\ReleaseVersionStrategy:
arguments:
$versionFile: '%kernel.project_dir%/var/asset_version.txt'
В config/packages/framework.yaml указываем стратегию:
framework:
assets:
version_strategy: App\Asset\VersionStrategy\ReleaseVersionStrategy
Если в проекте уже есть настройки framework.assets, объедините параметры в существующем разделе, а не создавайте второй. Для работы необходимы установленные Symfony Asset Component и Twig-интеграция.
- Обновляем версию при релизе. Файл версии создаётся отдельной командой или скриптом развёртывания. Пример команды
bin/console app:mark-updatedвsrc/Command/MarkUpdatedCommand.php:
<?php
declare(strict_types=1);
namespace App\Command;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
#[AsCommand(
name: 'app:mark-updated',
description: 'Обновляет версию статических ресурсов',
)]
final class MarkUpdatedCommand extends Command
{
public function __construct(private readonly string $projectDir)
{
parent::__construct();
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$directory = $this->projectDir . '/var';
if (!is_dir($directory) && !mkdir($directory, 0775, true) && !is_dir($directory)) {
throw new \RuntimeException('Не удалось создать каталог var');
}
$version = bin2hex(random_bytes(8));
$path = $directory . '/asset_version.txt';
if (file_put_contents($path, $version, LOCK_EX) === false) {
throw new \RuntimeException('Не удалось записать версию статики');
}
$output->writeln('Версия статики: ' . $version);
return Command::SUCCESS;
}
}
Для автосвязывания аргумента конструктора в config/services.yaml добавляем:
services:
App\Command\MarkUpdatedCommand:
arguments:
$projectDir: '%kernel.project_dir%'
Затем выполняем:
php bin/console app:mark-updated
В результате ссылка css/app.css будет иметь вид /css/app.css?v=..., а ссылка img/sprite.svg#test-123 — /img/sprite.svg?v=...#test-123.
Важно: если используете OPcache, долгоживущие процессы, несколько экземпляров приложения или CDN, версия должна согласованно обновляться на всех экземплярах. При долгом кешировании HTML необходимо также продумать, когда браузер получит страницу с новыми URL ресурсов.
Итог
После релиза новые HTML-страницы будут содержать ссылки с обновлённой версией. Браузер воспринимает такие URL как новые ресурсы и загружает актуальные файлы, если сервер и промежуточные кеши настроены корректно.
Собственная стратегия полезна для существующих проектов, но имеет ограничение: при каждом изменении версии обновляются URL всех ресурсов, даже если изменился только один файл. Для новых проектов, где это возможно, разумнее рассмотреть AssetMapper или файлы с хешами содержимого через Webpack Encore.
Документация: AssetMapper, пользовательские стратегии версионирования, версионирование Webpack Encore.





