💡 本文将带你一步步从零搭建一个现代前端项目的工程化架构，涵盖代码规范、自动化检查、格式化、Git 提交校验等环节，让你的项目在团队协作中更稳健、更优雅。
🧭 为什么需要工程化？
现代前端开发早已不是“写个 HTML + JS”就能上线。随着项目复杂度提升，团队协作、代码质量、自动化流程成了必须解决的问题。
因此，一个合理的工程化架构通常要包含以下几个关键点：
- ✅ 模块化构建（Vite）
- ✅ 类型安全（TypeScript）
- ✅ 代码规范（ESLint）
- ✅ 统一格式（Prettier）
- ✅ 自动校验（Husky + lint-staged）
接下来，我们从零开始构建这一整套体系。
🧱 一、初始化项目
首先，我们使用 Vite 快速初始化一个 TypeScript 项目。
# 创建项目
npm create vite@latest my-project -- --template react-ts
cd my-project
# 安装依赖
npm install
此时项目结构大致如下：
my-project
├── src/
├── tsconfig.json
├── index.html
├── package.json
└── vite.config.ts
🧹 二、接入 ESLint：规范你的代码
安装 ESLint：
npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev
初始化 ESLint：
npx eslint --init
选择：
- 使用 TypeScript
- 模块化方式选择 ESM
- 框架选 React
- 风格指南选择 自定义
创建 .eslintrc.cjs：
module.exports = {
parser: '@typescript-eslint/parser',
extends: [
'eslint:recommended',
'plugin:@typescript-eslint/recommended',
'plugin:react-hooks/recommended'
],
plugins: ['@typescript-eslint'],
rules: {
'@typescript-eslint/no-explicit-any': 'off'
}
}
在 package.json 添加脚本：
"scripts": {
"lint": "eslint "src/**/*.{ts,tsx}""
}
✨ 三、接入 Prettier：统一代码风格
安装：
npm install prettier eslint-config-prettier eslint-plugin-prettier --save-dev
新增配置 .prettierrc.json：
{
"semi": false,
"singleQuote": true,
"printWidth": 100,
"trailingComma": "none"
}
在 .eslintrc.cjs 中扩展：
extends: [
'eslint:recommended',
'plugin:@typescript-eslint/recommended',
'plugin:react-hooks/recommended',
'plugin:prettier/recommended'
]
测试格式化：
npm run lint
npx prettier --write .
🔒 四、接入 Husky + lint-staged：提交前自动检查
安装依赖：
npm install husky lint-staged --save-dev
初始化 Husky：
npx husky install
npm set-script prepare "husky install"
npm run prepare
添加 pre-commit 钩子：
npx husky add .husky/pre-commit "npx lint-staged"
在 package.json 中配置 lint-staged：
"lint-staged": {
"src/**/*.{ts,tsx}": [
"eslint --fix",
"prettier --write"
]
}
现在，每次 git commit 前，都会自动运行代码检查与格式化，确保提交的代码符合规范。
🧪 五、可选增强：Commitlint + Commitizen（提交信息规范）
如果想进一步约束 commit message：
npm install @commitlint/{config-conventional,cli} commitizen cz-conventional-changelog --save-dev
配置 .commitlintrc.json：
{
"extends": ["@commitlint/config-conventional"]
}
添加 Husky 钩子：
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'
使用 Commitizen 提交：
npx cz
✅ 六、总结
至此，我们完成了一套现代前端工程化架构：
| 工具 | 作用 |
|---|---|
| Vite | 构建工具 |
| TypeScript | 类型安全 |
| ESLint | 代码规范 |
| Prettier | 格式统一 |
| Husky + lint-staged | 提交前自动化检查 |
| Commitlint（可选） | 提交信息规范 |
这套体系的核心目标是：
让代码有规范、格式有保障、提交有校验，团队协作更高效。
💡 拓展建议
- 使用 Vitest 集成单元测试
- 使用 GitHub Actions / GitLab CI 做持续集成
- 使用 Docker + PNPM 优化部署流程
🎯 结语
工程化的核心不在于工具多少，而在于流程闭环。
本文的搭建方式适合大多数中大型项目，能帮助团队建立一套可维护、可扩展、自动化的开发体验。
如果觉得有帮助，别忘了点赞 + 收藏，一起构建更优雅的前端工程化体系 🚀！
