编辑资源 Mix · laravel 5.4

<article><h1>Laravel 的资源任务编译器 Laravel Mix</h1><ul><li><a href="#introduction">简介</a></li><li><a href="#installation">安装与配置</a></li><li><a href="#running-mix">运行 Mix</a></li><li><a href="#working-with-stylesheets">使用样式</a><ul><li><a href="#less">Less</a></li><li><a href="#sass">Sass</a></li><li><a href="#stylus">Stylus</a></li><li><a href="#postcss">PostCSS</a></li><li><a href="#plain-css">纯 CSS</a></li><li><a href="#url-processing">URL 处理</a></li><li><a href="#css-source-maps">资源地图</a></li></ul></li><li><a href="#working-with-scripts">使用脚本</a><ul><li><a href="#vendor-extraction">提取 Vendor</a></li><li><a href="#react-support">React</a></li><li><a href="#vanilla-js">原生 JS</a></li><li><a href="#custom-webpack-configuration">自定义 Webpack 配置</a></li></ul></li><li><a href="#copying-files-and-directories">复制文件与目录</a></li><li><a href="#versioning-and-cache-busting">版本与缓存清除</a></li><li><a href="#browsersync-reloading">Browsersync 自动加载刷新</a></li><li><a href="#notifications">通知</a></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>Laravel Mix 提供了简洁流畅的 API，让你能够为你的 Laravel 应用定义 Webpack 的编译任务。Mix 支持许多常见的 CSS 与 JavaScrtip 预处理器，通过简单的方法，你可以轻松的管理资源。例如：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js') .sass('resources/assets/sass/app.scss', 'public/css');</code></pre>如果你曾经对于使用 Webpack 及编译资源感到困惑，那么你绝对会爱上 Laravel Mix。当然，在 Laravel 应用开发中使用 Mix 并不是必须的，你也可以选择任何你喜欢的资源编译工具，或者不使用任何工具。<a name="installation"></a><h2><a href="#installation">安装</a></h2><h4>安装 Node</h4>在开始使用 Mix 之前，你必须先确定你的开发环境上有安装 Node.js 和 NPM。<pre class=" language-php"><code class=" language-php">node -v npm -v</code></pre>默认情况下, Laravel Homestead 会包含你所需的一切。当然，如果你没有使用 Vagrant，那么你可以浏览 <a href="https://nodejs.org/en/download/">nodejs</a> 下载可视化的安装工具来安装最新版的 Node 和 NPM.<h4>Laravel Mix</h4>剩下的只需要安装 Laravel Mix！随着新安装的 Laravel, 你会发现根目录下有个名为 <code class=" language-php">package.json</code> 的文件。就如同 <code class=" language-php">composer.json</code> 文件, 只不过 <code class=" language-php">package.json</code> 文件定义的是 Node 的依赖，而不是 PHP。你可以使用以下的命令安装依赖扩展包：<pre class=" language-php"><code class=" language-php">npm install</code></pre>如果你使用的是 Windows 系统或运行在 Windows 系统上的 VM, 你需要在运行 <code class=" language-php">npm install</code> 命令时将 <code class=" language-php">--no-bin-links</code> 开启：<pre class=" language-php"><code class=" language-php">npm install --no-bin-links</code></pre><a name="running-mix"></a><h2><a href="#running-mix">使用</a></h2>Mix 基于 <a href="https://webpack.js.org">Webpack</a> 的配置，所以运行定义于 <code class=" language-php">package.json</code> 文件中的 NPM 脚本即可执行 Mix 的编译任务:<pre class=" language-php"><code class=" language-php">// 运行所有 Mix 任务... npm run dev // 运行所有 Mix 任务和压缩资源输出 npm run production</code></pre><h4>监控资源文件修改</h4><code class=" language-php">npm run watch</code> 会在你的终端里持续运行，监控资源文件是否有发生改变。在 watch 命令运行的情况下，一旦资源文件发生变化，Webpack 会自动重新编译：<pre class=" language-php"><code class=" language-php">npm run watch</code></pre>你可能会发现，在某些环境下，当你改变了你的文件的时候而 Webpack 并没有同步更新。如果在你的系统中出现了这个问题，你可以考虑使用 <code class=" language-php">watch-poll</code> 命令：<pre class=" language-php"><code class=" language-php">npm run watch-poll</code></pre><a name="working-with-stylesheets"></a><h2><a href="#working-with-stylesheets">使用样式</a></h2>项目根目录的 <code class=" language-php">webpack.mix.js</code> 文件是资源编译的入口。可以把它看作是 Webpack 的配置文件。Mix 任务可以使用链式调用的写法来定义你的资源文件该如何进行编译。<a name="less"></a><h3>Less</h3><code class=" language-php">less</code> 方法可以让你将 <a href="http://lesscss.org/">Less</a> 编译为 CSS。下面的命令可以把 <code class=" language-php">app.less</code> 编译为 <code class=" language-php">public/css/app.css</code>。<pre class=" language-php"><code class=" language-php">mix.less('resources/assets/less/app.less', 'public/css');</code></pre>多次调用 <code class=" language-php">less</code> 方法可以编译多个文件:<pre class=" language-php"><code class=" language-php">mix.less('resources/assets/less/app.less', 'public/css') .less('resources/assets/less/admin.less', 'public/css');</code></pre>如果你想自定义编译后的 CSS 文件名, 你可以传递一个完整的路径到 <code class=" language-php">less</code> 方法的第二个参数:<pre class=" language-php"><code class=" language-php">mix.less('resources/assets/less/app.less', 'public/stylesheets/styles.css');</code></pre>如果你需要重写 <a href="https://github.com/webpack-contrib/less-loader#options">底层 Less 插件选项</a>，你可以传递一个对象到 <code class=" language-php">mix.less()</code> 的第三个参数：<pre class=" language-php"><code class=" language-php">mix.less('resources/assets/less/app.less', 'public/css', { strictMath: true });</code></pre><a name="sass"></a><h3>Sass</h3><code class=" language-php">sass</code> 方法可以让你将 <a href="http://sass-lang.com/">Sass</a> 编译为 CSS。你可以使用此方法：<pre class=" language-php"><code class=" language-php">mix.sass('resources/assets/sass/app.scss', 'public/css');</code></pre>同样的，如同 <code class=" language-php">less</code> 方法, 你可以将多个 Sass 文件编译为多个 CSS 文件，甚至可以自定义生成的 CSS 的输出目录：<pre class=" language-php"><code class=" language-php">mix.sass('resources/assets/sass/app.sass', 'public/css') .sass('resources/assets/sass/admin.sass', 'public/css/admin');</code></pre>另外 <a href="https://github.com/sass/node-sass#options">Node-Sass 插件选项</a> 可以通过传递第三个参数来重写：<pre class=" language-php"><code class=" language-php">mix.sass('resources/assets/sass/app.sass', 'public/css', { precision: 5 });</code></pre><a name="stylus"></a><h3>Stylus</h3>类似于 Less 和 Sass，<code class=" language-php">stylus</code> 方法允许你编译 <a href="http://stylus-lang.com/">Stylus</a> 为 CSS：<pre class=" language-php"><code class=" language-php">mix.stylus('resources/assets/stylus/app.styl', 'public/css');</code></pre>你也可以安装其他的 Stylus 插件，例如 <a href="https://github.com/jescalan/rupture">Rupture</a>。首先，通过 NPM(<code class=" language-php">npm install rupture</code>) 来安装插件，然后在调用 <code class=" language-php">mix.stylus()</code> 的时候引用插件：<pre class=" language-php"><code class=" language-php">mix.stylus('resources/assets/stylus/app.styl', 'public/css', { use: [ require('rupture')() ] });</code></pre><a name="postcss"></a><h3>PostCSS</h3><a href="http://postcss.org/">PostCSS</a>，一个用来转换 CSS 的强大工具，已经包含在 Laravel Mix 中。默认， Mix 利用了流行的 <a href="https://github.com/postcss/autoprefixer">Autoprefixer</a> 插件来自动添加所需要的 CSS3 供应商前缀。不过，你也可以自由添加任何适合你应用程序的插件。首先，通过 NPM 来安装想要的插件，然后在你的 <code class=" language-php">webpack.mix.js</code> 文件中引用：<pre class=" language-php"><code class=" language-php">mix.sass('resources/assets/sass/app.scss', 'public/css') .options({ postCss: [ require('postcss-css-variables')() ] });</code></pre><a name="plain-css"></a><h3>纯 CSS</h3>如果你只是想将一些纯 CSS 样式合并成单个的文件, 你可以使用 <code class=" language-php">styles</code> 方法。<pre class=" language-php"><code class=" language-php">mix.styles([ 'public/css/vendor/normalize.css', 'public/css/vendor/videojs.css' ], 'public/css/all.css');</code></pre><a name="url-processing"></a><h3>URL 处理</h3>由于 Laravel Mix 是建立在 Webpack 之上，所以了解一些 Webpack 概念就非常有必要。编译 CSS 的时候，Webpack 会重写和优化那些你样式表中调用 <code class=" language-php">url()</code> 的地方。虽然可能一开始听起来觉得奇怪，不过这确实是一个强大的功能。试想一下我们编译一个包含相对路径图片的 Sass 文件:<pre class=" language-php"><code class=" language-php">.example { background: url('../images/example.png'); }</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> <code class=" language-php">url()</code> 方法会在 URL 重写中排除绝对路径。例如 <code class=" language-php">url('/images/thing.png')</code> 或者 <code class=" language-php">url('http://example.com/images/thing.png')</code> 不会被修改。</blockquote>Laravel Mix 和 Webpack 默认会找到 <code class=" language-php">example.png</code>，把它复制到你的 <code class=" language-php">public/images</code> 目录下，然后在你生成的样式表中重写 <code class=" language-php">url()</code>。这样，你编译之后的 CSS 会变成：<pre class=" language-php"><code class=" language-php">.example { background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e); }</code></pre>与此功能相同，可能你的现在的文件夹结构已经按照你喜欢的方式来配置。如果是这种情况，你可以像这样来禁用 <code class=" language-php">url()</code> 重写：<pre class=" language-php"><code class=" language-php">mix.sass('resources/assets/app/app.scss', 'public/css') .options({ processCssUrls: false });</code></pre>如果在你的 <code class=" language-php">webpack.mix.js</code> 文件这样配置之后，Mix 将不再匹配 <code class=" language-php">url()</code> 或者复制 assets 到你的 public 目录。换句话来说，编译后的 CSS 跟你原来输入的看起来一样：<pre class=" language-php"><code class=" language-php">.example { background: url("../images/thing.png"); }</code></pre><a name="css-source-maps"></a><h3>资源地图</h3>source maps 默认状态下是禁用的，你可以通过在 <code class=" language-php">webpack.mix.js</code> 文件中调用 <code class=" language-php">mix.sourceMaps()</code> 方法来开启。它会带来一些编译成本，但在使用编译后的资源文件时可以更方便的在浏览器中进行调试：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js') .sourceMaps();</code></pre><a name="working-with-scripts"></a><h2><a href="#working-with-scripts">使用脚本</a></h2>Mix 也提供了一些函数来帮助你使用 JavaScript 文件，像是编译 ECMAScript 2015、模块编译、压缩、及简单的串联纯 JavaScript 文件。更棒的是，这些都不需要自定义的配置：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js');</code></pre>这一行简单的代码，支持：<div class="content-list"><ul><li>ECMAScript 2015 语法.</li><li>Modules</li><li>编译 <code class=" language-php">.vue</code> 文件.</li><li>针对生产环境压缩代码.</li></ul></div><a name="vendor-extraction"></a><h3>Vendor Extraction</h3>将应用程序的 JavaScript 与依赖库捆绑在一起的一个潜在缺点是，使得长期缓存更加困难。如，对应用程序代码的单独更新将强制浏览器重新下载所有依赖库，即使它们没有更改。如果你打算频繁更新应用程序的 JavaScript，应该考虑将所有的依赖库提取到单独文件中。这样，对应用程序代码的更改不会影响 vendor.js 文件的缓存。Mix 的 <code class=" language-php">extract</code> 方法可以轻松做到：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js') .extract(['vue'])</code></pre><code class=" language-php">extract</code> 方法接受你希望提取到 <code class=" language-php">vendor.js</code> 文件中的所有的依赖库或模块的数组。使用以上代码片段作为示例，Mix 将生成以下文件：<div class="content-list"><ul><li><code class=" language-php">public/js/manifest.js</code>: Webpack 显示运行时</li><li><code class=" language-php">public/js/vendor.js</code>: 依赖库</li><li><code class=" language-php">public/js/app.js</code>: 应用代码</li></ul></div>为了避免 <code class=" language-php">JavaScript</code> 错误，请务必按正确的顺序加载这些文件：<pre class=" language-php"><code class=" language-php"><script src="/js/manifest.js"></script> <script src="/js/vendor.js"></script> <script src="/js/app.js"></script></code></pre><a name="react"></a><h3>React</h3>Mix 可以自动安装 Babel 插件来支持 React。你只需要替换你的 <code class=" language-php">mix.js()</code> 变成 <code class=" language-php">mix.react()</code> 即可：<pre class=" language-php"><code class=" language-php">mix.react('resources/assets/js/app.jsx', 'public/js');</code></pre>在背后，React 会自动下载，并且自动下载适当的 <code class=" language-php">babel-preset-react</code> Babel 插件。<a name="vanilla-js"></a><h3>原生 JS</h3>类似使用 <code class=" language-php">mix.styles()</code> 来组合多个样式表一样，你也可以使用 <code class=" language-php">scripts()</code> 方法来合并并且压缩多个 JavaScript 文件：<pre class=" language-php"><code class=" language-php">mix.scripts([ 'public/js/admin.js', 'public/js/dashboard.js' ], 'public/js/all.js');</code></pre>这个选项对于那些没有使用 Webpack 的历史项目非常有用。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> <code class=" language-php">mix.babel()</code> 和 <code class=" language-php">mix.scripts()</code> 有点稍微不一样。<code class=" language-php">babel</code> 方法用法和 <code class=" language-php">scripts</code> 一样；不过，这些文件会经过 Babel 编译，把所有 ES2015 的代码转换为原生 JavaScript，这样所有浏览器都能识别。</blockquote><a name="custom-webpack-configuration"></a><h3>自定义 Webpack 配置</h3>Laravel Mix 默认引用了一个预先配置的 <code class=" language-php">webpack.config.js</code> 文件，以便尽快启动和运行。有时，你可能需要手动修改此文件。例如，你可能有一个特殊的加载器或插件需要被引用，或者也许你喜欢使用 Stylus 而不是 Sass。在这种情况下，你有两个选择：<h4>合并</h4>Mix 提供了一个有用的 <code class=" language-php">webpackConfig</code> 方法，允许合并任何 <code class=" language-php">Webpack</code> 配置以覆盖默认配置。这是一个非常好的选择，你不需要复制和维护 <code class=" language-php">webpack.config.js</code> 文件。webpackConfig 方法接受一个对象，该对象应包含要应用的任何 <a href="https://webpack.js.org/configuration/">Webpack 配置项</a>：<pre class=" language-php"><code class=" language-php">mix.webpackConfig({ resolve: { modules: [ path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js') ] } });</code></pre><a name="copying-files-and-directories"></a><h2><a href="#copying-files-and-directories">复制文件与目录</a></h2><code class=" language-php">copy</code> 方法可以复制文件与目录至新位置。当 <code class=" language-php">node_modules</code> 目录中的特定资源需要复制到 <code class=" language-php">public</code> 文件夹时会很有用。<pre class=" language-php"><code class=" language-php">mix.copy('node_modules/foo/bar.css', 'public/css/bar.css');</code></pre><a name="versioning-and-cache-busting"></a><h2><a href="#versioning-and-cache-busting">版本与缓存清除</a></h2>许多的开发者会在它们编译后的资源文件中加上时间戳或是唯一的 token，强迫浏览器加载全新的资源文件以取代提供的旧版本代码副本。你可以使用 version 方法让 Mix 处理它们。<code class=" language-php">version</code> 方法为你的文件名称加上唯一的哈希值，以防止文件被缓存：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js') .version();</code></pre>在为文件生成版本之后，你将不知道确切的文件名。因此，你应该在你的视图中使用 Laravel 的全局 <code class=" language-php">mix</code> PHP 辅助函数来正确加载名称被哈希后的文件。 <code class=" language-php">mix</code> 函数会自动判断被哈希的文件名称：<pre class=" language-php"><code class=" language-php"><link rel="stylesheet" href="{{ mix('/css/app.css') }}"></code></pre>在开发中通常是不需要版本化，你可能希望仅在运行 <code class=" language-php">npm run production</code> 的时候进行版本化：<pre class=" language-php"><code class=" language-php">mix.js('resources/assets/js/app.js', 'public/js'); if (mix.config.inProduction) { mix.version(); }</code></pre><a name="browsersync-reloading"></a><h2><a href="#browsersync-reloading">Browsersync 自动加载刷新</a></h2><a href="https://browsersync.io/">BrowserSync</a> 可以监控你的文件变化，并且无需手动刷新就可以把你的变化注入到浏览器中。你可以通过调用 <code class=" language-php">mix.browserSync()</code> 方法来启用这个功能支持：<pre class=" language-php"><code class=" language-php">mix.browserSync('my-domain.dev'); // 或者... // https://browsersync.io/docs/options mix.browserSync({ proxy: 'my-domain.dev' });</code></pre>你可以通过传递一个字符串 (代理) 或者一个对象 (BrowserSync 设置) 给这个方法。接着，使用 <code class=" language-php">npm run watch</code> 命令来开启 Webpack 的开发服务器。现在，当你修改一个脚本或者 PHP 文件，看着浏览器立即刷新出来的页面来反馈你的改变。<a name="notifications"></a><h2><a href="#notifications">通知</a></h2>在可用的时候，Mix 会将每个包的编译是否成功以系统通知的方式反馈给你。如果你希望停用这些通知，可以通过 <code class=" language-php">disableNotifications</code> 方法实现：<pre class=" language-php"><code class=" language-php">mix.disableNotifications();</code></pre><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://github.com/cmzz">@zyxcba</a></td><td><img class="avatar-66 rm-style" src="https://avatars3.githubusercontent.com/u/6111715?v=3&s=100"></td><td>翻译</td><td><a href="http://kaolake.net">考拉客</a> - 考拉微商店主加盟立返100元！</td></tr></tbody></table></article>