[TOC] # 編譯資源 Mix ## 使用樣式表 `webpack.mix.js` 文件所有資源編譯的切入點。把它想像為 Webpack 的輕量級配置封裝。Mix 任務可以與如何編譯資源的配置一起被鏈式調用。 ### Less `less` 方法可用于將 [Less](http://lesscss.org/) 編譯成 CSS。下面的語句將 `app.less` 文件編譯為 `public/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 插件選項](https://github.com/webpack-contrib/less-loader#options) ，可以傳遞一個對象作為 `mix.less()` 的第三個參數： ``` mix.less('resources/less/app.less', 'public/css', { strictMath: true }); ``` ### Sass `sass` 方法能將 [Sass](https://sass-lang.com/) 編譯成 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 插件選項](https://github.com/sass/node-sass#options) 可以作為第三個參數： ``` mix.sass('resources/sass/app.sass', 'public/css', { precision: 5 }); ``` ### Stylus 與 Less 和 Sass 相似， `stylus` 方法將 [Stylus](http://stylus-lang.com/) 編譯成 CSS： ``` mix.stylus('resources/stylus/app.styl', 'public/css'); ``` 還可以安裝額外的 Stylus 插件，比如 [Rupture](https://github.com/jescalan/rupture) 。先通過 NPM （`npm install rupture`）安裝有插件，然后在調用 `mix.stylus()` 時包含它： ``` mix.stylus('resources/stylus/app.styl', 'public/css', { use: [ require('rupture')() ] }); ``` ### PostCSS [PostCSS](https://postcss.org/) 是一個轉換 CSS 的強力工具，它已經包含在 Laravel Mix 中。默認情況下，Mix 利用流行的 [Autoprefixer](https://github.com/postcss/autoprefixer) 插件自動附加所有必要的 CSS3 第三方前綴。不過，你可以自由添加應用中所需的任何附加插件。首先通過 NPM 安裝所需插件，然后在 `webpack.mix.js` 文件引用： ``` mix.sass('resources/sass/app.scss', 'public/css') .options({ postCss: [ require('postcss-css-variables')() ] }); ``` ### 原生 CSS 如果想要將幾個原生 CSS 樣式表合并到單個文件中，可以使用 `styles` 方法。 ``` mix.styles([ 'public/css/vendor/normalize.css', 'public/css/vendor/videojs.css' ], 'public/css/all.css'); ``` ### URL 處理 因為是基于 Webpack 之上構建，了解幾個 Webpack 概念就很重要了。對于 CSS 編譯，Webpack 將重寫和優化任何帶有樣式表的 `url()` 調用。雖然初聽上去好像很奇怪，但這確實是個強大的功能。 想像一下我們想要編譯包含圖片相對 URL 的 Sass： ``` .example { background: url('../images/example.png'); } ``` > 提示：任何給定 `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/app/app.scss', 'public/css') .options({ processCssUrls: false }); ``` 在 `webpack.mix.js` 文件中加入這項配置，Mix 將不再匹配任何 `url()` 或者復制資源到 public 目錄。換句話說，編譯后的 CSS 看上去和你原來輸入的內容一樣： ``` .example { background: url("../images/thing.png"); } ``` ### 源碼映射 雖然默認情況下源碼映射被禁用，但是可以通過在 `webpack.mix.js` 文件中調用 `mix.sourceMaps()` 方法來激活。盡管會提高編譯/執行的成本，卻可以在在編譯資源時為瀏覽器開發工具提供額外的調試信息。 ``` 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` 文件。 - 為生產環境最小化代碼。 ### Vendor 提取 將應用自身的 JavaScript 和第三方庫綁定在一起有個潛在的缺點：會使長期緩存變得困難。例如，應用代碼的單獨更新將強制瀏覽器重新下載全部第三方庫，即使第三方庫沒有發生變化。 如果你打算頻繁地更新應用中的 JavaScript，應該考慮將第三方庫提取到它自己的文件中。這樣一來，應用代碼的改變將不影響 `vendor.js` 文件緩存。Mix 的 `extract` 方法為之提供了便利： ``` mix.js('resources/js/app.js', 'public/js') .extract(['vue']) ``` `extract` 方法接受你想要提取到 `vendor.js` 的全部庫或模塊的數組作為參數。使用上面例子中的代碼片段，Mix 將生成如下文件： ``` <div class="content-list" markdown="1"> - `public/js/manifest.js`: *Webpack 運行時清單* - `public/js/vendor.js`: *第三方庫代碼* - `public/js/app.js`: *應用代碼* </div> ``` 為避免 JavaScript 錯誤，應確保按適應順序加載這些文件： ``` <script src="/js/manifest.js"></script> <script src="/js/vendor.js"></script> <script src="/js/app.js"></script> ``` ### React Mix 能自動安裝 React 支持所需的 Babel 插件。要達成此目的，只需要用 `mix.react()` 替換 `mix.js()` ： ``` mix.react('resources/js/app.jsx', 'public/js'); ``` Mix 將在后臺下載并包含適用的 `babel-preset-react` Babel 插件。 ### Vanilla JS 與利用 `mix.styles()` 整合樣式表類似，你也可以使用 `scripts()` 方法整合并最小化任意數量的 JavaScript 文件： ``` mix.scripts([ 'public/js/admin.js', 'public/js/dashboard.js' ], 'public/js/all.js'); ``` 對于不需要使用 Webpack 編譯 JavaScript 的遺留代碼，這個選項尤其有用。 > 提示： `mix.babel()` 是 `mix.scripts()` 的一個小變種。它的方法簽名與 `scripts` 完全相同；但整合的文件將經由 Babel 編譯，它會將 ES2015 代碼轉換為瀏覽器能夠理解的 vanilla JavaScript。 ### 自定義 Webpack 配置 Lavarel Mix 在后臺引用預先配置的 `webpack.config.js` 文件以加速啟動和運行。有時，你可能需要手動編輯這個文件。你可能有一個特殊的加載器或插件需要引用，或者可能更愿意用 Stylus 代替 Sass。這種情況下，你有兩個選擇： #### 合并自定義配置 Mix 提供了 `webpackConfig` 方法來合并任意簡短的 Webpack 配置以覆蓋已有配置。這是個非常勾人的選擇，因為它不要求你復制和維護你自己的 `webpack.config.js` 副本。 `webpackConfig` 方法接受一個對象作為作參數，它包含你想要應用的任何 [Webpack 特定配置](https://webpack.js.org/configuration/) ， ``` mix.webpackConfig({ resolve: { modules: [ path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js') ] } }); ``` #### 自定義配置文件 如果你想完全自定義 Webpack 配置，將 `node_modules/laravel-mix/setup/webpack.config.js` 文件復制到項目的根目錄。然后將 `package.json` 文件中所有的 `--config` 引用都指向新復制的配置文件。如果選擇用這種方式自定義配置，Mix `webpack.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(); ``` 在生成版本化文件后，你不會知道確切的文件名。因此，你需要在 [views](/docs/{{version}}/views) 中使用 Laravel 的全局 `mix` 函數載入相應的哈希資源。 `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](https://browsersync.io/) 能夠自動監測文件變化，并且無需手動刷新就將變化注入到瀏覽器。可以調用 `mix.browserSync()` 方法開啟此項支持： ``` mix.browserSync('my-domain.test'); // 或... // https://browsersync.io/docs/options mix.browserSync({ proxy: 'my-domain.test' }); ``` 可以傳遞字符串（代理）或對象Y（BrowserSync 設置）給此方法。然后使用 `npm run watch` 命令啟動 Webpack 的開發服務器。再編輯腳本或者 PHP 文件，就會看到瀏覽器立即刷新以響應你的修改。 ## 環境變量 可以通過在 `.env` 文件中添加 `MIX_` 前綴，將環境變量注入到 Mix： ``` MIX_SENTRY_DSN_PUBLIC=http://example.com ``` 一旦此變量被定義在 `.env` 文件中，就可以借助 `process.env` 對象訪問它。如果在運行 `watch` 任務時這個值發生改，就需要重啟任務： ``` process.env.MIX_SENTRY_DSN_PUBLIC ``` ## 通知 如果可用，Mix 將自動為每次綁定顯示操作系統通知。這將為你提供編譯是否成功的實時反饋。不過，可能在某些情況下，你希望禁用通知。一個例子是在生產服務器上觸發 Mix。通知可以借助 `disableNotifications` 方法來禁用。 ``` mix.disableNotifications(); ```