Skip to content
Laravel
Icon

ПРЕДУПРЕЖДЕНИЕ Вы просматриваете документацию к старой версии Laravel. Рассмотрите возможность обновления Вашего проекта до Laravel 9.x.

Компиляция асетов (Микс)

Введение

Laravel Mix, пакет, разработанный создателем Laracasts Джеффри Уэй, предоставляет свободный API для определения webpack шагов сборки для вашего приложения Laravel с использованием нескольких распространенных препроцессоров CSS и JavaScript.

Другими словами, Mix упрощает компиляцию и минимизацию файлов CSS и JavaScript вашего приложения. Посредством простой цепочки методов вы можете плавно определить свой конвейер ресурсов. Например:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css');

Если вы когда-либо были сбиты с толку и ошеломлены, начав работу с веб-пакетами и компиляцией ресурсов, вам понравится Laravel Mix. Однако от вас не требуется использовать его при разработке приложения; вы можете использовать любой инструмент конвейера ресурсов, который пожелаете, или даже не использовать его вовсе.

{tip} Если вам нужно начать разработку приложения с помощью Laravel и Tailwind CSS, ознакомьтесь с одним из наших стартовых наборов приложений.

Установка и настройка

Установка Node

Перед запуском Mix вы должны сначала убедиться, что на вашем компьютере установлены Node.js и NPM:

node -v
npm -v

Вы можете легко установить последнюю версию Node и NPM с помощью простых графических установщиков с официального веб-сайта Node. Или, если вы используете Laravel Sail, вы можете вызывать Node и NPM через Sail:

./sail node -v
./sail npm -v

Установка Laravel Mix

Единственный оставшийся шаг - установить Laravel Mix. В новой установке Laravel вы найдете файл package.json в корне вашей структуры каталогов. Файл package.json по умолчанию уже включает в себя все, что вам нужно для начала работы с Laravel Mix. Думайте об этом файле как о вашем файле composer.json, за исключением того, что он определяет зависимости Node вместо зависимостей PHP. Вы можете установить зависимости, на которые он ссылается, запустив:

npm install

Запуск микса

Mix - это уровень конфигурации поверх webpack, поэтому для выполнения задач Mix вам нужно выполнить только один из сценариев NPM, которые включены в стандартный пакет Laravel файла package.json. Когда вы запускаете сценарии dev или production, все ресурсы CSS и JavaScript вашего приложения будут скомпилированы и помещены в каталог public:

// Выполнить все задачи Mix...
npm run dev
 
// Запускать все задачи Mix и минимизировать вывод...
npm run prod

Наблюдение за ресурсами на предмет изменений

Команда npm run watch продолжит работу в вашем терминале и будет следить за изменениями во всех соответствующих файлах CSS и JavaScript. Webpack автоматически перекомпилирует ваши ресурсы, когда обнаружит изменение в одном из этих файлов:

npm run watch

Webpack может не обнаруживать изменения ваших файлов в определенных локальных средах разработки. Если это так в вашей системе, рассмотрите возможность использования команды watch-poll:

npm run watch-poll

Работа со стилями

Файл webpack.mix.js вашего приложения является отправной точкой для компиляции всех ресурсов. Думайте об этом как о легкой оболочке конфигурации вокруг webpack. Задачи Mix можно объединить в цепочку, чтобы точно определить, как должны компилироваться ваши ресурсы.

Tailwind CSS

Tailwind CSS - это современная, ориентированная на полезность фреймворк для создания потрясающих сайтов, не покидая своего HTML. Давайте рассмотрим, как начать использовать его в проекте Laravel с Laravel Mix. Во-первых, мы должны установить Tailwind с помощью NPM и сгенерировать наш файл конфигурации Tailwind:

npm install
 
npm install -D tailwindcss
 
npx tailwindcss init

Команда init создаст файл tailwind.config.js. Раздел content этого файла позволяет настроить пути ко всем вашим HTML-шаблонам, компонентам JavaScript и любым другим исходным файлам, содержащим имена классов Tailwind, чтобы все классы CSS, не используемые в этих файлах, были удалены из ваша производственная сборка CSS:

content: [
    './storage/framework/views/*.php',
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
],

Затем вы должны добавить каждый из «слоев» Tailwind в файл resources/css/app.css вашего приложения:

@tailwind base;
@tailwind components;
@tailwind utilities;

После того, как вы настроили слои Tailwind, вы готовы обновить файл webpack.mix.js вашего приложения, чтобы скомпилировать ваш CSS на основе Tailwind:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css', [
        require('tailwindcss'),
    ]);

Наконец, вы должны указать свою таблицу стилей в основном шаблоне макета вашего приложения. Многие приложения предпочитают хранить этот шаблон в resources/views/layouts/app.blade.php. Кроме того, убедитесь, что вы добавили метатег meta адаптивного окна просмотра, если он еще не присутствует:

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="/css/app.css" rel="stylesheet">
</head>

