在 Laravel 專案中使用 webpack-encore

田勇發表於2019-07-21
LaravelWeb

看過我之前寫過的部落格的應該知道我一直是 laravel-mix 的死忠粉，有好幾篇文章都是關於它的。每每提到 laravel-mix 時更是不吝溢美之詞。然而就在大概一個月前，我卻決定不再使用它，而轉投 webpack-encore 陣營。

至於為什麼放棄 laravel-mix，主要是因為它的維護狀況堪憂，不僅更新節奏緩慢，許多 Issue 久懸未決，更重要的是，作者似乎將很多 bug 完全寄希望於 webpack5，哪怕有熱心人士 PR 了，也通常被關掉，然後回覆說“兄 dei，這個坑等 webpack5 出來就好了，我之前試過沒弄好，估計你這也填好坑，乾脆安分點兒等 webpack5 吧”（不是原話，但差不多是這意思 :smile:）。但最終讓我下定決心尋求替代方案的，則是這個 Issue，細翻原始碼，發現相關功能依賴的還是 extract-text-webpack-plugin，而這個包，早在 webpack4 釋出不久就被宣佈廢棄了（現在去看它的官方倉庫已經被設定為 archived），而作者似乎完全沒有使用 mini-css-extract-plugin 的意思。

正所謂愛之深，責之切，在對 laravel-mix 表示失望之後，我翻出了自己 star 多時的另一包 webpack-encore，雖說很早就 star 了，但之前卻沒試用過它，可能也是因為對於 laravel-mix 的偏愛，然而這次，不試便罷，試完之後大有相見恨晚之意。

webpack-encore 是 Symfony 官方的前端整合構建工具，同樣是基於 webpack，但它的 API 設計得更為友好，而且文件更完善，當然更關鍵的一點是，坑更少啊……從開始讀它的文件，倒把手裡一個專案從 laravel-mix 遷移到 webpack-encore，只用了幾個小時，並且期間相當順利。而我遷移的這個專案，是一個 Laravel 專案，所以下面就分享下，如果在 Laravel 專案中使用 webpack-encore 替代 laravel-mix。

安裝依賴

首先當然是安裝依賴

yarn add -D @symfony/webpack-encore

需要注意的是，webpack-encore 沒有像 laravel-mix 那樣在自己內部依賴 vue-tempplate-compiler 之類的包，所以如果自己專案裡用動了這些，需要自己在專案裡手動安裝好。

配置 webpack

在專案根目錄下新建一個 webpack.config.js 檔案並在其中配置 webpack-encore 功能（實際上它最終也是一個標準的 webpack 配置檔案），以最基本的玩法為例。

const Encore = require('@symfony/webpack-encore')

Encore
// directory where compiled assets will be stored
  .setOutputPath('public/js/')
  // public path used by the web server to access the output path
  .setPublicPath('/js')
  // only needed for CDN's or sub-directory deploy
  //.setManifestKeyPrefix('build/')

  /*
   * ENTRY CONFIG
   *
   * Add 1 entry for each "page" of your app
   * (including one that's included on every page - e.g. "app")
   *
   * Each entry will result in one JavaScript file (e.g. app.js)
   * and one CSS file (e.g. app.css) if you JavaScript imports CSS.
   */.addEntry('app', './resources/js/app.js')

// will require an extra script tag for runtime.js
// but, you probably want this, unless you're building a single-page app
  .enableSingleRuntimeChunk()

  .cleanupOutputBeforeBuild().enableSourceMaps(!Encore.isProduction())
// enables hashed filenames (e.g. app.abc123.css)
  .enableVersioning(Encore.isProduction())

  .enableVueLoader()
  .enableSassLoader(options => {
    options.implementation = require('sass')
  })

// fetch the config, then modify it!
const config = Encore.getWebpackConfig()

// export the final config
module.exports = config

新增 php helper 函式

Laravel 自帶了一個 mix() 函式用於引用 mix 編譯的資源，與之類似，syfony 也有這樣的函式，而且更為方便。為此你需要在 Laravel 專案中自行實現這兩方法，下面是我參考 symfony 裡相關原始碼改寫的，可能邏輯上並不算完善，但以自己一個多月的使用情況來看，它們表現良好。

