新项目搭建

前言

本文主要讲讲新项目搭建要做哪些基础配置，主要是为了团队合作方面需要做的一些规范

技术选型

vue3+vite+ts+less+ant-design-vue+tailwindcss

具体步骤

创建项目

用脚手架创建项目

$ pnpm create vue@latest
$ cd <your-project-name>
$ pnpm install
$ pnpm run dev

eslint相关配置

主要是eslint、prettier、commitlint、stylelint的配置。 eslintv9.x以上的参考这个博客 (opens new window)，挺全面的，就不赘述了

eslint.config.js，可参考

import eslint from '@eslint/js'
import globals from 'globals'
import tseslint from 'typescript-eslint'
import eslintPluginVue from 'eslint-plugin-vue'
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'

export default tseslint.config(
  {
    ignores: ['node_modules', 'dist', 'public'],
  },

  /** js推荐配置 */
  eslint.configs.recommended,
  /** ts推荐配置 */
  ...tseslint.configs.recommended,
  /** vue推荐配置 */
  ...eslintPluginVue.configs['flat/recommended'],

  {
    files: ['**/*.{ts,tsx,js,mjs,cjs,vue}'],
    rules: {
      'vue/multi-word-component-names': 'off',
      'no-console': 'error',
      'no-var': 'error',
    },
  },

  /**
   * 配置全局变量
   */
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.es2021,
        ...globals.node,

        /** 追加一些其他自定义全局规则 */
      },
    },
  },

  /**
   * vue 规则
   */
  {
    files: ['**/*.vue'],
    languageOptions: {
      parserOptions: {
        /** typescript项目需要用到这个 */
        parser: tseslint.parser,
        ecmaVersion: 'latest',
        /** 允许在.vue 文件中使用 JSX */
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    rules: {
      // 在这里追加 vue 规则
      // 这条规则是不允许修改props传递的属性，不加也是默认有的
      // 'vue/no-mutating-props': [
      //   'error',
      // 这里加上shallowOnly是修改这条规则，允许可改里层的属性，本身还是不允许改。
      // 但是不推荐，因为props还是保持单项数据流的规范比较好
      //   {
      //     shallowOnly: true,
      //   },
      // ],
    },
  },

  /**
   * prettier 配置
   * 会合并根目录下的.prettier.config.js 文件
   * @see https://prettier.io/docs/en/options
   */
  eslintPluginPrettierRecommended,
)

husky

git hooks工具，用于提交前校验和修复eslint，校验提交信息格式等

安装相应依赖

npm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional

初始化 Husky 配置

npx husky install

将 husky install 添加到 prepare 脚本

npm pkg set scripts.prepare="husky install"

在 package.json 中添加：

{
  "lint-staged": {
    "*.{js,ts,vue}": "eslint --fix",
    "*.{js,ts,vue,css,scss,html,json}": "prettier --write"
  }
}

添加 pre-commit 钩子

npx husky add .husky/pre-commit "npx lint-staged"

这会创建 .husky/pre-commit文件，修改内容如下：

bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

创建commitlint.config.js：

module.exports = {
  extends: ['@commitlint/config-conventional']
}

添加 commit-msg 钩子

npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

这会创建 .husky/commit-msg文件，内容如下：

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx commitlint --edit $1

注意: 配置完要执行一下pnpm install，husky才能生效 配置husky的时候注意文件位置，默认生成的文件都在_下面，应该会gitignore的，所以用到的文件直接移到.husky下面即可

安装UI组件库

这里以ant-design-vue为例

pnpm i --save ant-design-vue@4.x

然后到main.ts注册，这里以全局注册为例，其他的可参考官网 (opens new window)

import { createApp } from 'vue';
import Antd from 'ant-design-vue';
import App from './App';
import 'ant-design-vue/dist/reset.css';

const app = createApp(App);

app.use(Antd).mount('#app');

安装less

直接pnpm add less -D即可，vite集成了less-loader，所以这里无需安装less-loader了

如果需要启用 Less 中的 JavaScript 表达式、引入全局变量、变量值的修改等等，可以进行配置，在vite.config.js中配置

css: {
    preprocessorOptions: {
      less: {
        javascriptEnabled: true,  // 启用 Less 中的 JavaScript 表达式
        additionalData: `@import "@/styles/variables.less";`,  // 全局变量文件
        modifyVars: {  // 修改变量值（可选）
          'primary-color': '#1890ff'
        }
      }
    }
  },

安装tailwind

pnpm install -D tailwindcss@3.4.17 postcss autoprefixer

注意tailwindcss版本号，4.x的版本有问题，所以就用了3.x的最新版本

创建 tailwind.config.js

基础生成的配置文件如下，可以再根据自己需要进行配置

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

创建postcss.config.js

export default {
  plugins: {
    tailwindcss: {},  // 处理 @tailwind 指令
    autoprefixer: {}  // 添加浏览器前缀
  },
}

注意postcss autoprefixer这两个也是必须的，前者是css的后处理器，转化css语法，后者自动添加浏览器前缀

创建tailwind.css文件，并在main.js中引入该文件

@tailwind base;
@tailwind components;
@tailwind utilities;

安装stylelint

因为引入了tailwindcss，其中有些语法原生css不支持的，vscode会飘黄，如果直接设置vscode关闭检查，又会把所有的错误都关闭了，这样不好。所以最好的做法是关闭原生检查，引入stylelint加上相应rules检查

试了一些规则，只需要装这些就差不多了，装多了规则也不好

pnpm add -D stylelint stylelint-config-recommended stylelint-config-standard stylelint-prettier postcss-html 

参考版本如下

"postcss-html": "^1.8.0", // 只检测vue文件中style
"stylelint": "^16.18.0", 
"stylelint-config-recommended": "^16.0.0", // 推荐规则
"stylelint-config-standard": "^38.0.0", // 标准规则
"stylelint-prettier": "^5.0.3", // 避免和prettier互斥

stylelint.config.cjs 具体配置可参考

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-recommended',
    'stylelint-prettier/recommended',
  ],
  ignoreFiles: ['**/*.ts'],
  overrides: [
    {
      files: ['**/*.vue'],
      customSyntax: 'postcss-html',
    },
  ],
  rules: {
    'no-descending-specificity': null,
    'selector-pseudo-class-no-unknown': [
      true,
      {
        ignorePseudoClasses: ['deep', 'global', 'apply'],
      },
    ],
    'at-rule-no-unknown': [
      true,
      {
        ignoreAtRules: ['layer', 'for', 'include', 'mixin', 'tailwind'],
      },
    ],
    'value-keyword-case': [
      'lower',
      {
        ignoreFunctions: ['v-bind'], // 忽略 v-bind()中自动转为小写
      },
    ],
  },
}