PostCSS

PostCSS, , мощный инструмент для преобразования вашего CSS, включен в Laravel Mix из коробки. По умолчанию Mix использует популярный плагин Autoprefixer для автоматического применения всех необходимых префиксов поставщиков CSS3. Однако вы можете добавлять любые дополнительные плагины, подходящие для вашего приложения.

Сначала установите нужный плагин через NPM и включите его в свой массив плагинов при вызове метода Mix postCss. Метод postCss принимает путь к вашему файлу CSS в качестве первого аргумента и каталог, в который следует поместить скомпилированный файл, в качестве второго аргумента:

mix.postCss('resources/css/app.css', 'public/css', [
    require('postcss-custom-properties')
]);

Или вы можете выполнить postCss без дополнительных плагинов, чтобы добиться простой компиляции и минификации CSS:

mix.postCss('resources/css/app.css', 'public/css');

Sass

Метод sass позволяет вам скомпилировать Sass в CSS, понятный веб-браузерам. Метод sass принимает путь к вашему файлу Sass в качестве первого аргумента и каталог, в который следует поместить скомпилированный файл, в качестве второго аргумента:

mix.sass('resources/sass/app.scss', 'public/css');

Вы можете скомпилировать несколько файлов Sass в их собственные соответствующие файлы CSS и даже настроить выходной каталог результирующего CSS, вызвав метод sass несколько раз:

mix.sass('resources/sass/app.sass', 'public/css')
    .sass('resources/sass/admin.sass', 'public/css/admin');

Обработка URL

Поскольку Laravel Mix построен поверх webpack, важно понимать несколько концепций webpack. Для компиляции CSS webpack перепишет и оптимизирует любые вызовы url() в ваших таблицах стилей. Хотя поначалу это может показаться странным, это невероятно мощный функционал. Представьте, что мы хотим скомпилировать Sass, который включает относительный URL-адрес изображения:

.example {
    background: url('../images/example.png');
}

{note} Абсолютные пути для любого заданного url() будут исключены из перезаписи URL. Например, url('/images/thing.png') или url('http://example.com/images/thing.png') не будут изменены.

По умолчанию Laravel Mix и webpack найдут example.png, скопируют его в вашу папку public/images, а затем перепишут url() в созданной вами таблице стилей. Таким образом, ваш скомпилированный CSS будет:

.example {
    background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);
}

Какой бы полезной ни была эта функция, ваша существующая структура папок может быть уже настроена так, как вам нравится. В этом случае вы можете отключить перезапись url() следующим образом:

mix.sass('resources/sass/app.scss', 'public/css').options({
    processCssUrls: false
});

С этим добавлением к вашему файлу webpack.mix.js, Mix больше не будет сопоставлять какой-либо url() или копировать ресурсы в ваш общедоступный каталог. Другими словами, скомпилированный CSS будет выглядеть так же, как вы его изначально набирали:

.example {
    background: url("../images/thing.png");
}

Исходные карты

Хотя по умолчанию они отключены, исходные карты могут быть активированы путем вызова метода mix.sourceMaps() в вашем файле webpack.mix.js. Хотя это связано с затратами на компиляцию / производительность, это предоставит дополнительную отладочную информацию инструментам разработчика вашего браузера при использовании скомпилированных ресурсов:

mix.js('resources/js/app.js', 'public/js')
    .sourceMaps();

Стиль исходных карт

Webpack предлагает множество стилей сопоставления источников. По умолчанию стиль сопоставления исходного кода Mix установлен на eval-source-map, что обеспечивает быстрое время восстановления. Если вы хотите изменить стиль сопоставления, вы можете сделать это с помощью метода sourceMaps:

let productionSourceMaps = false;
 
mix.js('resources/js/app.js', 'public/js')
    .sourceMaps(productionSourceMaps, 'source-map');

Работа с JavaScript

Mix предоставляет несколько функций, которые помогут вам работать с вашими файлами JavaScript, такими как компиляция современного ECMAScript, объединение модулей, минификация и объединение простых файлов JavaScript. Более того, все это работает без проблем, не требуя ни унции специальной конфигурации:

mix.js('resources/js/app.js', 'public/js');

С помощью этой единственной строчки кода теперь вы можете воспользоваться следующими преимуществами:

- Последний синтаксис EcmaScript. - Модули. - Минификация для продакшен сред.

Vue

Mix автоматически установит плагины Babel, необходимые для поддержки компиляции однофайловых компонентов Vue при использовании метода vue. Никакой дополнительной настройки не требуется:

mix.js('resources/js/app.js', 'public/js')
   .vue();

После того, как ваш JavaScript скомпилирован, вы можете ссылаться на него в своем приложении:

<head>
    <!-- ... -->
 
    <script src="/js/app.js"></script>
</head>

React

Mix может автоматически устанавливать плагины Babel, необходимые для поддержки React. Для начала добавьте вызов метода react:

