项目创建及配置初始化

本项目使用Vite 进行构建

初始化项目

在终端中打开，键入下列命令：

使用npm

npm create vite@latest

EsLint 配置

安装并使用

提示

前提条件：内置 SSL 支持的 Node.js 版本（^12.22.0、^14.17.0 或 >=16.0.0），如果你使用的是官方 Node.js 发行版，那么已经内置了 SSL 支持

使用以下命令安装并配置EsLint:

npm init @eslint/config

1. 选择第二个

2. 选用那种模块进行开发？

• ES6 模块：这是现代 JavaScript 的模块系统，通常也叫做 ECMAScript 模块（ES Modules）。

  • 导入：import ... from 'module';
  • 导出：export ...;

• CommonJS 模块：这是 Node.js 传统的模块系统。

  • 导入：const module = require('module');
  • 导出：module.exports = ...;

3. 选择使用哪个框架进行开发？

5. 选择使用Typescript吗？

5. 项目在哪里运行？

6. 安装依赖插件？

6. 选择使用的包管理器进行安装

比如我使用 npm

配置 eslint.config.js 文件

安装初始化完后，会在项目根目录下自动生成 eslint.config.js 文件，需要对这个文件进行配置：

提示

eslint.config.js 文件使用了一个更现代的 ESLint 配置方式，这是 ESLint 在较新版本中引入的一种配置方法，称为“平铺配置”（flat config）。这与传统的 .eslintrc 配置文件有所不同，平铺配置允许使用更灵活的配置结构，可以更轻松地进行组合和扩展。

import globals from "globals";
import pluginJs from "@eslint/js";
import tseslint from "@typescript-eslint/eslint-plugin";
import pluginVue from "eslint-plugin-vue";
import prettier from "eslint-plugin-prettier";
import tsParser from "@typescript-eslint/parser";
import vueParser from "vue-eslint-parser";

export default [
  {
    files: ["**/*.{js,mjs,cjs,ts,vue,jsx,tsx}"],
    // 此处配置忽略文件
    ignores: ["node_modules/**", "dist/**"], // 忽略根目录下的 node_modules 和 dist 目录
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
        jest: "readonly", // 将 jest 配置为只读
      },
      ecmaVersion: "latest", // 使用最新的 ECMAScript 版本
      sourceType: "module", // 模块化
      parser: vueParser, // 使用 Vue 解析器
      parserOptions: {
        ecmaVersion: "latest",
        sourceType: "module",
        parser: tsParser, // TypeScript 解析器
        jsxPragma: "React",
        ecmaFeatures: {
          jsx: true, // 支持 JSX
        },
      },
    },
    plugins: {
      vue: pluginVue,
      "@typescript-eslint": tseslint,
      prettier: prettier,
    },
    rules: {
      ...pluginJs.configs.recommended.rules, // 启用 ESLint 推荐规则
      ...tseslint.configs.recommended.rules, // 启用 TypeScript 推荐规则
      ...pluginVue.configs["vue3-essential"].rules, // 启用 Vue3 基本规则
      "prettier/prettier": "error", // 启用 Prettier 规则
      "no-var": "error", // 要求使用 let 或 const 而不是 var
      "no-multiple-empty-lines": ["warn", { max: 1 }], // 不允许多个空行
      "no-console": process.env.NODE_ENV === "production" ? "error" : "off",
      "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
      "no-unexpected-multiline": "error", // 禁止空余的多行
      "no-useless-escape": "off", // 禁止不必要的转义字符

      "@typescript-eslint/no-unused-vars": "error", // 禁止定义未使用的变量
      "@typescript-eslint/prefer-ts-expect-error": "error", // 禁止使用 @ts-ignore
      "@typescript-eslint/no-explicit-any": "off", // 禁止使用 any 类型
      "@typescript-eslint/no-non-null-assertion": "off",
      "@typescript-eslint/no-namespace": "off", // 禁止使用自定义 TypeScript 模块和命名空间。
      "@typescript-eslint/semi": "off",

      "vue/multi-word-component-names": "off", // 关闭多词组件名称规则
      "vue/script-setup-uses-vars": "error", // 防止<script setup>使用的变量<template>被标记为未使用
      "vue/no-mutating-props": "off", // 允许变异 props
      "vue/attribute-hyphenation": "off", // 关闭属性连字符化命名规则
    },
  },
];

配置忽略文件

TIP

EsLint 最新版本采用了平铺式的配置风格，所以忽略文件应该在eslint.config.js 中添加配置项来进行实现，如下代码所示：

// .eslintignore

import globals from "globals";
import pluginJs from "@eslint/js";
import tseslint from "@typescript-eslint/eslint-plugin";
import pluginVue from "eslint-plugin-vue";
import prettier from "eslint-plugin-prettier";
import tsParser from "@typescript-eslint/parser";
import vueParser from "vue-eslint-parser";

export default [
  {
    files: ["**/*.{js,mjs,cjs,ts,vue,jsx,tsx}"],
    // 此处配置忽略文件
    ignores: ["node_modules/**", "dist/**"]
    
    // 后面的代码......
  },
];

Prettier 配置

了解更多配置详情，请阅读：Prettier 中文文档

安装Prettier

npm install --save-dev --save-exact prettier

