从 0 搭建企业级 Vue3/Vite 脚手架（规范、eslint、husky、打包、环境变量全流程）

Hi，我是前端人类学 ！

随着 Vue3 的普及和 Vite 的成熟，构建一个稳定、可扩展的企业级前端工程化项目，已经成为团队协作与长期维护的基石。一个好的脚手架不仅仅是 npm init vue@latest，它还需要包含代码规范 、提交规范 、自动化检查 以及多环境部署 等能力。

本文将不依赖任何现成的 CLI 模板 ，从最原始的 npm init 开始，带你一步步手动搭建一个真正能用于生产环境的企业级 Vue3 项目骨架。在这个过程中，我们会直面并解决上述所有工程化痛点，最终交付一个规范、稳健、自动化的开发底座。

---

文章目录

• • 一、初始化项目与依赖安装
  • [二、代码规范------ESLint + Prettier](#二、代码规范——ESLint + Prettier)
  • • [2.1 安装依赖](#2.1 安装依赖)
    • [2.2 配置 `.eslintrc.cjs`](#2.2 配置 .eslintrc.cjs)
    • [2.3 配置 `.prettierrc.cjs`](#2.3 配置 .prettierrc.cjs)
    • [2.4 添加 NPM Scripts](#2.4 添加 NPM Scripts)
  • [三、Git Hooks------Husky + lint-staged](#三、Git Hooks——Husky + lint-staged)
  • • [3.1 安装依赖](#3.1 安装依赖)
    • [3.2 初始化 Husky](#3.2 初始化 Husky)
    • [3.3 配置 lint-staged](#3.3 配置 lint-staged)
    • [3.4 添加 pre-commit Hook](#3.4 添加 pre-commit Hook)
  • 四、提交规范------Commitlint
  • • [4.1 安装依赖](#4.1 安装依赖)
    • [4.2 创建配置文件 `commitlint.config.cjs`](#4.2 创建配置文件 commitlint.config.cjs)
    • [4.3 添加 commit-msg Hook](#4.3 添加 commit-msg Hook)
  • 五、环境变量与多环境配置
  • • [5.1 创建环境文件](#5.1 创建环境文件)
    • [5.2 在代码中使用](#5.2 在代码中使用)
    • [5.3 在 `package.json` 中配置运行命令](#5.3 在 package.json 中配置运行命令)
  • [六、打包优化------Vite 配置进阶](#六、打包优化——Vite 配置进阶)
  • 七、完整的项目脚本命令汇总

---

一、初始化项目与依赖安装

我们使用 Vite 官方脚手架快速创建基础项目。

# 使用 pnpm（推荐）或 npm/yarn
pnpm create vite my-vue3-app --template vue-ts
cd my-vue3-app
pnpm install

选择 vue-ts 模板可以让我们直接获得 Vue3 + TypeScript 的完美组合。

安装完成后，建议调整目录结构为更适合企业级开发的方式：

src/
├── api/          # API 请求
├── assets/       # 静态资源
├── components/   # 公共组件
├── composables/  # 组合式函数
├── layouts/      # 布局组件
├── router/       # 路由
├── store/        # Pinia 状态管理
├── styles/       # 全局样式
├── types/        # 类型定义
├── utils/        # 工具函数
└── views/        # 页面视图

二、代码规范------ESLint + Prettier

企业级项目最核心的便是代码一致性。我们将整合 ESLint （代码质量）与 Prettier（代码格式化）。

2.1 安装依赖

pnpm add -D eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-vue eslint-config-prettier eslint-plugin-prettier

2.2 配置 .eslintrc.cjs

module.exports = {
  root: true,
  env: {
    browser: true,
    node: true,
    es2021: true,
  },
  extends: [
    'plugin:vue/vue3-recommended',
    'eslint:recommended',
    '@vue/typescript/recommended',
    'prettier', // 关闭与 Prettier 冲突的规则
  ],
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: '@typescript-eslint/parser',
    ecmaVersion: 2021,
    sourceType: 'module',
  },
  rules: {
    'vue/multi-word-component-names': 'off',
    '@typescript-eslint/no-explicit-any': 'warn',
    '@typescript-eslint/ban-types': 'off',
  },
};

2.3 配置 .prettierrc.cjs

module.exports = {
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: true,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'avoid',
  endOfLine: 'lf',
};

2.4 添加 NPM Scripts

"scripts": {
  "lint": "eslint . --ext .vue,.js,.ts,.jsx,.tsx --fix",
  "format": "prettier --write ."
}

三、Git Hooks------Husky + lint-staged

为了保证提交到仓库的代码是"干净"的，我们会在 Git commit 前自动执行代码检查与格式化。

3.1 安装依赖

pnpm add -D husky lint-staged

3.2 初始化 Husky

npx husky install

3.3 配置 lint-staged

在 package.json 中添加：

"lint-staged": {
  "*.{vue,js,ts}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,md}": [
    "prettier --write"
  ]
}

3.4 添加 pre-commit Hook

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

现在，每次 git commit 前，都会自动修复和格式化暂存区的代码。

四、提交规范------Commitlint

统一的提交信息有助于生成 CHANGELOG 和版本管理。我们采用业界流行的 Conventional Commits 规范。

4.1 安装依赖

pnpm add -D @commitlint/cli @commitlint/config-conventional

4.2 创建配置文件 commitlint.config.cjs

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'revert'],
    ],
    'subject-case': [0],
  },
};

4.3 添加 commit-msg Hook

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

五、环境变量与多环境配置

企业级项目通常有开发、测试、预发布、生产等多个环境。Vite 通过 .env 文件支持这一点。

5.1 创建环境文件

在项目根目录下创建：

• .env ------ 所有环境公共变量
• .env.development ------ 开发环境
• .env.staging ------ 预发布环境
• .env.production ------ 生产环境

示例 .env.development：

VITE_APP_TITLE=开发环境
VITE_API_BASE_URL=/api
VITE_ENV=development

5.2 在代码中使用

// 通过 import.meta.env 访问
const apiUrl = import.meta.env.VITE_API_BASE_URL;

5.3 在 package.json 中配置运行命令

"scripts": {
  "dev": "vite",
  "build:dev": "vite build --mode development",
  "build:staging": "vite build --mode staging",
  "build:prod": "vite build --mode production"
}

Vite 会根据 --mode 参数加载对应的 .env.[mode] 文件。

六、打包优化------Vite 配置进阶

在 vite.config.ts 中针对企业级打包需求进行优化配置。

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { resolve } from 'path';

export default defineConfig(({ mode }) => ({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          element: ['element-plus'],
        },
      },
    },
    chunkSizeWarningLimit: 1000,
    minify: 'terser', // 默认 esbuild，可以切换为 terser 做更激进压缩
  },
  server: {
    proxy: {
      '/api': {
        target: 'https://mock.example.com',
        changeOrigin: true,
        rewrite: path => path.replace(/^\/api/, ''),
      },
    },
  },
}));

七、完整的项目脚本命令汇总

最终 package.json 中的 scripts 应该是这样的：

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "build:dev": "vite build --mode development",
  "build:staging": "vite build --mode staging",
  "build:prod": "vite build --mode production",
  "preview": "vite preview",
  "lint": "eslint . --ext .vue,.js,.ts,.jsx,.tsx --fix",
  "format": "prettier --write .",
  "prepare": "husky install"
}

---

一个良好的脚手架是团队协作的基石，希望这篇文章能帮助你和你的团队快速进入企业级 Vue3 开发状态。如果你觉得有用，欢迎收藏或分享给更多朋友！