使用Vue3+ElementPlus+TS:项目初始化与核心依赖集成摘要本文系“Vue3+ElementPlus+TS

摘要

本文系“Vue3+ElementPlus+TS从零搭建后台管理系统”系列的第三篇。在前两篇文章中，我们介绍了项目创建、env.d.ts中三斜线指令的深层含义，以及Husky工具链在保障代码规范性方面的重要性。本篇将聚焦于项目初始化的核心环节，规划了项目的目录机构，集成了ElementPlus UI框架与Sass预处理器、自动化导入机制的配置、ElementPlus图标的全局化导入、Sass全局样式的设定与CSS基础初始化，以及Vite构建工具中环境变量的精细化配置与TypeScript的类型支持，只在开发环境中选择性启用Vue DevTools，同时优化ESLint针对Vue单文件组件（SFC）的命名规范。

项目目录结构的规范化设计

为了提升项目的可维护性与可扩展性，本文推荐采用如下目录组织方案：

demo-front/                      # 项目根目录
├── .editorconfig                # EditorConfig配置文件，用于统一代码风格
├── .env.development             # 开发环境变量配置
├── .env.production              # 生产环境变量配置
├── .eslintrc-auto-import.json   # ESLint自动导入配置
├── .gitattributes               # Git属性配置
├── .gitignore                   # Git忽略文件配置
├── .husky/                      # Husky Git钩子配置目录
│   ├── _/                       # Husky内部文件
│   ├── commit-msg               # 提交消息钩子
│   └── pre-commit               # 提交前钩子
├── .lintstagedrc.json           # lint-staged配置，用于对暂存文件进行lint
├── .prettierrc.json             # Prettier代码格式化配置
├── .vscode/                     # VS Code编辑器配置
│   └── extensions.json          # 推荐的VS Code扩展
├── README.md                    # 项目说明文档
├── TODO.md                      # 待办事项列表
├── commitlint.config.cjs        # Commitlint配置，用于规范提交信息
├── docs/                        # 文档目录
├── eslint.config.ts             # ESLint配置文件
├── index.html                   # 应用入口HTML文件
├── package-lock.json            # npm包版本锁定文件
├── package.json                 # 项目依赖和脚本配置
├── public/                      # 静态资源目录
│   ├── favicon.ico              # 网站图标
│   └── mockServiceWorker.js     # Mock Service Worker脚本
├── src/                         # 源代码目录
│   ├── App.vue                  # 应用根组件
│   ├── api/                     # API接口目录
│   │   ├── index.ts             # API入口文件
│   │   └── modules/             # API模块目录
│   ├── assets/                  # 静态资源目录
│   │   └── logo.svg             # 项目logo
│   ├── components/              # 公共组件目录
│   ├── config/                  # 配置文件目录
│   ├── directives/              # Vue自定义指令目录
│   ├── hooks/                   # Vue组合式API钩子目录
│   ├── layout/                  # 布局组件目录
│   ├── main.ts                  # 应用入口文件
│   ├── mocks/                   # 模拟数据目录
│   ├── plugins/                 # 插件目录
│   ├── router/                  # 路由目录
│   ├── stores/                  # 状态存储目录
│   ├── styles/                  # 样式目录
│   ├── types/                   # TypeScript类型定义目录
│   ├── utils/                   # 工具函数目录
│   └── views/                   # 页面视图目录
├── tsconfig.app.json            # TypeScript应用配置
├── tsconfig.json                # TypeScript主配置
├── tsconfig.node.json           # TypeScript Node配置
└── vite.config.ts               # Vite构建工具配置

ElementPlus UI与Sass预处理器的集成

依赖引入

npm install element-plus sass @element-plus/icons-vue 和 npm install -D unplugin-vue-components unplugin-auto-import

ElementPlus基础配置和自动导入

main.ts配置

//尽管使用了自动导入,但是ElMessage的样式还的手动导入
import 'element-plus/theme-chalk/src/message.scss'
import 'element-plus/theme-chalk/src/message-box.scss'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
}

配置按需导入(vite.config.ts)

