网站导航
> 技术文档 > vite+vue3+typescript的项目配置eslint+oxlint+husky+lint-staged+commitlint+commitizen+cz-git完成前端工程化配置

vite+vue3+typescript的项目配置eslint+oxlint+husky+lint-staged+commitlint+commitizen+cz-git完成前端工程化配置

网友: 技术文档 2025-07-30 11:58:04

1. 项目初始化

使用vite命令选择对应的模板来初始化项目

pnpm create vite vue3-ts-project --template vue-ts

2. 安装eslint、oxlint和@antfu/eslint-config来对项目代码做语法检测和代码风格的格式化

eslint的作用是什么？

ESLint 通过解析 JavaScript/TypeScript 代码为 AST（抽象语法树），对代码风格、潜在错误（如未声明变量、未使用参数）等进行检测的工具，可以通过在配置文件中自定义各种检验规则。

oxlint是什么？跟eslint之间有什么关系？

Oxlint 是一款基于 Rust 开发的 JavaScript/TypeScript 代码检查工具（Linter），由尤雨溪创立的 Void(0) 公司旗下的 ​OXC 工具链项目推出。它旨在通过高性能和更直观的代码诊断能力提升开发效率，与 ESLint 存在互补与竞争关系。

推荐使用场景：在 CI/CD 或 lint-staged 中 ​先运行 Oxlint 快速拦截 90% 的常见问题，再运行 ESLint 处理复杂规则。例如，尤雨溪在 Vue 3 项目中用 Oxlint 检查 590 个文件仅需 30-50ms。

@antfu/eslint-config是什么？

一站式代码风格管理配置

项目地址:https://gitcode.com/gh_mirrors/es/eslint-config

项目介绍

@antfu/eslint-config 是由知名开发者Anthony Fu开发的一款ESLint配置包。它不仅支持TypeScript、JSX、Vue等多种前端技术栈，还提供了丰富的自定义选项，使得开发者可以根据项目需求灵活调整代码风格。

核心特性
自动格式化修复：无需Prettier，即可实现代码格式化的自动修复。
简洁的配置：仅需一行配置，即可启用合理的默认设置和最佳实践。
广泛的文件支持：支持TypeScript、JSX、Vue、JSON、YAML、Toml、Markdown等多种文件格式。
高度可定制：虽然配置是意见化的，但提供了丰富的自定义选项。
ESLint Flat Config：采用ESLint的新Flat配置格式，便于组合和扩展。

技术栈支持
React、Svelte、UnoCSS、Astro、Solid：可选支持这些流行的前端框架和工具。
格式化工具：支持CSS、HTML、XML等文件的格式化。

代码风格原则
最小化阅读障碍：排序导入、悬挂逗号等。
稳定性和一致性：单引号、无分号等。
使用ESLint Stylistic：确保代码风格的一致性。

安装eslint、oxlint和@antfu/eslint-config

pnpm add eslint oxlint @antfu/eslint-config -D

在项目的根目录创建eslint.config.js配置文件并添加自定义配置

import antfu from \'@antfu/eslint-config\'export default antfu({ vue: { \'vue/block-order\': [\'error\', { // 块顺序 order: [\'script\', \'template\', \'style\'], }], }, typescript: true, stylistic: { indent: 2, // 缩进 semi: false, // 语句分号 quotes: \'single\', // 单引号 }, rules: { \'new-cap\': [\'off\', { newIsCap: true, capIsNew: false }], \'no-console\': \'off\', // 忽略console }, ignores: [ \'dist/**\', \'node_modules/**\', \'**/types/**\', \'public/**\', \'vite.config.ts\', \'eslint.config.js\', ],})

在package.json中添加检验命令