mix.js('resources/js/app.jsx', 'public/js')
   .react();

За кулисами Mix загрузит и включит соответствующий плагин Babel babel-preset-react. После того, как ваш JavaScript скомпилирован, вы можете ссылаться на него в своем приложении:

<head>
    <!-- ... -->
 
    <script src="/js/app.js"></script>
</head>

Извлечение вендора

Одним из потенциальных недостатков объединения всего кода JavaScript для конкретного приложения с библиотеками вендора, такими как React и Vue, является то, что это затрудняет долгосрочное кэширование. Например, одно обновление кода вашего приложения заставит браузер повторно загрузить все библиотеки вашего вендора, даже если они не изменились.

Если вы намереваетесь часто обновлять JavaScript своего приложения, вам следует рассмотреть возможность извлечения всех библиотек вашего вендора в их собственный файл. Таким образом, изменение кода вашего приложения не повлияет на кеширование вашего большого файла vendor.js. Метод Mix extract упрощает задачу:

mix.js('resources/js/app.js', 'public/js')
    .extract(['vue'])

Метод extract принимает массив всех библиотек или модулей, которые вы хотите извлечь в файл vendor.js. Используя приведенный выше фрагмент в качестве примера, Mix сгенерирует следующие файлы:

- `public/js/manifest.js`: *Среда выполнения манифеста Webpack* - `public/js/vendor.js`: *Ваши vendor-библиотеки* - `public/js/app.js`: *Код вашего приложения*

Чтобы избежать ошибок JavaScript, обязательно загружайте эти файлы в правильном порядке:

<script src="/js/manifest.js"></script>
<script src="/js/vendor.js"></script>
<script src="/js/app.js"></script>

Пользовательская конфигурация Webpack

Иногда вам может потребоваться вручную изменить базовую конфигурацию Webpack. Например, у вас может быть специальный загрузчик или плагин, на который нужно сослаться.

Mix предоставляет полезный метод webpackConfig, который позволяет вам объединить любые короткие переопределения конфигурации Webpack. Это особенно привлекательно, поскольку не требует от вас копирования и поддержки вашей собственной копии файла webpack.config.js. Метод webpackConfig принимает объект, который должен содержать любую специфичную для Webpack конфигурацию, которую вы хотите применить.

mix.webpackConfig({
    resolve: {
        modules: [
            path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js')
        ]
    }
});

Управление версиями / очистка кеша

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

Метод version добавит уникальный хэш к именам файлов всех скомпилированных файлов, что сделает очистку кеша более удобной:

mix.js('resources/js/app.js', 'public/js')
    .version();

После создания версионного файла вы не узнаете точное имя файла. Итак, вы должны использовать глобальную функцию Laravel mix в ваших представлениях, чтобы загрузить соответствующим образом хешированный ресурс. Функция mix автоматически определит текущее имя хешированного файла:

<script src="{{ mix('/js/app.js') }}"></script>

Поскольку файлы с поддержкой версий обычно не нужны при разработке, вы можете указать процессу управления версиями запускаться только во время npm run prod:

mix.js('resources/js/app.js', 'public/js');
 
if (mix.inProduction()) {
    mix.version();
}

Пользовательские Mix URL-адреса

Если ваши скомпилированные ресурсы Mix развернуты в CDN отдельно от вашего приложения, вам нужно будет изменить базовый URL-адрес, сгенерированный функцией mix. Вы можете сделать это, добавив параметр конфигурации mix_url в файл конфигурации вашего приложения config/app.php:

'mix_url' => env('MIX_ASSET_URL', null)

После настройки URL-адреса Mix функция mix будет префикс настроенного URL-адреса при создании URL-адресов для ресурсов:

https://cdn.example.com/js/app.js?id=1964becbdd96414518cd

Перезагрузка Browsersync

BrowserSync может автоматически отслеживать изменения в ваших файлах и вносить изменения в браузер без необходимости обновления вручную. Вы можете включить поддержку этого, вызвав метод mix.browserSync():

mix.browserSync('laravel.test');

BrowserSync options можно указать, передав объект JavaScript в метод browserSync:

mix.browserSync({
    proxy: 'laravel.test'
});

Затем запустите сервер разработки webpack с помощью команды npm run watch. Теперь, когда вы изменяете скрипт или файл PHP, вы можете наблюдать, как браузер мгновенно обновляет страницу, чтобы отразить ваши изменения.

Переменные среды

Вы можете вставить переменные среды в свой сценарий webpack.mix.js, добавив к одной из переменных среды в вашем файле .env префикс MIX_:

MIX_SENTRY_DSN_PUBLIC=http://example.com

После того, как переменная была определена в вашем файле .env, вы можете получить к ней доступ через объект process.env. Однако вам нужно будет перезапустить задачу, если значение переменной среды изменится во время выполнения задачи:

process.env.MIX_SENTRY_DSN_PUBLIC

Уведомления

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

mix.disableNotifications();