Подача ресурсів у розробці проти виробництва

У середовищі dev, URL - /assets/images/duck-3c16d9220694c0e56d8648f25e6035e9.png - обробляється та повертається вашим додатком Symfony. Для середовища prod, до розгортання, ви маєте виконати:

1

$ php bin/console asset-map:compile

Це фізично скопіює всі файли з ваших мапованих каталогів у public/assets/, щоб вони видавалися напряму вашим веб-сервером. Дивіться Розгортання , щоб дізнатися більше.

Налагодження: як побачити всі маповані ресурси

Щоб побачити всі маповані ресурси у вашому додатку, виконайте:

1

$ php bin/console debug:asset-map

Це відобразить вам усі маповані шляхи та ресурси всередині кожного:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Шляхи AssetMapper
-----------------

--------- --------------------------
 Шлях      Префікс з простором імен
--------- --------------------------
assets

Mapped Assets
-------------

------------------ ----------------------------------------------------
 Логічний шлях      Шлях файлової системи
------------------ ----------------------------------------------------
 app.js             assets/app.js
 styles/app.css     assets/styles/app.css
 images/duck.png    assets/images/duck.png

"Логічний шлях" - це шлях, який слід використовувати при посиланні на ресурс, наприклад, з шаблону.

Імпорт сторонніх пакетів JavaScript

Припустимо, ви хочете використати пакет npm, наприклад bootstrap. Технічно, це можна зробити, імпортувавши його повну URL-адресу, наприклад, з CDN:

1

import { Alert } from 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm';

Але ой! Необхідність додавання цієї URL-адреси - це біль! Замість цього ми можемо додати її до нашої "importmap" за допомогою команди importmap:require. Цю команду можна використати для завантаження будь-якого пакету npm:

1

$ php bin/console importmap:require bootstrap

Це додає пакет bootstrap до вашого файлу importmap.php:

1
2
3
4
5
6
7
8
9
10

// importmap.php
return [
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    'bootstrap' => [
        'version' => '5.3.0',
    ],
];

Тепер ви можете імпортувати пакет bootstrap як звичайно:

1
2

import { Alert } from 'bootstrap';
// ...

Усі пакети в importmap.php завантажуються до каталогу assets/vendor/,
який слід ігнорувати git'у (рецепт Flex додає його до .gitignore за вас). Щоб завантажити файли на інші комп'ютери, вам слід виконати наступну команду якщо деякі з них відсутні:

1

$ php bin/console importmap:install

Ви можете оновити сторонні пакети до їхніх поточних версій виконавши:

1
2
3
4
5
6
7
8

# перелічує застарілі пакети і показує їхні найновіші версії 
$ php bin/console importmap:outdated
# оновлює всі застарілі пакети
$ php bin/console importmap:update

# ви також можете запустити команди лише для заданого списку пакетів 
$ php bin/console importmap:update bootstrap lodash
$ php bin/console importmap:outdated bootstrap lodash

Як працює importmap?

Як цей файл importmap.php дозволяє вам імпортувати bootstrap? Це відбувається завдяки функції Twig {{ importmap() }} в base.html.twig, яка виводить importmap:

1
2
3
4
5
6
7

<script type="importmap">{
    "imports": {
        "app": "/assets/app-4e986c1a2318dd050b1d47db8d856278.js",
        "/assets/duck.js": "/assets/duck-1b7a64b3b3d31219c262cf72521a5267.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/+esm"
    }
}</script>

Мапи імпорту - це вбудована функція браузера. Коли ви імпортуєте bootstrap з JavaScript, браузер подивиться на importmap і побачить, що він повинен отримати пакет з асоційованого шляху.

Але звідки взявся запис імпорту /assets/duck.js? Це не живе в importmap.php.Чудове питання!

