Версионирование ресурсов с Webpack Encore

Дата обновления перевода 2024-07-25

Версионирование ресурсов с Webpack Encore

Устали от того, что когда вы развёртываете, ваш браузер кеширует старую версию ваших ресурсов? Вызвав enableVersioning(), каждое имя файла теперь будет включать хеш, который будет изменяться каждый раз, когда будет изменяться содержимое этого файла(например, app.123abc.js вместо app.js). Это позволяет вам использовать агрессивные стратегии кеширования (например, Expires в отдалённом будущем), потому что каждый раз, когда меняется файл, будет меняться его хеш, игнорируя любой существующий кеш:

1
2
3
4
5
6
7
// webpack.config.js

// ...
Encore
    .setOutputPath('public/build/')
    // ...
+     .enableVersioning()

Чтобы связать эти ресурсы, Encore создаёт файл manifest.json со ссылкой на эти новые имена файлов.

Загрузка ресурсов из entrypoints.json и manifest.json

Каждый раз, когда вы запускаете Enconre, в вашей папке вывода генерируется два файла конфигурации (местоположение по умолчанию: public/build/): entrypoints.json и manifest.json. Оба файлы похожи между собой, и каждй содержит маршрут к финальным версионированными именам файлов.

Первый файл – entrypoints.json – используется помощниками Twig encore_entry_script_tags() и encore_entry_link_tags(). Если вы их используете, то ваши файлы CSS и JavaScript будут отображать новое, вресионированное имя файла. Если вы не используете Symfony, вашему приложению нужно будет прочитать этот файл схожим образом.

Файл manifest.json необходим только для того, чтобы получать версионированное имя файла других файлов, вроде файлов шрифтов или изображений (хотя он также содержит информацию о файлах CSS и JavaScript):

1
2
3
4
5
{
    "build/app.js": "/build/app.123abc.js",
    "build/dashboard.css": "/build/dashboard.a4bf2d.css",
    "build/images/logo.png": "/build/images/logo.3eed42.png"
}

В вашем приложении вам нужно прочесть этот файл, чтобы динамически отображать правильные маршруты в ваших тегах script и link. Если вы используете Symfony, просто активируйте версионирование стратегии json_manifest_file:

1
2
3
4
5
# этот файл добавляется автоматически при установке Encore с помощью Symfony Flex
# config/packages/assets.yaml
framework:
    assets:
        json_manifest_path: '%kernel.project_dir%/public/build/manifest.json'

Вот и всё! Просто не забудьте обернуть каждый путь в функцию Twig asset(), как обычно:

1
<img src="{{ asset('build/images/logo.png') }}" alt="ACME logo">

Диагностика и устранение неполадок

Версионирование ресурсов и развёртывание

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

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

Узнайте больше