Laravel - Compiling Assets (Mix)

Вступление

Laravel Mix предоставляет свободный API для определения шагов сборки Webpack для вашего приложения Laravel с использованием нескольких распространенных препроцессоров CSS и JavaScript. С помощью простой цепочки методов вы можете свободно определить свой конвейер активов. Например:

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

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

 

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

Установка узла

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

node -v
npm -v

По умолчанию Laravel Homestead включает в себя все, что вам нужно; однако, если вы не используете Vagrant, вы можете легко установить последнюю версию Node и NPM, используя простые графические установщики со страницы их загрузки .

Laravel Mix

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

npm install

 

Начало Mix

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

// Run all Mix tasks...
npm run dev

// Run all Mix tasks and minify output...
npm run production

Наблюдение за активами за изменениями

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

npm run watch

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

npm run watch-poll

 

Работа с таблицами стилей

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

Less

Этот less метод может быть использован для компиляции Less в CSS. Давайте скомпилируем наш основной файл в .app.lesspublic/css/app.css

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

Несколько вызовов lessметода могут быть использованы для компиляции нескольких файлов:

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

Если вы хотите настроить имя файла скомпилированного CSS, вы можете передать полный путь к файлу в качестве второго аргумента lessметода:

mix.less('resources/less/app.less', 'public/stylesheets/styles.css');

Если вам нужно переопределить базовые параметры плагина Less , вы можете передать объект в качестве третьего аргумента :mix.less()

mix.less('resources/less/app.less', 'public/css', {
    strictMath: true
});

Sass

sass метод позволяет компилировать Sass в CSS. Вы можете использовать метод следующим образом:

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

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

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

В качестве третьего аргумента могут быть предоставлены дополнительные параметры плагина Node-Sass :

mix.sass('resources/sass/app.sass', 'public/css', {
    precision: 5
});

Stylus

Подобно Less и Sass, stylusметод позволяет вам скомпилировать Stylus в CSS:

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

Вы также можете установить дополнительные плагины Stylus, такие как Rupture . Сначала установите соответствующий плагин через NPM ( npm install rupture), а затем потребуйте его при вызове :mix.stylus()

mix.stylus('resources/stylus/app.styl', 'public/css', {
    use: [
        require('rupture')()
    ]
});

 

PostCSS

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

mix.sass('resources/sass/app.scss', 'public/css')
   .options({
        postCss: [
            require('postcss-css-variables')()
        ]
   });

 

Plain CSS

Если вы просто хотите объединить несколько простых таблиц стилей CSS в один файл, вы можете использовать этот stylesметод.

mix.styles([
    'public/css/vendor/normalize.css',
    'public/css/vendor/videojs.css'
], 'public/css/all.css');

 

URL Processing

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

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

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

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

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

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

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

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

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

 

Source Maps

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

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

 

Работа с JavaScript

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

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

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

• Синтаксис ES2015.
• Модули
• Компиляция .vueфайлов.
• Минификация для производственных сред.

 

Поставщик извлечения

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

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

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

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

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

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

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

React

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

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

За кулисами Mix загрузит и включит соответствующий плагин Babel.babel-preset-react

Vanilla JS

Подобно объединению таблиц стилей , вы также можете комбинировать и минимизировать любое количество файлов JavaScript с помощью метода:mix.styles()scripts()

mix.scripts([
    'public/js/admin.js',
    'public/js/dashboard.js'
], 'public/js/all.js');

Эта опция особенно полезна для устаревших проектов, где вам не требуется компиляция Webpack для вашего JavaScript.

Небольшое изменение есть . Его подпись метода идентична ; однако объединенный файл получит компиляцию Babel, которая переводит любой код ES2015 в ванильный JavaScript, понятный для всех браузеров.mix.scripts()mix.babel()scripts

 

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

За кулисами Laravel Mix ссылается на предварительно сконфигурированный файл, чтобы вы как можно быстрее начали работать. Иногда вам может понадобиться вручную изменить этот файл. У вас может быть специальный загрузчик или плагин, на который нужно сослаться, или же вы предпочитаете использовать Stylus вместо Sass. В таких случаях у вас есть два варианта:webpack.config.js

Слияние пользовательских настроек

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

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

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

Если вы хотите полностью настроить конфигурацию Webpack, скопируйте файл в корневой каталог вашего проекта. Затем укажите все ссылки в вашем файле на вновь скопированный файл конфигурации. Если вы решите применить этот подход к настройке, любые будущие обновления Up для Mix должны быть вручную объединены в ваш настроенный файл.node_modules/laravel-mix/setup/webpack.config.js--configpackage.jsonwebpack.config.js

 

Копирование файлов и каталогов

Этот copyметод может быть использован для копирования файлов и каталогов в новые места. Это может быть полезно, когда конкретный ресурс в вашем node_modulesкаталоге должен быть перемещен в вашу publicпапку.

mix.copy('node_modules/foo/bar.css', 'public/css/bar.css');

При копировании каталога copyметод сгладит структуру каталога. Чтобы сохранить исходную структуру каталога, вы должны использовать copyDirectoryвместо этого метод:

mix.copyDirectory('resources/img', 'public/img');

 

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

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

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

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

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

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

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

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

if (mix.inProduction()) {
    mix.version();
}

 

Перегрузка Browsersync

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

mix.browserSync('my-domain.test');

// Or...

// https://browsersync.io/docs/options
mix.browserSync({
    proxy: 'my-domain.test'
});

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

 

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

Вы можете добавить переменные окружения в Mix, добавив префикс к ключу в вашем .envфайле MIX_:

MIX_SENTRY_DSN_PUBLIC=http://example.com

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

process.env.MIX_SENTRY_DSN_PUBLIC

 

Уведомления

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

mix.disableNotifications();