Vuejs 3 webpack: Problem with vue-template-compiler

技术背景

在将 Vue.js 3 集成到使用 Webpack 的现有项目时，会遇到 vue-template-compiler 版本不匹配的问题。官方文档指出，每次发布新的 Vue 版本时，都会同时发布相应版本的 vue-template-compiler，编译器的版本必须与基础 Vue 包保持同步，否则 vue-loader 生成的代码可能与运行时不兼容。

实现步骤

初始化 package.json

{
    "private": true,
    "name": "vue-3",
    "description": null
}

安装 Vue 3 和 vue-loader

npm i --save vue@next vue-loader@next

安装开发依赖

npm i -D @vue/compiler-sfc css-loader file-loader mini-css-extract-plugin url-loader webpack webpack-cli webpack-dev-server

配置 webpack.config.js

const path = require("path");
const { VueLoaderPlugin } = require("vue-loader");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = (env = {}) => ({
  mode: env.prod ? "production" : "development",
  devtool: env.prod ? "source-map" : "cheap-module-eval-source-map",
  entry: [
    require.resolve(`webpack-dev-server/client`),
    path.resolve(__dirname, "./src/main.js")
  ].filter(Boolean),
  output: {
    path: path.resolve(__dirname, "./dist"),
    publicPath: "/dist/"
  },
  resolve: {
    alias: {
      vue: "@vue/runtime-dom"
    }
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        use: "vue-loader"
      },
      {
        test: /\.png$/,
        use: {
          loader: "url-loader",
          options: { limit: 8192 }
        }
      },
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: { hmr: !env.prod }
          },
          "css-loader"
        ]
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin(),
    new MiniCssExtractPlugin({
      filename: "[name].css"
    })
  ],
  devServer: {
    inline: true,
    hot: true,
    stats: "minimal",
    contentBase: __dirname,
    overlay: true,
    injectClient: false,
    disableHostCheck: true
  }
});

添加开发脚本

在 package.json 中添加 dev 脚本：

{
    "private": true,
    "scripts": {
        "dev": "webpack-dev-server"
    },
    "dependencies": {
        "vue": "^3.0.2"
    },
    "name": "vue-3",
    "description": null,
    "devDependencies": {
      // 其他开发依赖
    }
}

填充 index.html

<link rel="stylesheet" href="/dist/main.css" />
<div id="app"></div>
<script src="/dist/main.js"></script>

运行项目

npm run dev

然后访问 http://localhost:8080/。

核心代码

webpack.config.js

const path = require("path");
const { VueLoaderPlugin } = require("vue-loader");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = (env = {}) => ({
  mode: env.prod ? "production" : "development",
  devtool: env.prod ? "source-map" : "cheap-module-eval-source-map",
  entry: [
    require.resolve(`webpack-dev-server/client`),
    path.resolve(__dirname, "./src/main.js")
  ].filter(Boolean),
  output: {
    path: path.resolve(__dirname, "./dist"),
    publicPath: "/dist/"
  },
  resolve: {
    alias: {
      vue: "@vue/runtime-dom"
    }
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        use: "vue-loader"
      },
      {
        test: /\.png$/,
        use: {
          loader: "url-loader",
          options: { limit: 8192 }
        }
      },
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: { hmr: !env.prod }
          },
          "css-loader"
        ]
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin(),
    new MiniCssExtractPlugin({
      filename: "[name].css"
    })
  ],
  devServer: {
    inline: true,
    hot: true,
    stats: "minimal",
    contentBase: __dirname,
    overlay: true,
    injectClient: false,
    disableHostCheck: true
  }
});

最佳实践

• 使用 vue-loader@next 与 Vue 3 配合使用。
• 使用 @vue/compiler-sfc 代替 vue-template-compiler。
• 若无法使用 Vue CLI 管理项目，可将其作为参考，生成新项目并使用 vue inspect 命令检查其 Webpack 配置和 package.json 中的依赖。

常见问题

vue-template-compiler 版本不匹配

错误信息：

Vue packages version mismatch:

- [email protected] (/home/alejo/playground/parquesFrontend/node_modules/vue/index.js)
- [email protected] (/home/alejo/playground/parquesFrontend/node_modules/vue-template-compiler/package.json)

This may cause things to work incorrectly. Make sure to use the same version for both.

解决方案：使用 @vue/compiler-sfc 代替 vue-template-compiler，并安装 vue@next 和 vue-loader@next。

安装 vue@next 时出现 ETARGET 错误

错误信息：

npm ERR! code ETARGET
npm ERR! notarget No matching version found for [email protected].

解决方案：确保网络正常，清除 npm 缓存后重新安装：

npm cache clean --force
npm i --save vue@next vue-loader@next