Файл assets/app.js вище імпортує ./duck.js. Коли ви імпортуєте файл за допомогою відносного шляху, ваш браузер шукає цей файл відносно того, що імпортує його. Отже, він шукатиме /assets/duck.js. Цей URL був би правильним, за винятком того, що файл duck.js є версіонованим. На щастя, компонент AssetMapper бачить цей імпорт і додає мапування з /assets/duck.js до правильного, версіонованого імені файлу. Результат: імпорт ./duck.js просто працює!

Функція importmap() також виводить ES-модуль shim, щоб старіші браузери розуміли мапи імпорту (див. конфігурацію polyfill ).

Точка входу та попереднє завантаження "app"

"Точка входу" - це основний файл JavaScript, який завантажує браузер, і ваш додаток починається з нього за замовчуванням:

1
2
3
4
5
6
7
8

// importmap.php
return [
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    // ...
];

На додаток до мапи імпорту, {{ importmap('app') }} у base.html.twig виводить декілька інших речей, зокрема:

1

<script type="module">import 'app';</script>

Цей рядок вказує браузеру завантажити запис мапи імпорту app, що призводить до виконання коду у файлі assets/app.js.

Функція importmap() також виводить набір "попередніх завантажень":

1
2

<link rel="modulepreload" href="/assets/app-4e986c1a2318dd050b1d47db8d856278.js">
<link rel="modulepreload" href="/assets/duck-1b7a64b3b3d31219c262cf72521a5267.js">

Це оптимізація продуктивності, про яку ви можете дізнатися нижче у Продуктивність: Додавання попереднього завантаження .

Імпорт конкретних файлів зі стороннього пакета

Іноді вам буде потрібно імпортувати конкретний файл з пакета. Наприклад, припустимо, ви інтегруєте highlight.js і хочете імпортувати лише ядро і певну мову:

1
2
3
4
5

import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';

hljs.registerLanguage('javascript', javascript);
hljs.highlightAll();

У цьому випадку додавання пакета highlight.js до вашого файлу importmap.php не спрацює: що б ви не імпортували - наприклад, highlight.js/lib/core - має точно співпадати із записом у файлі importmap.php.

Замість цього використайте importmap:require і передайте йому точні шляхи, які вам потрібні. Цей приклад також показує, як можна вимагати декілька пакетів одночасно:

1

$ php bin/console importmap:require highlight.js/lib/core highlight.js/lib/languages/javascript

Глобальні змінні на кшталт jQuery

Можливо, ви звикли покладатися на глобальні змінні, такі як змінна $ в jQuery:

1
2
3
4
5

// assets/app.js
import 'jquery';

// app.js або будь-який інший файл
$('.something').hide(); // НЕ ПРАЦЮВАТИМЕ!

Але у модульному середовищі (наприклад, в AssetMapper), коли ви імпортуєте бібліотеку типу jquery, вона не створює глобальну змінну. Натомість, вам слід імпортувати її і встановити як змінну у кожному файлі, де вона вам потрібна:

1
2

import $ from 'jquery';
$('.something').hide();

Ви навіть можете зробити це з тегу вбудованого скрипта:

1
2
3
4

<script type="module">
    import $ from 'jquery';
    $('.something').hide();
</script>

Якщо вам необхідно зробити щось глобальною змінною, зробіть це вручну зсередини app.js:

1
2
3

import $ from 'jquery';
// речі у "window" стають глобальними змінними
window.$ = $;

Шляхи всередині CSS-файлів

Зсередини CSS ви можете посилатися на інші файли за допомогою звичайної функції CSS url() і відносним шляхом до цільового файлу:

1
2
3
4
5

/* assets/styles/app.css */
.quack {
    /* file lives at assets/images/duck.png */
    background-image: url('../images/duck.png');
}

Шлях у фінальному файлі app.css буде автоматично включено до оновленої URL-адреси для duck.png:

1
2
3
4

/* public/assets/styles/app-3c16d9220694c0e56d8648f25e6035e9.css */
.quack {
    background-image: url('../images/duck-3c16d9220694c0e56d8648f25e6035e9.png');
}

Використання Tailwind CSS

