【前端工程化】webpack5+vue3+ts+代码规范构建企业级前端项目(一)

一. 前言

本文是专栏【前端工程化】webpack5+vue3+ts+代码规范构建企业级前端项目系列第一篇，会详细讲解手动初始化vue3+ts项目，并使用webpack5配置基础版vue3+ts环境。

本系列文章将使用最新的webpack5一步一步从零搭建一个完整的vue3+ts开发和打包环境，配置完善构建速度和构建结果的优化配置，以及配置完善的代码规范和git提交规范。完整代码已上传到webpack5-vue3-ts。

全系列文章：

《第一篇：基础功能配置，webpack5配置vue3+ts基础环境，实现dev开发和打包构建》。
《第二篇：进阶功能配置，环境变量，支持css，less，图片和媒体资源，css3前缀，babel兼容》。
《第三篇：优化构建速度：构建耗时分析，持久化缓存，多线程loader，devtool，loader作用范围》。
《第四篇：优化化构建结果：构建结果分析，抽离css文件，压缩css，js文件，hash合理配置，代码分割，tree-shaking清理css和js，打包生成gzip》。
代码格式规范：editorconfig统一编辑器配置，prettier自动格式化代码，stylelint规范样式和保存自动修复，代码提交自动格式化css和js代码等。
代码语法规范：eslint检测js代码语法，style-lint检测样式代码语法，使用tsc检测类型报错，lint-staged按需检测代码等。
git提交规范：代码提交时husky检测代码语法规范，代码提交时husky检测commit备注规范，commitizen配置commit辅助信息等。

全系列概览

二. 初始化项目

在开始webpack配置之前，先手动初始化一个基本的vue3+ts项目，新建项目文件夹webpack5-vue3-ts, 在项目下执行

npm init -y

初始化好package.json后,在项目下新增以下所示目录结构和文件

├── build
|   ├── webpack.base.js # 公共配置
|   ├── webpack.dev.js  # 开发环境配置
|   └── webpack.prod.js # 打包环境配置
├── public
│   └── index.html # html模板
├── src
|   ├── App.vue 
│   └── index.ts # vue3应用入口页面
├── tsconfig.json  # ts配置
└── package.json

安装webpack依赖

npm i webpack@5.85.1 webpack-cli@5.1.3 -D

安装vue3依赖

npm i vue@^3.3.4 -S

添加public/index.html内容

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>webpack5-vue3-ts</title>
</head>
<body>
  <!-- 容器节点 -->
  <div id="root"></div>
</body>
</html>

添加tsconfig.json内容

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"],
}

添加src/App.vue内容

<template>
  <h2>webpack5-vue3-ts</h2>
</template>

<script setup lang="ts">
</script>
<style scoped>
</style>

添加src/index.ts内容

import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#root')

现在项目业务代码已经添加好了,接下来可以配置webpack的代码了。

三. webpack公共配置

修改webpack.base.js

3.1. 配置入口文件

// build/webpack.base.js
const path = require('path')

module.exports = {
  entry: path.join(__dirname, '../src/index.ts'), // 入口文件
}

3.2 配置出口文件

// build/webpack.base.js
const path = require('path')

module.exports = {
  // ...
  // 打包文件出口
  output: {
    filename: 'static/js/[name].js', // 每个输出js的名称
    path: path.join(__dirname, '../dist'), // 打包结果输出路径
    clean: true, // webpack4需要配置clean-webpack-plugin来删除dist文件,webpack5内置了
    publicPath: '/' // 打包后文件的公共前缀路径
  },
}

3.3 配置loader解析ts和vue

由于webpack默认只能识别js文件,不能识别vue和ts文件，需要借助 vue-loader 来识别vue语法。ts文件可以借助babel-loader的预设预设 @babel/preset-typescript 来先ts语法转换为js 语法。

安装babel核心模块和babel预设以及vue-loader

npm i babel-loader@^9.1.2 @babel/core@^7.22.5 @babel/preset-env@^7.22.5 @babel/preset-typescript@^7.22.5 vue-loader@^17.2.2 -D

在webpack.base.js的module.rules配置vue-loader和和babel-loader对应插件配置

// build/webpack.base.js
const { VueLoaderPlugin } = require('vue-loader')
module.exports = {
  // ...
  module: {
    rules: [
      {
      	test: /\.vue$/, // 匹配.vue文件
      	use: 'vue-loader', // 用vue-loader去解析vue文件
      },
      {
        test: /\.ts$/, // 匹配.ts文件
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              [
                "@babel/preset-typescript",
                {
                  allExtensions: true, //支持所有文件扩展名(重要)
                },
              ],
            ]
          }
        }
      }
    ]
  },
  plugins: [
    // ...
    new VueLoaderPlugin(), // vue-loader插件
  ]
}

单文件.vue文件被 vue-loader 解析三个部分，script 部分会由 ts 来处理，但是ts不会处理 .vue 结尾的文件，所以要在预设里面加上 allExtensions: true配置项来支持所有文件扩展名。