use Illuminate\Support\HtmlString;

/**
 * @param  string  $entryName
 * @return HtmlString
 */
function encore_entry_link_tags(string $entryName): HtmlString
{
    $entryPointsFile = public_path('js/entrypoints.json');

    $jsonResult = json_decode(file_get_contents($entryPointsFile), true);

    if (!array_key_exists('css', $jsonResult['entrypoints'][$entryName])) {
        return null;
    }

    $tags = array_map(function ($item) {
        return '<link rel="stylesheet" href="'.$item.'"/>';
    }, $jsonResult['entrypoints'][$entryName]['css']);

    return new HtmlString(implode('', $tags));
}

/**
 * @param  string  $entryName
 * @return HtmlString
 */
function encore_entry_script_tags(string $entryName): HtmlString
{
    $entryPointsFile = public_path('js/entrypoints.json');

    $jsonResult = json_decode(file_get_contents($entryPointsFile), true);

    if (!array_key_exists('js', $jsonResult['entrypoints'][$entryName])) {
        return null;
    }

    $tags = array_map(function ($item) {
        return '<script src="'.$item.'"></script>';
    }, $jsonResult['entrypoints'][$entryName]['js']);

    return new HtmlString(implode('', $tags));
}

使用 encore_entry_link_tags 和 encore_entry_script_tags 引用編譯的前端資源

在模板裡使用前面新增的 helper 函式引用資源，你會發現它比 Laravel 自帶的 mix() 函式更方便，只需要一個函式，就可以自動引入 vendor.js 和 app.js 了。

<!doctype html>
<html lang="{{ app()->getLocale() }}">
<head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    <!-- CSRF Token -->
    <meta name="csrf-token" content="{{ csrf_token() }}">

    <title>{{ config('app.name') }}</title>

    <!-- app.css -->
    {{ encore_entry_link_tags('app') }}
</head>
<body>

    <div id="app"></div>

    {{ encore_entry_script_tags('app') }}
</body>
</html>

修改 package.json 中的指令碼（scripts）

因為 laravel 專案預設 package.json 中 develop 等相關的指令碼都是使用 laravel-mix 的，為了方便日常開發，現在要對它們進行一些調整，改用 webpack-cocore。調整後大致如下，你也可以根據自己實際應用情況進行其它調整

"scripts": {
    "dev": "npm run development",
    "development": "cross-env NODE_ENV=development encore dev",
    "watch": "npm run development -- --watch",
    "watch-poll": "npm run watch -- --watch-poll",
    "hot": "encore dev-server --port=9001 --hot",
    "prod": "npm run production",
    "production": "cross-env NODE_ENV=production encore production"
},

執行指令碼，愉快擼 BUG

做完前面的這些步驟之後，在終端執行 yarn run hot，瀏覽器中輸入專案繫結的域名（如 app.test)，就可以體驗方便高效的 HMR 開發了。

後記

使用 webpack-encore 已經快兩個月了，這期間總體說來相當順利，小坑雖然有，但沒什麼大坑。去 github 上提 issue，維護成員基本上都很友善耐心，幾個小時就會有回覆。這種態度也讓我對它更加放心了，相信它會折騰得越來越好。雖然 webpack-encore 是作為 Symfony 預設整合工具來設計的，但這並不妨礙它在 Laravel 中發揮強大威力。

相比於 laravel-mix，encore 的 API 以及一些預設配置方面考慮得更為科學和全面，想要配置 vue-loader 或者 ts-loader 之類的，只需要呼叫相應的方法。另外還有點讓我先驚訝的是，他們竟然對 watchOptions.ignored 的預設值也考慮到了，預設忽略 /node_modules/，降低 CPU 佔用。當然，更為重要的是，mix4 裡因為一些 bug 而無法使用的功能，在 encore 裡卻正常，如 dynamic import。

總之，如果你已經發現了 laravel-mix 的種種不足但又苦於沒更好選擇的話，不妨試試 webpack-encore，相信你會對它愛不釋手。

部落格原文

相關文章