Щоб використовувати CSS-фреймворк Tailwind з компонентом AssetMapper, ознайомтеся з symfonycasts/tailwind-bundle.

Використання Sass

Щоб використовувати Sass з компонентом AssetMapper, ознайомтеся з symfonycasts/sass-bundle.

Лінивий імпорт CSS з файлу JavaScript

Якщо у вас є деякий CSS, який ви хочете завантажити ліниво, ви можете зробити це за допомогою звичайного, "динамічного" синтаксису імпорту:

1
2
3
4

// assets/any-file.js
import('./lazy.css');

// ...

У цьому випадку lazy.css буде завантажено асинхронно, а потім додано на сторінку. Якщо ви використовуєте динамічний імпорт для лінивого завантаження JavaScript-файлу, і цей файл імпортує файл CSS (використовуючи нединамічний синтаксис import), цей файл CSS також буде завантажено асинхронно.

Відсутній запис importmap

Одна з найпоширеніших помилок буде виходити з консолі вашого браузера і буде приблизно такою:

Failed to resolve module specifier " bootstrap". Relative references must start with either "/", "./", or "../".

Або:

The specifier "bootstrap" was a bare specifier, but was not remapped to anything. Relative module specifiers must start with "./", "../" or "/".

Це означає, що десь у вашому JavaScript ви імпортуєте сторонній пакет, наприклад, import 'bootstrap'. Браузер намагається знайти цей пакет у вашому файлі importmap, але його там немає.

Майже завжди це можна виправити, додавши його до вашого importmap:

1

$ php bin/console importmap:require bootstrap

404 Не знайдено для файлу JavaScript, CSS або зображення

Іноді файл JavaScript, який ви імпортуєте (наприклад, import './duck.js'), або файл CSS/зображення, на який ви посилаєтеся, не буде знайдено, і ви побачите помилку 404 у консолі вашого браузера. Ви також помітите, що в URL 404 відсутній хеш версії в імені файлу (наприклад, 404 до /assets/duck.js замість шляху на кшталт /assets/duck.1b7a64b3b3d31219c262cf72521a5267.js).

Зазвичай це відбувається тому, що шлях вказано неправильно. Якщо ви посилаєтеся на файл безпосередньо в шаблоні Twig:

1

<img src="{{ asset('images/duck.png') }}">

Тоді шлях, який ви передаєте asset() має бути "логічним шляхом" до файлу. Використайте команду debug:asset-map, щоб побачити всі валідні логічні шляхи у вашому додатку.

Швидше за все, ви імпортуєте непрацюючий ресурс з файлу CSS (наприклад @import url('other.css')) або файлу JavaScript:

1
2

// assets/controllers/farm-controller.js
import '../farm/chicken.js';

При цьому шлях має бути відносним до файлу, який його імпортує (а в JavaScript-файлах він повинен починатися з ./ або ../). У цьому випадку ../farm/chicken.js буде вказувати на assets/farm/chicken.js. Щоб переглянути список всіх невалідних імпортованих даних у вашому додатку, виконайте:

1
2

$ php bin/console cache:clear
$ php bin/console debug:asset-map

Будь-який невалідний імпорт буде показано у вигляді попереджень у верхній частині екрану (переконайтеся, що у вас встановлено symfony/monolog-bundle):

1
2

WARNING   [asset_mapper] Unable to find asset "../images/ducks.png" referenced in "assets/styles/app.css".
WARNING   [asset_mapper] Unable to find asset "./ducks.js" imported from "assets/app.js".

Попередження про відсутній ресурс у коментованому коді

Компонент AssetMapper шукає у ваших файлах JavaScript рядки import, щоб він міг автоматично додати їх до вашої мапи імпорту . Це робиться через регулярний вираз і працює дуже добре, хоча і не ідеально. Якщо ви закоментуєте імпорт, його все одно буде знайдено і додано до вашої карти імпорту. Це нічому не зашкодить, але може бути несподіванкою.

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