创建配置文件

以下命令会在项目根目录下生成.prettierrc 配置文件

node --eval "fs.writeFileSync('.prettierrc','{}\n')"

.prettierrc 配置文件

{
    "singleQuote": true,
    "semi": false,
    "bracketSpacing": true,
    "htmlWhitespaceSensitivity": "ignore",
    "endOfLine": "auto",
    "trailingComma": "all",
    "tabWidth": 4
}

.prettierignore 忽略文件配置

/dist/*
/html/*
.local
/node_modules/**
**/*.svg
**/*.sh
/public/*

配置StyleLint

配置StyleLint 可对sass 语法进行检查

安装 StyleLint

使用以下命令，将配置 对 sass语法的支持：

npm install --save-dev stylelint stylelint-config-standard-scss

.stylelintrc.json 文件配置

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-standard-scss",
    "stylelint-config-recommended-vue",
    "stylelint-config-recess-order",
    "stylelint-config-html/vue"
  ],
  "overrides": [
    {
      "files": ["**/*.{scss,css,vue,html}"],
      "customSyntax": "postcss-scss"
    },
    {
      "files": ["**/*.{html,vue}"],
      "customSyntax": "postcss-html"
    }
  ],
  "ignoreFiles": [
    "**/*.js",
    "**/*.jsx",
    "**/*.tsx",
    "**/*.ts",
    "**/*.json",
    "**/*.md",
    "**/*.yaml"
  ],
  "rules": {
    "value-keyword-case": null,
    "no-descending-specificity": null,
    "function-url-quotes": "always",
    "no-empty-source": null,
    "selector-class-pattern": null,
    "property-no-unknown": null,
    "block-opening-brace-space-before": "always",
    "value-no-vendor-prefix": null,
    "property-no-vendor-prefix": null,
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global", "v-deep", "deep"]
      }
    ]
  }
}

.stylelintignore 忽略文件配置

/node_modules/*
/dist/*
/html/*
/public/*

配置 husky

安装 husky

详情查看：官方文档

npm install --save-dev husky

初始化 husky

npx husky init

pre-commit配置

npm run format

commitlint 配置

安装 commitlint

详情查看，官方文档

npm install --save-dev @commitlint/cli @commitlint/config-conventional

commitlint.config.js 配置

在项目的根目录下创建一个 commitlint.config.cjs 文件，用于配置 commitlint：

module.exports = {
    extends: ['@commitlint/config-conventional'],
    // 校验规则
    rules: {
        'type-enum': [
            2,
            'always',
            [
                'feat',
                'fix',
                'docs',
                'style',
                'refactor',
                'perf',
                'test',
                'chore',
                'revert',
                'build',
            ],
        ],
        'type-case': [0],
        'type-empty': [0],
        'scope-empty': [0],
        'scope-case': [0],
        'subject-full-stop': [0, 'never'],
        'subject-case': [0, 'never'],
        'header-max-length': [0, 'always', 72],
    },
}

commit-msg 配置

手动创建：.husky/commit-msg 文件，并写入：

npm run commitlint

统一包管理工具

比如我的项目将包管理工具统一为：npm，这样项目如果使用其他包管理工具安装依赖就会报错。

在项目根目录下创建文件：scripts/preinstall.js

if (!/npm/.test(process.env.npm_execpath || '')) {
    console.warn(
        `\u001b[33mThis repository must use npm as the package manager ` +
            `for scripts to work properly.\u001b[39m\n`,
    )
    process.exit(1)
}

在 package.json 中添加指令

提示

以下 package.json 中的指令，都是上述配置过程中，每个配置项需要的指令，为了方便，特此全部集中在此处进行展现：

{
  "name": "vue3_ts",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite --open",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint src",
    "fix": "eslint src --fix",
    "format": "prettier --write \"./**/*.{html,vue,ts,js,json,md}\"",
    "lint:eslint": "eslint src/**/*.{ts,vue} --cache --fix",
    "lint:style": "stylelint src/**/*.{css,scss,vue} --cache --fix",
    "prepare": "husky install",
    "commitlint": "commitlint --config commitlint.config.cjs -e -V",
    "preinstall": "node ./scripts/preinstall.js"
  },
  "dependencies": {
    "@element-plus/icons-vue": "^2.3.1",
    "@vue/runtime-core": "^3.4.38",
    "element-plus": "^2.8.0",
    "vue": "^3.4.38"
  },
  "devDependencies": {
    "@commitlint/cli": "^19.4.0",
    "@commitlint/config-conventional": "^19.2.2",
    "@typescript-eslint/eslint-plugin": "^6.5.0",
    "@typescript-eslint/parser": "^6.5.0",
    "@vitejs/plugin-vue": "^5.1.2",
    "eslint": "^8.50.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.2.1",
    "eslint-plugin-vue": "^9.27.0",
    "husky": "^9.1.5",
    "prettier": "^3.3.3",
    "sass-embedded": "^1.77.8",
    "stylelint": "^16.8.2",
    "stylelint-config-standard-scss": "^13.1.0",
    "typescript": "^5.5.3",
    "vite": "^5.4.1",
    "vue-eslint-parser": "^9.4.3",
    "vue-tsc": "^2.0.29"
  }
}