編輯資源 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>