laravel-elixir · laravel 5.3 中文文檔

# 編譯資源文件 (Laravel Elixir) - [簡介](#introduction) - [安裝與配置](#installation) - [運行 Elixir](#running-elixir) - [使用樣式](#working-with-stylesheets) - [Less](#less) - [Sass](#sass) - [Stylus](#stylus) - [純 CSS](#plain-css) - [Source Maps](#css-source-maps) - [使用腳本](#working-with-scripts) - [Webpack](#webpack) - [Rollup](#rollup) - [Scripts](#javascript) - [復制文件與目錄](#copying-files-and-directories) - [版本與緩存清除](#versioning-and-cache-busting) - [BrowserSync](#browser-sync) <a name="introduction"></a> ## 簡介 Laravel Elixir 提供了簡潔流暢的 API，讓你能夠在你的 Laravel 應用程序中定義基本的 [Gulp](http://gulpjs.com) 任務。Elixir 支持許多常見的 CSS 與 JavaScript 預處理器，例如 [Sass](http://sass-lang.com) 和 [Webpack](https://webpack.github.io/)。使用鏈式調用，Elixir 讓你流暢地定義開發流程，例如： ```javascript elixir(function(mix) { mix.sass('app.scss') .webpack('app.js'); }); ``` 如果你曾經對于上手 Gulp 及編譯資源文件感到困惑，那么你將會愛上 Laravel Elixir，不過 Laravel 并不強迫你使用 Elixir，你可以自由的選用你喜歡的自動化開發流程工具，或者完全不使用此類工具。 <a name="installation"></a> ## 安裝及配置 #### 安裝 Node 在開始使用 Elixir 之前，你必須先確保你的機器上有安裝 Node.js 和 npm。 node -v npm -v 默認情況下，Laravel Homestead 包含了你所需的一切；如果你沒有使用 Vagrant，那么你可以從[Node 的官方下載頁面](http://nodejs.org/en/download/) 下載可視化安裝工具來安裝 Node 與 NPM 的最新版本。 #### Gulp 接著，你需要全局安裝 [Gulp](http://gulpjs.com) 的 NPM 擴展包： npm install --global gulp-cli #### Laravel Elixir 最后的步驟就是安裝 Elixir。在每一份新安裝的 Laravel 代碼里，你會發現根目錄有個名為 `package.json` 的文件。默認的 `package.json` 已經包含了 Elixir 和 Webpack JavaScript 模塊。想像它就如同你的 `composer.json` 文件，只不過它定義的是 Node 的依賴擴展包，而不是 PHP 的。你可以使用以下的命令安裝依賴擴展包： npm install 如果你是在 Windows 系統上或在 Windows 主機系統上運行 VM 進行開發，你需要在運行 `npm install` 命令時將 `--no-bin-links` 開啟： npm install --no-bin-links <a name="running-elixir"></a> ## 運行 Elixir Elixir 是創建于 [Gulp](http://gulpjs.com) 之上，所以要運行你的 Elixir 任務，只需要在命令行運行 `gulp` 命令。在命令增加 `--production` 標示會告知 Elixir 壓縮你的 CSS 及 JavaScript 文件： // 運行所有任務... gulp // 運行所有任務并壓縮所有 CSS 及 JavaScript... gulp --production 一旦運行了上述命令，你會看到一個漂亮的表格，列舉出了所有剛剛發生的事件的摘要。 #### 監控資源文件修改 `gulp watch` 會在你的終端里持續運行，監控資源文件是否有發生改變。在 `watch` 命令運行的情況下，一旦資源文件發生變化，Gulp 會自動重新編譯： gulp watch <a name="working-with-stylesheets"></a> ## 使用樣式項目根目錄的 `gulpfile.js` 包含你所有的 Elixir 任務。Elixir 任務可以使用鏈式調用的寫法來定義你的資源文件該如何進行編譯。 <a name="less"></a> ### Less 要將 [Less](http://lesscss.org/) 編譯為 CSS，你可以使用 `less` 方法。`less` 方法會假設你的 Less 文件被保存在 `resources/assets/less` 文件夾中。默認情況下，此例子的任務會將編譯后的 CSS 放置于 `public/css/app.css`： ```javascript elixir(function(mix) { mix.less('app.less'); }); ``` 你可能會想合并多個 Less 文件至單個 CSS 文件。同樣的，生成的 CSS 會被放置于 `public/css/app.css`: ```javascript elixir(function(mix) { mix.less([ 'app.less', 'controllers.less' ]); }); ``` 如果你想自定義編譯后的 CSS 輸出位置，可以傳遞第二個參數至 `less` 方法： ```javascript elixir(function(mix) { mix.less('app.less', 'public/stylesheets'); }); // 指定輸出的文件名稱... elixir(function(mix) { mix.less('app.less', 'public/stylesheets/style.css'); }); ``` <a name="sass"></a> ### Sass `sass` 方法讓你能編譯 [Sass](http://sass-lang.com/) 至 CSS。Sass 文件的默認讀取路徑是 `resources/assets/sass`，你可以使用此方法： ```javascript elixir(function(mix) { mix.sass('app.scss'); }); ``` 同樣的，如同 `less` 方法，你可以編譯多個 Sass 文件至單個的 CSS 文件，甚至可以自定義生成的 CSS 的輸出目錄： ```javascript elixir(function(mix) { mix.sass([ 'app.scss', 'controllers.scss' ], 'public/assets/css'); }); ``` #### 自定義路徑盡管我們建議你使用 Laravel 默認的資源文件夾，但是如果你想要更換到其他路徑，你可以在文件路徑前面加上 `./`。這樣 Elixir 就會從項目根目錄開始查找文件，而不是默認資源文件目錄。舉例來說，如果像要編譯 `app/assets/sass/app.scss` 文件并且輸出到 `public/css/app.css`，可以用下面 `sass` 的命令： ```javascript elixir(function(mix) { mix.sass('./app/assets/sass/app.scss'); }); ``` <a name="stylus"></a> ### Stylus `stylus` 命令可以用來編譯 [Stylus](http://stylus-lang.com/) 至 CSS。假設你的 Stylus 文件放在 `resources/assets/stylus`，你可以這樣調用： ```javascript elixir(function(mix) { mix.stylus('app.styl'); }); ``` > {tip} 這個方法的簽名和 `mix.less()` 與 `mix.sass()`是一樣的。 <a name="plain-css"></a> ### 純 CSS 如果你只是想將一些純 CSS 樣式合并成單個的文件，你可以使用 `styles` 方法。此方法的默認路徑為 `resources/assets/css` 目錄，而生成的 CSS 會被放置于 `public/css/all.css`： ```javascript elixir(function(mix) { mix.styles([ 'normalize.css', 'main.css' ]); }); ``` 當然，你也可以通過傳遞第二個參數至 `styles` 方法，將生成的文件輸出至指定的位置： ```javascript elixir(function(mix) { mix.styles([ 'normalize.css', 'main.css' ], 'public/assets/css/site.css'); }); ``` <a name="css-source-maps"></a> ### Source Maps 在 Elixir 中，為了更方便的在瀏覽器中進行調試，source maps 默認是開啟的。因此，針對每個被編譯的文件，同目錄內都會伴隨著一個 `*.css.map` 或者 `*.js.map` 文件。如果你不想為你的應用生成 source maps，你可以使用 `sourcemaps` 配置選項關閉它們： ```javascript elixir.config.sourcemaps = false; elixir(function(mix) { mix.sass('app.scss'); }); ``` <a name="working-with-scripts"></a> ## 使用腳本 Elixir 也提供了一些函數來幫助你使用 JavaScript 文件，像是編譯 ECMAScript 6、編譯 CoffeeScript、Browserify、壓縮、及簡單的串聯純 JavaScript 文件。如果你是使用 ES2015 編寫代碼，你可以在 [Webpack](http://webpack.github.io) 和 [Rollup](http://rollupjs.org/) 中選擇。如果你對這些工具都不熟悉，也沒有關系，Elixir 會幫你處理所有復雜的問題。默認情況下，Laravel 的 `gulpfile` 會使用 `webpack` 來編譯 Javascript，但是你可以自由選擇其他你喜歡的打包工具 <a name="webpack"></a> ### Webpack `webpack` 命令可以用來編譯和打包 [ECMAScript 2015](https://babeljs.io/docs/learn-es2015/) 文件至純 JavaScript。這個功能接受相對于 `resources/assets/js` 的文件路徑作為參數，并在 `public/js` 文件夾下生成一個打包好的文件： ```javascript elixir(function(mix) { mix.webpack('app.js'); }); ``` 如果要選擇不同的輸入和輸出目錄，只需簡單的在路徑前面加上 `.`。然后你就可以使用相對應用根目錄的路徑。比如，想要把 `app/assets/js/app.js` 編譯至 `public/dist/app.js`: ```javascript elixir(function(mix) { mix.webpack( './resources/assets/js/app.js', './public/dist' ); }); ``` 如果你想要發揮 Webpack 更多的作用。Elixir會讀取你放在應用根目錄的 `webpack.config.js` 文件并且在編譯過程中[應用這些配置](https://webpack.github.io/docs/configuration.html)。 <a name="rollup"></a> ### Rollup 和 Webpack 類似，Rollup 是新一代的 ES2015 打包工具。這個功能可以接受一組相對于 `resources/assets/js` 的路徑為參數，并在 `public/js` 文件夾下生成打包好的文件： ```javascript elixir(function(mix) { mix.rollup('app.js'); }); ``` 就像 `webpack` 命令一樣，你也可以在 `rollup` 命令里自定義輸入輸出的文件的路徑： elixir(function(mix) { mix.rollup( './resources/assets/js/app.js', './public/dist' ); }); <a name="javascript"></a> ### Scripts 如果你想將多個 JavaScript 文件合并至單個文件，你可以使用 `scripts` 方法，這個方法可以自動生成 source maps，合并和壓縮文件。 `scripts` 方法假設所有的路徑都相對于 `resources/assets/js` 目錄，且默認會將生成的 JavaScript 放置于 `public/js/all.js`： ```javascript elixir(function(mix) { mix.scripts([ 'order.js', 'forum.js' ]); }); ``` 如果你想多個腳本的集合合并成不同文件，你可以使用調用多個 `scripts` 方法。給予該方法的第二個參數會為每個串聯決定生成的文件名稱： ```javascript elixir(function(mix) { mix.scripts(['app.js', 'controllers.js'], 'public/js/app.js') .scripts(['forum.js', 'threads.js'], 'public/js/forum.js'); }); ``` 如果你想合并指定目錄中的所有腳本，你可以使用 `scriptsIn` 方法。生成的 JavaScript 會被放置在 `public/js/all.js`： ```javascript elixir(function(mix) { mix.scriptsIn('public/js/some/directory'); }); ``` > {tip} 如果你想合并多個已經編譯過的第三方庫，比如 jQuery，可以嘗試使用 `mix.combine()`。這個命令可以合并文件，但是跳過生成 source map 和壓縮文件的步驟。這樣一來，編譯時間可以大大縮短。 <a name="copying-files-and-directories"></a> ## 復制文件與目錄 `copy` 方法可以復制文件與目錄至新位置。所有操作路徑都相對于項目的根目錄： ```javascript elixir(function(mix) { mix.copy('vendor/foo/bar.css', 'public/css/bar.css'); }); ``` <a name="versioning-and-cache-busting"></a> ## 版本與緩存清除許多的開發者會在它們編譯后的資源文件中加上時間戳或是唯一的 token，強迫瀏覽器加載全新的資源文件以取代提供的舊版本代碼副本。你可以使用 `version` 方法讓 Elixir 處理它們。 `version` 方法接收一個相對于 `public` 目錄的文件名稱，接著為你的文件名稱加上唯一的哈希值，以防止文件被緩存。舉例來說，生成出來的文件名稱可能像這樣：`all-16d570a7.css`： ```javascript elixir(function(mix) { mix.version('css/all.css'); }); ``` 在為文件生成版本之后，你可以在你的[視圖](/docs/{{version}}/views) 中使用 Laravel 的全局 `elixir` PHP 輔助函數來正確加載名稱被哈希后的文件。elixir 函數會自動判斷被哈希的文件名稱： <link rel="stylesheet" href="{{ elixir('css/all.css') }}"> #### 為多個文件生成版本你可以傳遞一個數組至 `version` 方法來為多個文件生成版本： ```javascript elixir(function(mix) { mix.version(['css/all.css', 'js/app.js']); }); ``` 一旦該文件被加上版本，你需要使用 `elixir` 輔助函數來生成哈希文件的正確鏈接。切記，你只需要傳遞未哈希文件的名稱至 `elixir` 輔助函數。此函數會自動使用未哈希的名稱來判斷該文件為目前的哈希版本： <link rel="stylesheet" href="{{ elixir('css/all.css') }}"> <script src="{{ elixir('js/app.js') }}"></script> <a name="browser-sync"></a> ## BrowserSync 當你對前端資源進行修改后，BrowserSync 會自動刷新你的網頁瀏覽器。`browserSync` 接受的參數是包含 `proxy` （一般是應用的本地URL）屬性的 JavaScript 對象。然后，當你運行了 `gulp watch` 命令，你就可以通過 3000 (`http://project.dev:3000`) 端口來訪問你的 web 應用，并且享受瀏覽器同步的便利。 ```javascript elixir(function(mix) { mix.browserSync({ proxy: 'project.dev' }); }); ```