Продуктивність: розуміння попереднього завантаження

Одна з поширених проблем, про яку може повідомити LightHouse, наступна:

Avoid Chaining Critical Requests

Декілька елементів у цьому списку це нормально. Але якщо цей список довгий або деякі елементи на глибині багатьох рівнів, то вам це треба виправити за допомогою "попереднього завантаження". Щоб зрозуміти проблему, уявіть, що у вас таке налаштування:

• assets/app.js імпортує ./duck.js
• assets/duck.js імпортує bootstrap

Коли браузер завантажує сторінку, відбувається наступне:

1. Браузер завантажує assets/app.js;
2. Потім він бачить імпорт ./duck.js і завантажує assets/duck.js;
3. Потім він бачить імпорт bootstrap і завантажує assets/bootstrap.js.

Замість того, щоб завантажувати всі 3 файли паралельно, браузер буде змушений завантажувати їх по черзі, коли він їх виявлятиме. Це може негативно вплинути на продуктивність.

AssetMapper уникає цієї проблеми, виводячи "попередньо завантажені" теги link. Логіка працює наступним чином:

A) Коли ви викликаєте importmap('app') у вашому шаблоні, компонент AssetMapper переглядає файл assets/app.js і знаходить усі файли JavaScript які він імпортує, або файли, які імпортують ці файли, тощо.

B) Потім він виводить тег link для кожного з цих файлів з атрибутом rel="preload". Це вказує браузеру почати завантаження цих файлів негайно, навіть якщо він ще не бачив ствердження import для них.

Крім того, якщо у вашому додатку доступний компонент WebLink, Symfony додасть заголовок Link у відповідь, щоб попередньо завантажити файли CSS.

Чи об'єднує компонент AssetMapper ресурси?

Ні! Але це тому, що в цьому більше немає необхідності!

У минулому було прийнято об'єднувати ресурси, щоб зменшити кількість HTTP-запитів, які були зроблені. Завдяки розвитку веб-серверів, таких як HTTP/2, зазвичай не є проблемою тримати ваші ресурси окремо і дозволити браузеру завантажувати їх паралельно. Насправді,
якщо ви тримаєте їх окремо, коли ви оновлюєте один ресурс, браузер може продовжувати використовувати кешовану версію всіх інших ваших ресурсів.

Дивіться Оптимізація для отримання більш детальної інформації.

Чи мінімізує компонент AssetMapper ресурси?

Ні! Мінімізація або стиснення ресурсів важлива, але може бути виконана вашим веб-сервером або за допомогою сервісу на кшталт Cloudflare. Дивіться Оптимізація для більш детальної інформації.

Чи готовий компонент AssetMapper до виробництва? Він продуктивний?

Так! Дуже! Компонент AssetMapper використовує досягнення у технологіях браузерів (наприклад importmaps і нативну підтримку import ) і веб-серверів (наприклад, HTTP/2, який дозволяє ресурсам завантажуватися паралельно). Дивіться інші питання про мінімізацію та комбінування і Оптимізацію для більш детальної інформації.

Сайт https://ux.symfony.com працює на компоненті AssetMapper і має 99% оцінку від Google Lighthouse.

Чи працює компонент AssetMapper з усіма браузерами?

Так! Такі функції, як importmaps та ствердження import підтримуються у всіх сучасних браузерах, але компонент AssetMapper постачається з ES-модулем shim для підтримки importmap у старих браузерах. Отже, він працює скрізь (див. примітку нижче).

У вашому власному коді, якщо ви покладаєтеся на сучасні можливості функцій JavaScript ES6, наприклад, синтаксис класів, це підтримується у всіх браузерах, окрім найстаріших. Якщо вам необхідно підтримувати дуже старі браузери, вам слід скористатися таким інструментом, як Encore замість компонента AssetMapper.

1
2
3
4
5
6
7

// це працює
import { add } from './math.js';

// це не працюватиме у найстаріших браузерах
import('./math.js').then(({ add }) => {
    // ...
});

