登录vue3+vite+ts创建项目-企业级
Vue3+Vite+TS 企业级项目搭建完整指南（含多环境配置）
本文基于 Vue3、Vite4+、TypeScript 构建企业级项目，整合多环境配置、代码规范、自动导入、样式处理等核心功能，配置结构清晰可扩展，适配生产、开发、测试多场景需求。
一、初始化 Vue3 项目
采用 Vite 构建工具（比 Webpack 启动更快、热更新更高效，是 Vue3 官方推荐方案），快速初始化项目并集成 TypeScript。
步骤 1：执行初始化命令
# 使用 npm/cnpm/pnpm 均可，这里以 cnpm 为例
cnpm create vite@latest
# 若需指定版本，可执行：cnpm create vite
步骤 2：交互式配置项目
-
输入项目名：如
vite-vue3-ts-enterprise（建议英文，避免特殊字符） -
选择框架：上下键切换至
Vue（默认适配 Vue3） -
选择变体：切换至
TypeScript（集成 TS 类型校验）
步骤 3：安装依赖并启动项目
# 进入项目目录
cd vite-vue3-ts-enterprise
# 安装依赖（优先用项目包管理器，避免版本冲突）
cnpm install
# 启动开发环境
cnpm run dev
启动成功后，访问 http://localhost:5173 即可看到 Vue3 初始页面。Vite 默认端口为 5173，后续可在配置中修改。
二、基础配置（环境、别名、类型）
完善项目基础配置，解决路径别名、Node 类型、环境变量加载等核心问题，适配企业级开发习惯。
步骤 1：安装 Node 类型依赖
为 TS 提供 Node 环境类型定义，避免路径处理等操作时 TS 报错。
cnpm i @types/node --save-dev
步骤 2：配置 tsconfig.json
优化 TS 编译规则，添加路径别名、类型目录等配置，确保 TS 语法兼容 Vue3 单文件组件（SFC）。
{
"compilerOptions": {
"typeRoots": [
"node_modules/@types", // 默认类型目录
"src/types" // 自定义类型目录（后续可存放全局类型）
],
"target": "ESNext", // 目标 ES 版本
"useDefineForClassFields": true, // 适配 Vue3 类组件
"module": "ESNext", // 模块规范
"moduleResolution": "Node", // 模块解析方式
"strict": true, // 开启严格模式（强制类型校验）
"jsx": "preserve", // 保留 JSX 语法（适配 Vue3 JSX/TSX）
"resolveJsonModule": true, // 允许导入 JSON 文件
"isolatedModules": true, // 确保每个文件都是独立模块（Vite 要求）
"esModuleInterop": true, // 兼容 CommonJS 模块
"lib": ["ESNext", "DOM"], // 引入 ES 特性和 DOM 类型
"skipLibCheck": true, // 跳过第三方库类型校验（提升编译速度）
"noEmit": true, // 不生成编译产物（Vite 负责构建）
"baseUrl": "./", // 基础路径
"paths": { // 路径别名（简化导入，避免相对路径嵌套）
"@": ["src"],
"@/*": ["src/*"]
}
},
"include": [ // 需要 TS 校验的文件
"src/**/*.ts",
"src/**/*.d.ts",
"src/**/*.tsx",
"src/**/*.vue",
"build/**/*" // 新增：让 TS 识别 build 文件夹下的配置文件
],
"references": [
{ "path": "./tsconfig.node.json" } // 关联 Node 环境配置
]
}
步骤 3：配置多环境变量（env 文件夹）
创建独立 env 文件夹管理不同环境变量，实现开发、测试、生产环境隔离，避免硬编码。
1. 创建 env 文件夹及配置文件
# 根目录创建 env 文件夹
mkdir env
# 新建 3 个环境配置文件（对应开发、测试、生产）
touch env/.env.development
touch env/.env.test
touch env/.env.production
2. 编写各环境变量
Vite 环境变量需以 VITE_ 为前缀，否则无法在业务代码中访问。
-
env/.env.development（开发环境）
# 开发环境 API 基础地址 `` VITE_API_BASE_URL=http://localhost:3000/api `` # 环境标识 `` VITE_ENV=development `` # 调试模式（开发环境开启） ``VITE_DEBUG=true -
env/.env.test（测试环境）
VITE_API_BASE_URL=https://test.api.example.com `` VITE_ENV=test ``VITE_DEBUG=false -
env/.env.production（生产环境）
VITE_API_BASE_URL=https://api.example.com `` VITE_ENV=production ``VITE_DEBUG=false
步骤 4：拆分多环境 Vite 配置（build 文件夹）
将 Vite 配置拆分为「基础配置+环境专属配置」，统一放入 build 文件夹，提升可维护性，后续新增环境可快速扩展。
1. 创建 build 文件夹及配置文件
# 根目录创建 build 文件夹（集中管理所有配置）
mkdir build
# 新建 3 个配置文件
touch build/vite.base.ts # 基础通用配置
touch build/vite.dev.ts # 开发环境配置
touch build/vite.prod.ts # 生产环境配置
调整后根目录核心结构：
vite-vue3-ts-enterprise/
├── build/ # 配置文件目录
│ ├── vite.base.ts # 基础配置（通用逻辑）
│ ├── vite.dev.ts # 开发环境专属配置
│ └── vite.prod.ts # 生产环境专属配置
├── env/ # 环境变量目录
├── src/ # 业务代码目录
├── public/ # 静态资源目录
├── package.json
├── tsconfig.json
└── tsconfig.node.json
2. 编写 build 文件夹下的配置文件
（1）build/vite.base.ts（基础通用配置）
抽取所有环境共用逻辑，如插件、别名、环境变量目录、静态资源处理等。
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue'; // Vue 单文件组件插件
import vueJsx from '@vitejs/plugin-vue-jsx'; // 支持 Vue3 JSX/TSX
import path from 'path';
export default defineConfig({
// 环境变量目录（指定 env 文件夹，而非默认根目录）
envDir: path.resolve(__dirname, '../env'),
// 插件配置（所有环境共用插件）
plugins: [
vue(), // 解析 .vue 文件
vueJsx() // 解析 .jsx/.tsx 文件
],
// 路径解析配置
resolve: {
alias: {
// 别名 @ 指向 src 目录（与 tsconfig.json 保持一致）
'@': path.resolve(__dirname, '../src')
}
},
// 基础构建配置
build: {
outDir: path.resolve(__dirname, '../dist'), // 打包输出目录
assetsDir: 'assets', // 静态资源存放目录
rollupOptions: {
// 静态资源分类打包（按后缀名分组）
output: {
assetFileNames: (assetInfo) => {
if (assetInfo.name?.endsWith('.css')) {
return 'css/[name].[hash:8].[ext]';
}
if (assetInfo.name?.match(/.(png|jpg|jpeg|gif|svg)$/i)) {
return 'images/[name].[hash:8].[ext]';
}
return 'assets/[name].[hash:8].[ext]';
},
// JS 文件分类打包
chunkFileNames: 'js/chunks/[name].[hash:8].js',
entryFileNames: 'js/[name].[hash:8].js'
}
}
}
});
（2）build/vite.dev.ts（开发环境配置）
补充开发环境独有逻辑，如热更新、代理、端口配置等，优化开发体验。
import { defineConfig ，mergeConfig} from 'vite';
import path from 'path';
import baseConfig from './vite.base';
export default mergeConfig(
baseConfig,
defineConfig({
mode: 'development', // 开发模式
server: {
port: 8080, // 自定义开发端口（替换默认 5173）
open: true, // 启动后自动打开浏览器
hmr: { // 热模块替换（提升热更新速度）
host: 'localhost',
port: 8080
},
proxy: { // 接口代理（解决跨域问题）
'/api': {
target: process.env.VITE_API_BASE_URL, // 读取环境变量中的 API 地址
changeOrigin: true, // 开启跨域代理
rewrite: (path) => path.replace(/^/api/, '') // 重写路径（移除前缀 /api）
}
}
},
css: {
devSourcemap: true // 开发环境生成 CSS SourceMap（便于调试样式）
}
})
);
（3）build/vite.prod.ts（生产环境配置）
补充生产环境优化逻辑，如压缩、清除控制台、SourceMap 控制等，提升打包产物性能。
import { defineConfig ，mergeConfig} from 'vite';
import { visualizer } from 'rollup-plugin-visualizer'; // 打包分析插件
import baseConfig from './vite.base';
export default mergeConfig(
baseConfig,
defineConfig({
mode: 'production', // 生产模式
build: {
minify: 'terser', // 使用 terser 压缩代码（比默认 esbuild 压缩更彻底）
sourcemap: false, // 生产环境关闭 SourceMap（保护源码，减小包体积）
terserOptions: {
compress: {
drop_console: true, // 清除控制台打印（生产环境可选）
drop_debugger: true // 清除 debugger 语句
}
}
},
plugins: [
// 打包分析插件（可选，生成可视化报告，优化包体积）
visualizer({
open: false, // 不自动打开报告
filename: path.resolve(__dirname, '../dist/analysis.html')
})
]
})
);
4. 更新 package.json 脚本
修改启动、打包脚本，指向 build 文件夹下的对应配置文件，实现按环境加载配置。
"scripts": {
"dev": "vite --config build/vite.dev.ts", // 启动开发环境
"build:dev": "vue-tsc -b && vite build --config build/vite.dev.ts", // 开发环境打包（测试用）
"build:test": "vue-tsc -b && vite build --config build/vite.prod.ts --mode test", // 测试环境打包
"build:prod": "vue-tsc -b && vite build --config build/vite.prod.ts", // 生产环境打包
"type-check": "vue-tsc --noEmit", // TS 类型校验（不生成产物）
"preview": "vite preview" // 预览打包产物
}
vue-tsc -b 用于在打包前执行 TS 类型校验，若存在类型错误则终止打包，避免带错上线；--mode 参数用于指定环境，匹配 env 文件夹下的配置文件。
三、集成代码规范工具（ESLint + Prettier）
统一代码风格，减少团队协作冲突，自动修复格式问题，确保代码质量。需先在 VS Code 安装 ESLint、Prettier 插件。
步骤 1：安装依赖
# ESLint 核心及 Vue/TS 适配依赖
cnpm i eslint @eslint/js typescript-eslint @typescript-eslint/parser @typescript-eslint/plugin eslint-plugin-vue vue-eslint-parser -D
# Prettier 及 ESLint 兼容依赖（解决两者规则冲突）
cnpm i prettier eslint-config-prettier eslint-plugin-prettier -D
# Vite ESLint 插件（开发时实时校验）
cnpm i vite-plugin-eslint -D
步骤 2：配置 ESLint（eslint.config.js）
ESLint 8.21.0+ 支持扁平配置文件，适配 Vue3+TS 语法，集成 Prettier 规则。
import globals from "globals";
import pluginJs from "@eslint/js";
import tseslint from "typescript-eslint";
import pluginVue from "eslint-plugin-vue";
import prettier from "eslint-plugin-prettier";
import prettierConfig from "eslint-config-prettier";
import eslintParser from "vue-eslint-parser";
export default [
// 配置忽略文件（替代传统 .eslintignore）
{
ignores: [
"node_modules/**",
"dist/**",
"public/**",
"build/**",
"src/assets/**",
"*.config.js",
"*.config.ts"
]
},
// 基础配置（适配 Vue/TS 文件）
{
files: ["**/*.{js,mjs,cjs,vue,ts,tsx}"],
languageOptions: {
parser: eslintParser, // 解析 Vue 单文件组件
parserOptions: {
parser: "@typescript-eslint/parser", // 解析 TS 语法
ecmaVersion: 2020,
sourceType: "module"
},
globals: { ...globals.browser, ...globals.node } // 全局变量
},
plugins: {
vue: pluginVue,
"@typescript-eslint": tseslint.plugin,
prettier: prettier // 集成 Prettier
},
rules: {
// 基础规则
"no-var": "error", // 禁止使用 var
"no-console": process.env.NODE_ENV === "production" ? "error" : "off", // 生产环境禁止 console
"no-multiple-empty-lines": ["warn", { max: 1 }], // 最多允许 1 行空行
// Vue 规则
"vue/multi-word-component-names": "off", // 关闭组件名多单词校验（灵活命名）
"vue/valid-template-root": "off", // 允许模板根节点多元素
// TS 规则
"@typescript-eslint/no-explicit-any": "off", // 允许使用 any（可选，根据团队规范调整）
"no-unused-vars": ["error", { "varsIgnorePattern": "Vue" }], // 忽略 Vue 未使用警告
// Prettier 规则（将 Prettier 错误作为 ESLint 错误提示）
"prettier/prettier": "error"
}
},
// 集成推荐规则
pluginJs.configs.recommended,
...tseslint.configs.recommended,
...pluginVue.configs["flat/essential"],
...pluginVue.configs["flat/recommended"],
prettierConfig // 覆盖 ESLint 与 Prettier 冲突的规则
];
步骤 3：配置 Prettier（.prettierrc.js）
定义代码格式化规则，与 ESLint 规则兼容，统一团队代码风格。
module.exports = {
printWidth: 80, // 一行最多 80 字符
tabWidth: 2, // 2 个空格缩进（与 Vue 官方一致）
useTabs: false, // 不使用 Tab 缩进
semi: true, // 行尾添加分号
singleQuote: true, // 使用单引号
quoteProps: "as-needed", // 对象 key 仅必要时加引号
jsxSingleQuote: false, // JSX 中使用双引号
trailingComma: "all", // 对象/数组末尾添加逗号（便于 diff）
bracketSpacing: true, // 大括号内保留空格 { foo: bar }
jsxBracketSameLine: false, // JSX 闭合标签换行
arrowParens: "always", // 箭头函数单参数也加括号 (x) => x
endOfLine: "auto" // 自动适配系统换行符
};
步骤 4：配置 VS Code 自动格式化（.vscode/settings.json）
实现保存时自动修复 ESLint 错误并执行 Prettier 格式化，提升开发效率。
{
"eslint.enable": true,
"eslint.format.enable": true,
"editor.quickSuggestions": true,
"eslint.validate": ["javascript", "javascriptreact", "vue-html", "typescript", "html", "vue"],
"eslint.options": {
"extensions": [".js", ".jsx", ".ts", ".tsx", ".vue"]
},
"editor.formatOnSave": true, // 保存时格式化
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit" // 保存时自动修复 ESLint 错误
},
// 不同文件指定默认格式化工具
"editor.defaultFormatter": "esbenp.prettier-vscode",
"[vue]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
步骤 5：添加脚本命令
"scripts": {
// 新增 ESLint/Prettier 命令
"lint": "eslint "src/**/*.{js,ts,vue,tsx}" --fix", // 自动修复 ESLint 错误
"prettier": "prettier --write "src/**/*.{js,ts,vue,tsx,json,css}"" // 自动格式化
}
四、集成 Git 提交规范（Husky + Lint-Staged + CommitLint）
约束 Git 提交信息，在提交前校验代码规范，避免不合格代码入库，保障代码仓库整洁。
步骤 1：初始化 Git 仓库（若未初始化）
git init
步骤 2：安装依赖
# Husky（Git Hook 工具）、Lint-Staged（暂存区代码校验）
cnpm i husky@9.1.2 lint-staged@^15.2.7 -D
# CommitLint（提交信息校验）
cnpm i @commitlint/cli@^19.3.0 @commitlint/config-conventional@^19.2.2 -D
步骤 3：配置 Husky
# 生成 .husky 文件夹（存储 Git Hook 脚本）
npx husky init
# 手动创建 pre-commit（提交前校验）和 commit-msg（提交信息校验）脚本
touch .husky/pre-commit
touch .husky/commit-msg
步骤 4：编写 Hook 脚本
-
.husky/pre-commit（提交前校验暂存区代码）
#!/bin/sh `` . "$(dirname -- "$0")/_/husky.sh" ```` echo -e "\033[33m ------------- 正在校验暂存区代码规范 ---------------- \033[0m" ``npx --no-install lint-staged -
.husky/commit-msg（校验提交信息格式）
#!/bin/sh `` . "$(dirname -- "$0")/_/husky.sh" ```` echo -e "\033[33m ------------- 正在校验提交信息格式 ---------------- \033[0m" ``npx --no-install commitlint --edit "$1"
步骤 5：配置 Lint-Staged（package.json）
仅对暂存区代码执行校验和格式化，提升效率（避免全量校验）。
"lint-staged": {
"src/**/*.{vue,js,jsx,ts,tsx}": [
"eslint --fix", // 自动修复 ESLint 错误
"prettier --write" // 格式化代码
],
"src/**/*.{cjs,json,css}": [
"prettier --write" // 格式化配置文件和样式文件
]
}
步骤 6：配置 CommitLint（commitlint.config.cjs）
由于 package.json 默认为 ES 模块，需用 .cjs 后缀声明 CommonJS 格式。
module.exports = {
ignores: [commit => commit.includes('init')], // 忽略 init 初始化提交
extends: ['@commitlint/config-conventional'], // 基础规范
rules: {
'body-leading-blank': [2, 'always'], // 提交描述主体前空行
'footer-leading-blank': [1, 'always'], // 底部说明前空行
'header-max-length': [2, 'always', 108], // 标题最大长度 108
'subject-empty': [2, 'never'], // 标题不可为空
'type-empty': [2, 'never'], // 类型不可为空
'type-enum': [ // 允许的提交类型（规范提交场景）
2,
'always',
[
'wip', // 开发中
'feat', // 新增功能
'fix', // 修复 Bug
'test', // 测试相关
'refactor', // 代码重构
'build', // 构建配置（如依赖、打包）
'docs', // 文档更新
'perf', // 性能优化
'style', // 代码风格（不影响逻辑）
'ci', // 持续集成配置
'chore', // 琐事（如配置文件修改）
'revert', // 回滚代码
'types', // 类型声明更新
'release' // 版本发布
]
]
}
};
提交格式规范
git commit -m "<type>[optional scope]: <description>"
# 示例
git commit -m "feat[user]: 新增用户登录功能"
git commit -m "fix[api]: 修复用户列表接口跨域问题"
说明：type 为提交类型（必填），optional scope 为涉及模块（可选），description 为提交描述（必填，简洁明了）。
五、Vue3 专属插件集成（提升开发效率）
步骤 1：自动导入（API/组件）
无需手动导入 Vue 内置 API（如 ref、reactive）和全局组件，减少模板代码。
# 安装自动导入插件
cnpm i unplugin-auto-import unplugin-vue-components -D
# 若使用 UI 库（如 Ant Design Vue），需安装对应解析器
cnpm i unplugin-vue-components/resolvers -D
更新 build/vite.base.ts，添加插件配置：
import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'; // AntD Vue 解析器
export default defineConfig({
plugins: [
// ... 原有插件
// 自动导入 Vue API
AutoImport({
imports: ['vue', 'vue-router', 'pinia'], // 自动导入的库
dts: path.resolve(__dirname, '../src/auto-imports.d.ts'), // 生成类型声明文件
eslintrc: {
enabled: true // 生成 ESLint 配置，避免未导入警告
}
}),
// 自动导入组件
Components({
dirs: [path.resolve(__dirname, '../src/components')], // 自定义组件目录
extensions: ['vue', 'tsx'], // 组件后缀
dts: path.resolve(__dirname, '../src/components.d.ts'), // 生成组件类型声明
resolvers: [AntDesignVueResolver({ importStyle: false })], // UI 库组件自动导入
})
]
});
步骤 2：PX 转 REM（适配多端）
实现移动端自适应，将 PX 自动转为 REM，替代手动计算。
cnpm i postcss @minko-fe/postcss-pxtorem autoprefixer -D
根目录创建 postcss.config.js：
import pxtorem from '@minko-fe/postcss-pxtorem';
import autoprefixer from 'autoprefixer';
export default {
plugins: [
pxtorem({
rootValue: 16, // 基准值（1rem = 16px，可根据设计稿调整）
unitPrecision: 5, // 转换精度（保留 5 位小数）
propList: ['*'], // 所有属性都转换
selectorBlackList: ['no-rem'], // 类名含 no-rem 的不转换
atRules: ['media'], // 媒体查询中的 PX 也转换
exclude: /node_modules/ // 排除第三方库
}),
autoprefixer() // 自动添加 CSS 前缀（适配低版本浏览器）
]
};
步骤 3：SVG 组件化
将 SVG 图片转为 Vue 组件，支持按需引入和样式修改。
cnpm i vite-svg-loader -D
更新 build/vite.base.ts：
import svgLoader from 'vite-svg-loader';
export default defineConfig({
plugins: [
// ... 原有插件
svgLoader() // 解析 SVG 为 Vue 组件
]
});
使用方式：import Logo from '@/assets/logo.svg';，直接作为组件使用 <Logo />。
六、项目测试与验证
-
开发环境启动：
cnpm run dev，验证热更新、接口代理、自动导入是否正常。 -
类型校验：
cnpm run type-check，确保无 TS 类型错误。 -
代码规范校验：
cnpm run lint，自动修复格式错误。 -
生产环境打包：
cnpm run build:prod，验证打包产物是否正常，体积是否合理。 -
提交测试：修改代码后执行
git add .、git commit -m "test: 测试提交规范"，验证 Husky 校验是否生效。
七、总结
本指南构建了一套企业级 Vue3+Vite+TS 项目架构，核心亮点：
- 多环境配置拆分，环境隔离清晰，可快速扩展测试环境。
- 完整代码规范体系，从开发到提交全流程约束，保障代码质量。
- Vue3 专属插件集成，自动导入、自适应等功能提升开发效率。
- 配置结构清晰，build 文件夹集中管理配置，便于后期维护。
可根据项目需求扩展 Pinia（状态管理）、Vue Router（路由）、单元测试等功能，适配更复杂的业务场景。