{ \"scripts\": { \"lint\": \"oxlint . --fix && eslint . --fix\", }}

给vscode编辑器并安装eslint插件，在项目根目录的.vscode/setting.json配置文件添加代码格式化相关的配置

{ // 开启扁平化配置 \"eslint.useFlatConfig\": true, // 关闭默认的配置，我们这里默认不开启prettier格式化 \"prettier.enable\": false, // 关闭默认格式化 \"editor.formatOnSave\": false, // 保存自动修复 \"editor.codeActionsOnSave\": { // 我们这里是指定自定义的修复 \"source.fixAll.eslint\": \"explicit\", // 来源导入我们不需要给关闭掉 \"source.organizeImports\": \"never\", // 使用 stylelint 来修复样式问题 \"source.fixAll.stylelint\": \"explicit\", \"source.fixAll.oxc\": \"always\" }, // 静默样式规则自动修复 \"eslint.rules.customizations\": [ { \"rule\": \"style/*\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"format/*\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-indent\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-spacing\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-spaces\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-order\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-dangle\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*-newline\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*quotes\", \"severity\": \"off\", \"fixable\": true }, { \"rule\": \"*semi\", \"severity\": \"off\", \"fixable\": true } ], // 在eslin中开启哪些语言的校验 \"eslint.validate\": [ \"javascript\", \"javascriptreact\", \"typescript\", \"typescriptreact\", \"\", \"html\", \"markdown\", \"json\", \"jsonc\", \"yaml\", \"toml\", \"xml\", \"gql\", \"graphql\", \"astro\", \"css\", \"less\", \"scss\", \"pcss\", \"postcss\" ], \"oxc.enable\": true, \"cSpell.words\": [ \"aeac\", \"esno\", \"radash\", \"unplugin\" ]}

3. 使用husky、lint-staged来对提交的代码进行检查和格式化

husky是什么？有什么用？

Husky 是一款基于 Node.js 的 Git 钩子（Git Hooks）管理工具，用于在代码提交或推送前自动化执行脚本，例如代码检查、测试等。

核心功能与用途：

  1. ​代码质量保障
    • 在 git commit 前触发 pre-commit 钩子，运行 ESLint、Prettier 等工具检查代码规范，阻止不符合规则的提交。
    • 示例：通过 lint-staged 仅检查暂存区文件，避免全量扫描耗时问题。
  2. ​提交信息规范
    • 在 git commit 时触发 commit-msg 钩子，使用 Commitlint 校验提交信息格式（如遵循 Conventional Commits 规范）。
    • 示例：强制要求提交信息以 feat:、fix: 等前缀开头。
  3. ​自动化流程集成
    • 与构建工具（Webpack、Rollup）和 CI/CD 管道结合，确保部署前代码质量。
    • 支持自定义脚本，例如在 pre-push 钩子中运行单元测试。

lint-staged是什么？有什么作用？

lint-staged 是一款专注于 Git 暂存区（staged files）的代码质量检查工具，通过自动化执行代码规范检查和格式化，保障提交到仓库的代码符合团队标准。其核心作用在于 ​提升开发效率 和 ​保障代码质量。

lint-staged 的核心功能

  1. ​精准检查暂存区文件
    仅对 git add 添加至暂存区的文件执行检查，避免全量扫描整个项目，极大减少计算量，尤其适合大型项目。

  2. ​自动化修复与提交整合
    支持与 ESLint、Prettier、Stylelint 等工具结合，在检查后自动修复可纠正的问题（如代码缩进、引号格式），并通过 git add 将修复后的文件重新加入暂存区，确保修复生效。

具体操作与配置

安装husky与lint-staged

pnpm add husky lint-staged -D

初始化git仓库

git init

初始化husky

npx husky init

这将在项目根目录下创建.husky 文件夹，并在 package.json 中添加 prepare 脚本

添加 pre-commit 钩子

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

添加lint-staged.config.cjs配置文件进行配置

module.exports = { \"lint-staged\": { // 匹配 JavaScript/TypeScript/Vue 等文件 \"**/*.{js,jsx,ts,tsx,vue,html,css,less}\": [ \"eslint --fix\" // 自动修复 ESLint 错误 ] }}

4. 使用husky+commitlint+commitizen+cz-git来规范提交信息

commitlint、commitizen、cz-git这三个插件的作用分别是什么？看看deepseek的总结

以下是 **commitlint**、**commitizen** 和 **cz-git** 三个工具的核心作用与区别解析：

一、Commitlint：提交信息规范校验器
**作用**：  
Commitlint 是一个静态检查工具，用于验证 Git 提交信息是否符合预定义的格式规范（如 [Conventional Commits](https://www.conventionalcommits.org/)）。  
- **核心功能**：  
  - 在 `commit-msg` 钩子中自动拦截不符合规范的提交信息，阻止其进入仓库。  
  - 支持自定义规则，例如限制提交类型（`feat`/`fix`/`docs` 等）、标题长度（默认 72 字符）、正文格式等。  
  - 与 Husky 集成，实现提交前的自动化校验。  

**典型场景**：  
团队通过 `commitlint.config.js` 定义规范，确保所有提交信息风格统一，便于生成自动化变更日志（CHANGELOG）。

二、Commitizen：交互式提交信息生成器
**作用**：  
Commitizen 是一个命令行工具，通过交互式问答引导开发者生成符合规范的提交信息，降低手动输入错误的风险。  
- **核心功能**：  
  - 提供交互式 CLI 界面，逐步选择提交类型、作用域（Scope）、描述等。  
  - 支持预设规则集（如 `cz-conventional-changelog`），默认遵循 Angular 提交规范。  
  - 通过 `git cz` 命令替代原生 `git commit`，简化规范提交流程。  

**典型场景**：  
开发者无需记忆格式，通过选择菜单快速生成如 `feat(button): add hover effect` 的标准提交信息。

---

三、cz-git：Commitizen 的增强适配器
**作用**：  
cz-git 是 Commitizen 的高级适配器（Adapter），在保留规范生成能力的基础上，提供更灵活的定制和交互体验。  
- **核心功能**：  
  - **智能搜索与选择**：支持模糊搜索提交类型和作用域，减少手动输入（例如输入 `fe` 快速匹配 `feat`）。  
  - **高度可定制**：允许自定义提交模板、Emoji 支持、作用域动态加载（如自动读取 Monorepo 子包列表）。  
  - **AI 集成**：可选 OpenAI 自动生成提交描述，提升效率。  
  - **与 Commitlint 联动**：在校验失败时直接在 CLI 中显示错误提示，快速修正。  

**典型场景**：  
在大型 Monorepo 项目中，cz-git 可动态加载子包作为作用域选项，并通过 AI 辅助生成复杂的提交正文。

---

四、三者的协同关系
1. **工作流程**：  
   - **Commitizen/cz-git** → 生成规范提交信息 → **Commitlint** → 校验信息合法性 → 提交成功/失败。  
2. **工具定位**：  
   - **Commitizen** 是生成工具，**cz-git** 是其功能扩展；  
   - **Commitlint** 是校验工具，确保生成的提交信息符合团队规范。  
3. **推荐组合**：  
   - 中小项目：Commitizen + `cz-conventional-changelog` + Commitlint。  
   - 复杂项目：cz-git（增强交互） + Commitlint（严格校验）。

具体操作

安装commitlint和默认规则合集，还有commitizen和cz-git

pnpm add commitlint @commitlint/config-conventional commitizen cz-git -D

添加.commitlintrc.cjs配置文件

// .commitlintrc.js/** @type {import(\'cz-git\').UserConfig} */module.exports = { extends: [\'@commitlint/config-conventional\'], rules: { // @see: https://commitlint.js.org/#/reference-rules \'type-enum\': [ 2, \'always\', [ \'build\', \'chore\', \'ci\', \'docs\', \'feat\', \'fix\', \'perf\', \'refactor\', \'revert\', \'style\', \'test\', ], ], }, prompt: { alias: { fd: \'docs: fix typos\' }, messages: { type: \'选择你要提交的类型 | Select the type of change that you\\\'re committing:\', scope: \'选择一个提交范围（可选）| Denote the SCOPE of this change (optional):\', customScope: \'请输入自定义的提交范围 | Denote the SCOPE of this change:\', subject: \'填写简短精炼的变更描述 | Write a SHORT, IMPERATIVE tense description of the change:\\n\', body: \'填写更加详细的变更描述（可选）。使用 \"|\" 换行 | Provide a LONGER description of the change (optional). Use \"|\" to break new line:\\n\', breaking: \'列举非兼容性重大的变更（可选）。使用 \"|\" 换行 | List any BREAKING CHANGES (optional). Use \"|\" to break new line:\\n\', footerPrefixesSelect: \'选择关联issue前缀（可选）| Select the ISSUES type of changeList by this change (optional):\', customFooterPrefix: \'输入自定义issue前缀 | Input ISSUES prefix:\', footer: \'列举关联issue (可选) 例如: #31, #I3244 | List any ISSUES by this change. E.g.: #31, #34:\\n\', confirmCommit: \'是否提交或修改commit ? | Are you sure you want to proceed with the commit above?\', }, types: [ { value: \'feat\', name: \'feat: 新增功能 | A new feature\' }, { value: \'fix\', name: \'fix: 修复缺陷 | A bug fix\' }, { value: \'docs\', name: \'docs: 文档更新 | Documentation only changes\', }, { value: \'style\', name: \'style: 代码格式 | Changes that do not affect the meaning of the code\', }, { value: \'refactor\', name: \'refactor: 代码重构 | A code change that neither fixes a bug nor adds a feature\', }, { value: \'perf\', name: \'perf: 性能提升 | A code change that improves performance\', }, { value: \'test\', name: \'test: 测试相关 | Adding missing tests or correcting existing tests\', }, { value: \'build\', name: \'build: 构建相关 | Changes that affect the build system or external dependencies\', }, { value: \'ci\', name: \'ci: 持续集成 | Changes to our CI configuration files and scripts\', }, { value: \'revert\', name: \'revert: 回退代码 | Revert to a commit\' }, { value: \'chore\', name: \'chore: 其他修改 | Other changes that do not modify src or test files\', }, ], useEmoji: false, emojiAlign: \'center\', useAI: false, aiNumber: 1, themeColorCode: \'\', scopes: [], allowCustomScopes: true, allowEmptyScopes: true, customScopesAlign: \'bottom\', customScopesAlias: \'custom\', emptyScopesAlias: \'empty\', upperCaseSubject: false, markBreakingChangeMode: false, allowBreakingChanges: [\'feat\', \'fix\'], breaklineNumber: 100, breaklineChar: \'|\', skipQuestions: [], issuePrefixes: [ // 如果使用 gitee 作为开发管理 { value: \'link\', name: \'link: 链接 ISSUES 进行中\' }, { value: \'closed\', name: \'closed: 标记 ISSUES 已完成\' }, ], customIssuePrefixAlign: \'top\', emptyIssuePrefixAlias: \'skip\', customIssuePrefixAlias: \'custom\', allowCustomIssuePrefix: true, allowEmptyIssuePrefix: true, confirmColorize: true, scopeOverrides: undefined, defaultBody: \'\', defaultIssues: \'\', defaultScope: \'\', defaultSubject: \'\', },}

添加husky钩子的commit-msg

npx husky add .husky/commit-msg \"npx commitlint --config .commitlintrc.cjs --color --edit \"$1\"\"

在package.json中添加提交命令脚本和cz-git适配器

{ \"scripts\": { \"commit\": \"git-cz\" }, \"config\": { \"commitizen\": { \"path\": \"node_modules/cz-git\" } }}

以上就是基于vite来实现项目代码规范约束配置的全部内容。

网络标签：

相关问题