Чи можу я використовувати це з Sass або Tailwind?

Звичайно! Дивіться Використання Tailwind CSS або Використання Sass .

Чи можу я використовувати це з TypeScript?

Звичайно! Дивіться Використання TypeScript .

Чи можу я використовувати це з JSX або Vue?

Напевно, ні. І якщо ви пишете додаток на React, Svelte або іншому фронтенд-фреймворку, вам, ймовірно, буде краще використовувати безпосередньо їхні інструменти.

JSX можна скомпілювати безпосередньо у нативний JavaScript-файл, але якщо ви використовуєте багато JSX, вам, ймовірно, захочеться використати інструмент на кшталт Encore . Дивіться Документацію UX React для більш детальної інформації про використання з компонентом AssetMapper.

Vue-файли можуть бути написані на нативному JavaScript, і вони будуть працювати з з компонентом AssetMapper. Але ви не можете писати однофайлові компоненти (тобто файли .vue) за допомогою компонента, оскільки вони мають бути використані у системі побудови. Зверніться до Документації UX Vue.js для більш детальної інформації про використання з з компонентом AssetMapper.

Перевизначення сторонніх ресурсів

Якщо ви хочете перевизначити сторонній ресурс, ви можете зробити це, створивши файл у вашому каталозі assets/ з тим самим ім'ям. Наприклад, якщо ви хочете перевизначити файл pagerfanta.css, створіть файл за адресою assets/bundles/babdevpagerfanta/css/pagerfanta.css. Цей файл використовуватиметься замість оригінального файлу.

framework.asset_mapper.paths

Ця конфігурація містить всі каталоги, які будуть проскановані на наявність ресурсів. Це може бути простим списком:

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            - assets/
            - vendor/some/package/assets

Ви можете надати кожному шляху "простір імен", який буде використано у мапі ресурсів:

1
2
3
4
5

framework:
    asset_mapper:
        paths:
            assets/: ''
            vendor/some/package/assets/: 'some-package'

У цьому випадку "логічний шлях" до всіх файлів у каталозі vendor/some/package/assets/ буде доповнено префіксом some-package - наприклад, some-package/foo.js.

framework.asset_mapper.excluded_patterns

Це список глобальних патернів, які будуть виключені з мапи ресурсів:

1
2
3
4

framework:
    asset_mapper:
        excluded_patterns:
            - '*/*.scss'

Ви можете використати команду debug:asset-map, щоб перевірити, що очікувані вами файли включені у мапу ресурсів.

framework.asset_mapper.exclude_dotfiles

Чи вилучати з маппера будь-які файли, що починаються з .. Цей корисно, якщо ви хочете уникнути витоку чутливих файлів, таких як .env або .gitignore у файлах, опублікованих маппером ресурсів.

1
2
3

framework:
    asset_mapper:
        exclude_dotfiles: true

Ця опція ввімкнена за замовчуванням.

framework.asset_mapper.importmap_polyfill

Конфігурує полізаповнення для старих браузерів. За замовчуванням, ES-модуль shim завантажується через CDN (тобто значенням за замовчуванням для цього параметра є `es-module-shims`):

1
2
3
4
5
6
7
8
9

framework:
    asset_mapper:
        # встановіть цю опцію як false, щоб повністю вимкнути shim
        # (ваш сайт/додаток не буде працювати в старих браузерах)
        importmap_polyfill: false

        # ви також можете використовувати користувацьке полізаповнення, додавши його до файлу importmap.php
        # і встановивши цю опцію як ключ цього файлу у файлі importmap.php
        # importmap_polyfill: 'custom_polyfill'

1

$ php bin/console importmap:require es-module-shims

framework.asset_mapper.importmap_script_attributes

Це список атрибутів, які будуть додані до тегів <script>, відображених функцією
Twig {{ importmap() }}:

1
2
3
4

framework:
    asset_mapper:
        importmap_script_attributes:
            crossorigin: 'anonymous'