关掉原生配置，最好是在工作区修改，然后提交远程，团队成员就可以按这个规范来。具体文件在.vscode/setting.json中，配置可参考

{
  // 禁用原生 CSS 校验
  "css.validate": false,
  "less.validate": false,
  "scss.validate": false,
  // 开启stylelint的校验
  "stylelint.enable": true,
  "stylelint.validate": ["css", "less", "vue", "html"],
  // 开启自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit",
    "source.fixAll.stylelint": "explicit"
  },
  // 保存的时候自动格式化
  "editor.formatOnSave": true,
  // 默认格式化工具选择prettier
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  // 配置该项，新建文件时默认就是space：2
  "editor.tabSize": 2
}

若是在vue文件开头中有奇怪的报错，是因为在.vscode的setting.json中有这个stylelint.config的空配置导致的错误，删掉就行，注意检查用户区和工作区，都要删掉。具体问题描述和解决看stylelint (opens new window)

按需自动引入组件

上面安装ant-design-vue代码举例的是全局注册，页面上不用一个个写import

但是全局注册就会存在一些实际没用的组件，也会打包进去，增加了打包体积，首屏加载速度也会变慢，所以大型项目还是局部注册会好一些

局部注册就是把上面app.use(Antd)的全局注册去掉，在页面使用时再一个个import就好，这种就是按需引入了

不过这是手动引入，还是有些麻烦的，可以借助unplugin-vue-components，自动进行按需引入

安装依赖 pnpm install unplugin-vue-components -D

配置 vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [
        AntDesignVueResolver({
          importStyle: 'less', // 使用 less 样式
        }),
      ],
    }),
  ],
})

会自动生成components.d.ts，可以看到自动引入后组件类型，在页面使用的时候，就会自动按需引入

这里除了配置AntDesignVueResolver，让其自动按需导入了，还有在项目中components文件夹（默认是这个，也可做配置项修改的）下的组件，也是会自动导入的

团队开发最好将components.d.ts放到.gitignore文件中忽略，因为这个文件会在安装和启动后自动生成，而团队多人同时开发的话，难免会造成冲突

按需自动引入方法

除了上面的unplugin-vue-components可以自动引入组件，还可以用unplugin-auto-import自动引入方法

这里就引入常用的vue、vue-router、pinia

下载安装unplugin-auto-import

pnpm i unplugin-auto-import -D

配置vite.config.ts，让自动引入插件能使用

import AutoImport from 'unplugin-auto-import/vite'

 plugins: [
    AutoImport({
      // 配置需要自动导入的库
      imports: ['vue', 'vue-router', 'pinia'],
      dts: './src/auto-imports.d.ts',
      eslintrc: {
        enabled: true,
      },
    }),
  ],

run dev后会自动生成auto-imports.d.ts文件和.eslintrc-auto-import.json

同样，这两个文件也推荐放到.gitignore里面

如此，使用上没问题了，但是eslint会飘红报错，所以需要配置eslint.config.ts和tsconfig.json

eslint.config.ts

// 因为eslint.config.ts是扁平化的配置，需要转化一下
import autoImportConfig from './.eslintrc-auto-import.json' assert { type: 'json' }

  {
    languageOptions: {
      globals: {
        /** 然后再globals里面配置就行了 */
        ...autoImportConfig.globals,
      },
    },
  },

tsconfig.json

// 若是tsconfig.json引入了tsconfig.app.json，就在tsconfig.app.json里配置，配*.d.ts就是所有.d.ts的文件了
{
  "include": ["src/**/*", "src/**/*.vue", "*.d.ts"],

}