import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  // ...
  plugins: [
    // ...
    AutoImport({
        resolvers: [ElementPlusResolver()],
        // 导入 Vue 函数，如：ref, reactive, toRef 等
        imports: ['vue', 'vue-router', 'pinia'],
        dts: 'src/types/auto-imports.d.ts', // 自动生成声明文件
        dirs: ['src/hooks', 'src/stores'], // 自动导入自定义的 hooks 和 stores
        vueTemplate: true, // 允许模板里也自动导入
        eslintrc: {
          enabled: true,
          filepath: './.eslintrc-auto-import.json',
          globalsPropValue: true,
        },
    }),
    Components({
       dirs: ['src/components'], // 自动扫描 components 目录
       extensions: ['vue', 'md'], // 支持 vue 和 md 组件
       deep: true, // 支持子目录递归
       dts: 'src/types/components.d.ts', // 自动生成声明文件
       // 导入 Element Plus函数，如：ElMessage, ElMessageBox 等
       resolvers: [ElementPlusResolver()],
    }),
  ],
  css: {
      preprocessorOptions: {
        // 定义全局 SCSS 变量
        scss: {
          api: 'modern-compiler',
          //知识点，这是使用@use而不是import。未来的版本sass会弃用import
          additionalData: `@use "@/styles/var.scss";`,
        },
      },
    },
})

注：此处使用 @use 代替传统的 @import，符合 Sass 的现代语法规范，提升可维护性与模块化能力。

类型系统与 ESLint 的支持

为确保自动导入 API 在开发过程中具有良好的类型推导及 ESLint 识别能力，需要在 tsconfig.json 和 ESLint 配置中分别进行声明：

// tsconfig.json，让ts识别ref, reactive, toRef 等
{
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue", "src/auto-imports.d.ts", "src/components.d.ts"],
  // ...
}

import autoImportGlobals from './.eslintrc-auto-import.json' // 引入自动生成的 globals，否则使用Elmessage时eslint还会报错

export default defineConfig([
 //....
{
    name: 'app/auto-import',
    files: ['**/*.{ts,mts,tsx,vue}'],
    languageOptions: {
      globals: autoImportGlobals.globals, // 挂载到 languageOptions.globals
    },
  },
  js.configs.recommended,
  ...pluginVue.configs['flat/essential'],
  skipFormatting,
])

配置国际化App.vue

//配置语言是中文，否则一个组件(分页等)显示的是中文
<script setup lang="ts">
import zhCn from 'element-plus/es/locale/lang/zh-cn'
</script>

<template>
  <el-config-provider :locale="zhCn">
    <RouterView />
  </el-config-provider>
</template>

vite配置优化

Vite通过.env文件系列（.env, .env.development, .env.production等）管理环境变量。在vite.config.ts中，可以通过loadEnv函数加载这些变量。

// vite.config.ts
import { defineConfig, loadEnv, type UserConfig } from 'vite'
// ...其他导入

export default defineConfig(({ mode }) => {
  // 根据当前工作模式加载对应的环境变量
  // process.cwd() 获取当前工作目录
  const env = loadEnv(mode, process.cwd())

  console.log(env.VITE_BASE_URL); // 示例：访问环境变量
  const config:UserConfig = {
      base: env.VITE_BASE_URL,
      plugins:[
           mode === 'development' && vueDevTools(), //当 mode 不是 'development' 时， mode === 'development' && vueDevTools() 会返回 false,就不会加载这个插件
      ]
  }

 // 过滤掉 plugins 数组中的 false 值
  config.plugins = config.plugins?.filter(Boolean)
  return config
})

ESLint规则微调：Vue组件命名规范

Vue官方推荐组件名使用多词（Multi-word）形式，以避免与原生HTML元素冲突。ESLint的vue/multi-word-component-names规则强制此规范。然而，在某些特定场景下，如页面级根组件或布局组件，可能希望使用单一名词，如Index.vue、Layout.vue。

项目模板中ESLint已采用Flat Config (eslint.config.js)。我们可以调整此规则，允许特定的单文件组件名。
```
export default defineConfigWithVueTs(
{
    files: ['**/*.vue'],
    rules: {
      'vue/multi-word-component-names': [
        'error',
        {
          ignores: ['index', '404'], // 允许 index.vue 但强制其他 Vue 组件使用多单词名称
        },
      ],
    },
  },
)
```