Webpack 1.x 升级至 2.x 常见问题与解决方案

Webpack 升级背景与动机

前言

Webpack 作为前端资源加载与打包的核心工具，依据模块依赖关系进行静态分析，并按指定规则生成静态资源。近期在推进博客服务端渲染（SSR）项目时，发现现有的 Vue SSR 示例均基于 Webpack 2 构建。由于博主在 Webpack 1.x 环境下长期尝试，始终无法生成 vue-ssr-server-bundle.json 文件，因此决定执行 Webpack 版本升级操作。

本文旨在记录升级过程中遭遇的若干问题及其解决路径。受限于记忆，可能无法涵盖所有细节，但力求记录关键步骤。以下将详细展开具体介绍。

常见报错与解决方案

错误：Error: Chunk.entry was removed. Use hasRuntime()

解决办法：升级 extract-text-webpack-plugin 至版本 "^2.1.0"。

错误：Error: Breaking change: extract now only takes a single argument.

// 错误提示

Error: Breaking change: extract now only takes a single argument. Either an options object *or* the loader(s).
Example: if your old code looked like this:
 ExtractTextPlugin.extract('style-loader', 'css-loader')

You would change it to:
 ExtractTextPlugin.extract({ fallback: 'style-loader', use: 'css-loader' })

此问题源于 Webpack 2 对 Loader 配置方式的调整。需修改 ExtractTextPlugin 的配置结构以适配新规范。

{
 test: /\.less$/,
 use: ExtractTextPlugin.extract({
  fallback: 'style-loader',
  use: ['css-loader', 'less-loader']
 })
},

HTML 插件资源引入配置修正

由 htmlWebpackPlugin 生成的 HTML 文件中，未正确引入 CSS 及 app.js 资源。

修改配置，将 chunks 属性改为使用 files 包裹。

{
 filename: pageName + '.html',
 template: __dirname + '/src/' + pageName + '.html',
 chunks: pageConf.chunks,
 inject: true
};

{
 filename: pageName + '.html',
 template: __dirname + '/src/' + pageName + '.html',
 files: {
  chunks: pageConf.chunks,
 },
 inject: true
};

ESLint 与 ES6 语法兼容性问题

ESLint 无法识别 ES6 语法，导致构建报错。

 ✘ http://eslint.org/docs/rules/ Parsing error: The keyword 'import' is reserved
 src\entry.client.js:7:1
 import { createApp } from './app'
 ^

解决办法：修改 ESLint 配置，增加 parser 选项。

"parser": "babel-eslint",

Browserslist 版本错误处理

错误：Module build failed: BrowserslistError: Unknown version 57 of and_chr

该错误通常由 npm 包版本过旧引起。解决方法为删除 node_modules 目录，并重新安装依赖。

Vue Loader 提取 CSS 配置

Webpack 执行 dist 打包后，未生成公共 CSS 文件。

检查 vue-loader 配置，确保添加 extractCSS: true 选项。

{
 test: /\.vue$/,
 loader: 'vue-loader',
 options: {
  extractCSS: isProd,
  preserveWhitespace: false,
  postcss: [
  require('autoprefixer')({
   browsers: ['last 3 versions']
  })
  ]
 }
},

升级总结与建议

小结

整体升级过程相对顺利，vue-ssr-server-bundle.json 已成功生成，但这仅是 SSR 实施的起点，后续仍面临诸多挑战。若对 Webpack 2 不熟悉，建议先查阅官方文档，英文阅读困难者可参考中文翻译版。此次升级的核心在于多数 Loader 需同步升级，并重点关注 Loader 配置语法的变更，其他方面无明显异常。

总结

以上为本文全部内容，希望这些经验对大家的开发工作有所助益。如有任何疑问，欢迎留言交流，感谢支持。