3.4. 配置extensions

extensions是webpack的resolve解析配置下的选项，在引入模块时不带文件后缀时，会来该配置数组里面依次添加后缀查找文件。

修改webpack.base.js，注意把高频出现的文件后缀放在前面

// build/webpack.base.js
module.exports = {
  // ...
  resolve: {
    extensions: ['.vue', '.ts', '.js', '.json'],
  }
}

这里只配置js, vue和ts和json，其他文件引入都要求带后缀，可以提升构建速度。

3.5. 添加html-webpack-plugin插件

webpack需要把最终构建好的静态资源都引入到一个html文件中,这样才能在浏览器中运行,html-webpack-plugin就是来做这件事情的,安装依赖：

npm i html-webpack-plugin -D

因为该插件在开发和构建打包模式都会用到,所以还是放在公共配置webpack.base.js里面

// build/webpack.base.js
const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {
  // ...
  plugins: [
    // ...
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, '../public/index.html'), // 模板取定义root节点的模板
      inject: true, // 自动注入静态资源
    })
  ]
}

到这里一个最基础的vue3基本公共配置就已经配置好了,需要在此基础上分别配置开发环境和打包环境了。

四. webpack开发环境配置

4.1. 安装 webpack-dev-server

开发环境配置代码在webpack.dev.js中,需要借助 webpack-dev-server在开发环境启动服务器来辅助开发,还需要依赖webpack-merge来合并基本配置,安装依赖:

npm i webpack-dev-server webpack-merge -D

修改webpack.dev.js代码, 合并公共配置，并添加开发模式配置

// build/webpack.dev.js
const path = require('path')
const { merge } = require('webpack-merge')
const baseConfig = require('./webpack.base.js')

// 合并公共配置,并添加开发环境配置
module.exports = merge(baseConfig, {
  mode: 'development', // 开发模式,打包更加快速,省了代码优化步骤
  devtool: 'eval-cheap-module-source-map', // 源码调试模式,后面会讲
  devServer: {
    port: 3000, // 服务端口号
    compress: false, // gzip压缩,开发环境不开启,提升热更新速度
    hot: true, // 开启热更新，后面会讲vue3模块热替换具体配置
    historyApiFallback: true, // 解决history路由404问题
    static: {
      directory: path.join(__dirname, "../public"), //托管静态资源public文件夹
    }
  }
})

4.2. package.json添加dev脚本

在package.json的scripts中添加

// package.json
"scripts": {
  "dev": "webpack-dev-server -c build/webpack.dev.js"
},

-c 是 --config的缩写，是指定webpack-dev-server的配置文件。

执行npm run dev,就能看到项目已经启动起来了,访问http://localhost:3000/,就可以看到项目界面,具体完善的vue3模块热替换在下面会讲到。

五. webpack打包环境配置

5.1. 修改webpack.prod.js代码

// build/webpack.prod.js
const { merge } = require('webpack-merge')
const baseConfig = require('./webpack.base.js')
module.exports = merge(baseConfig, {
  mode: 'production', // 生产模式,会开启tree-shaking和压缩代码,以及其他优化
})

5.2. package.json添加build打包命令脚本

在package.json的scripts中添加build打包命令

"scripts": {
    "dev": "webpack-dev-server -c build/webpack.dev.js",
    "build": "webpack -c build/webpack.prod.js"
},

执行npm run build,最终打包在dist文件中, 打包结果:

dist                    
├── static
|   ├── js
|     ├── main.js
├── index.html

5.3. 浏览器查看打包结果

打包后的dist文件可以在本地借助node服务器serve打开,全局安装serve

npm i serve -g

然后在项目根目录命令行执行serve -s dist,就可以启动打包后的项目了。

到现在一个基础的支持vue3和ts的webpack5就配置好了,但只有这些功能是远远不够的,还需要继续添加其他配置。

文章系列：

《第一篇：基础功能配置，webpack5配置vue3+ts基础环境，实现dev开发和打包构建》。
《第二篇：进阶功能配置，环境变量，支持css，less，图片和媒体资源，css3前缀，babel兼容》。
《第三篇：优化构建速度：构建耗时分析，持久化缓存，多线程loader，devtool，loader作用范围》。
《第四篇：优化化构建结果：构建结果分析，抽离css文件，压缩css，js文件，hash合理配置，代码分割，tree-shaking清理css和js，打包生成gzip》。
代码格式规范：editorconfig统一编辑器配置，prettier自动格式化代码，stylelint规范样式和保存自动修复，代码提交自动格式化css和js代码等。
代码语法规范：eslint检测js代码语法，style-lint检测样式代码语法，使用tsc检测类型报错，lint-staged按需检测代码等。
git提交规范：代码提交时husky检测代码语法规范，代码提交时husky检测commit备注规范，commitizen配置commit辅助信息等。