老项目救星：Vue3/Vite/JS 项目渐进式引入「代码 + Commit」自动化规范全指南（多人协作）

好的，组长！以下是将您提供的详细操作方案进行格式规范化 后的内容。我将使用 Markdown 的标题、代码块、列表等特性，使其更具可读性和条理性，同时严格保持原有的内容和逻辑不变。

---

Vue3 + Vite + JS 老项目代码和提交规范引入方案

为您准备的这套方案核心思想是：渐进式引入，自动化保障，对现有代码侵入性降到最低，重点规范未来的代码。

总体目标

• 代码风格统一： 所有团队成员产出的代码格式保持一致。
• 代码质量保障： 在代码提交前自动检查潜在的语法错误和不合理写法。
• 提交信息规范： 统一 Git 提交信息的格式，便于追溯和自动化。
• 自动化流程： 将规范集成到 Git 工作流中，强制保障规范落地。

技术选型

规范类型	工具名称	作用描述
代码格式化	Prettier	强大的、高定制性的代码格式化工具。
代码质量检查	ESLint	JavaScript/Vue 代码的静态分析工具。
Git Hooks	Husky	轻松管理和使用 Git 钩子（如 pre-commit, commit-msg）。
暂存区文件检查	lint-staged	只对 Git 暂存区的文件执行检查和格式化，完美适配老项目。
Commit 规范	Commitlint + Commitizen	检查并辅助生成规范的 Git 提交信息。

---

详细操作方案

第一步：安装核心依赖

在项目根目录下打开终端，执行以下命令，将所有需要的工具安装为开发依赖：

Bash

npm install eslint prettier eslint-plugin-vue eslint-config-prettier husky lint-staged @commitlint/cli @commitlint/config-conventional commitizen -D

依赖说明：

• eslint, prettier: 核心工具。
• eslint-plugin-vue: ESLint 识别 .vue 文件语法规则的插件。
• eslint-config-prettier: 解决 ESLint 和 Prettier 的规则冲突。
• husky, lint-staged, @commitlint/cli, @commitlint/config-conventional, commitizen: Git 工作流自动化工具。

第二步：配置 ESLint (代码质量检查)

在项目根目录创建 .eslintrc.cjs 文件：

JavaScript

// .eslintrc.cjs
module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended', // 使用 Vue3 推荐规则，更严格
    'prettier', // 确保这个是 extends 数组的最后一项
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  plugins: [
    'vue',
  ],
  rules: {
    // 在这里可以自定义团队的规则，覆盖默认配置
    // 例如：强制使用单引号
    'quotes': ['error', 'single'],
    // 生产环境禁用 console.log
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    // 生产环境禁用 debugger
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    // 可以根据团队习惯添加更多规则...
    'vue/multi-word-component-names': 'off', // 暂时关闭组件名必须多单词的规则，老项目可能不满足
  },
};

第三步：配置 Prettier (代码格式化)

1. 创建 .prettierrc.json

在项目根目录创建 .prettierrc.json 文件：

JSON

// .prettierrc.json
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always",
  "bracketSpacing": true,
  "endOfLine": "auto"
}

2. 创建 .prettierignore

在项目根目录创建 .prettierignore 文件，告诉 Prettier 哪些文件不需要格式化：

Plaintext

# .prettierignore
/dist/*
.local
.output.js
/node_modules/**
**/*.svg
**/*.sh
/public/*

第四步：配置 Git Hooks (自动化核心)

1. 初始化 Husky

Bash

npx husky-init

此命令会在 package.json 中添加 prepare 脚本，并创建 .husky 目录。

2. 配置 lint-staged

打开 package.json 文件，添加如下配置。这是整个方案对老项目最友好的部分，因为它只处理你将要提交的文件。

JSON

// package.json (仅展示新增部分)
{
  // ... 其他配置
  "lint-staged": {
    "*.{js,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{html,css,scss,md}": [
      "prettier --write"
    ]
  }
}

3. 修改 pre-commit 钩子

将 .husky/pre-commit 文件的内容修改为：

Bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

现在，每当有成员执行 git commit 时，lint-staged 就会自动对暂存区的文件执行 ESLint 修复和 Prettier 格式化，不通过则无法提交。

第五步：配置 Commitlint (提交信息规范)

1. 创建 commitlint.config.js

在项目根目录创建 commitlint.config.js 文件：

JavaScript

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // 在这里可以自定义规则
    // 例如：type 类型范围
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // 修复bug
        'docs',     // 文档变更
        'style',    // 代码格式（不影响代码运行的变动）
        'refactor', // 重构（既不是增加feature，也不是修复bug）
        'perf',     // 性能优化
        'test',     // 增加测试
        'chore',    // 构建过程或辅助工具的变动
        'revert',   // 回退
        'build',    // 打包
      ],
    ],
  },
};

2. 添加 commit-msg 钩子

执行以下命令，让 Husky 在 commit-msg 阶段调用 commitlint：

Bash

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

现在，如果不符合规范的 commit message，提交将会失败。

3. 引入 Commitizen (推荐)

为了让团队成员更方便地写出规范的 commit message，我们使用 commitizen。

• 初始化 commitizen:

  Bash

  npx commitizen init @commitlint/cz-commitlint --save-dev --save-exact

• 在 package.json 中添加一个脚本:

  JSON

  // package.json (仅展示新增部分)
  {
    "scripts": {
      // ...
      "commit": "cz"
    }
  }

通知团队成员：以后提交代码时，不要再用 git commit -m "..."，而是使用 npm run commit。终端会以交互式问答的方式引导你生成一条规范的 commit message。

第六步：IDE 集成与团队推广

1. 统一 VS Code 配置

确保团队成员都安装了 ESLint 和 Prettier - Code Formatter 这两个 VS Code 插件。

在项目根目录创建 .vscode/settings.json 文件，并提交到 Git 仓库：

JSON

// .vscode/settings.json
{
  "editor.formatOnSave": true, // 开启保存时自动格式化
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit" // 开启保存时自动执行 ESLint 修复
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode", // 设置 Prettier 为默认格式化器
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

这样，成员在开发时保存文件，代码就会被自动格式化和修复，体验极佳。

2. 团队宣讲与文档

• 组织一次简短会议，解释规范的目的、好处和使用方法。
• 重点演示 npm run commit 的使用。
• 将关键步骤和命令写成一个简单的 CONTRIBUTING.md 文档，放在项目根目录。

---

总结与落地

至此，一套完整的、自动化的前端工程化规范就搭建完成了。

给团队成员的最终指引：

1. 克隆/拉取最新代码后，执行 npm install 安装所有依赖。
2. 如果使用 VS Code，请安装推荐的插件（ESLint, Prettier）。
3. 正常进行代码开发，Ctrl+S 保存时代码会自动格式化和修复。
4. 开发完成后，使用 git add . 添加文件。
5. 使用 npm run commit 命令提交代码，根据提示完成提交。
6. git push 推送代码。

这套方案的最大优点是，它通过工具强制保证了规范的下限，同时通过 IDE 插件和交互式命令提升了开发的上限体验。对于老项目，它只关心新增和修改的部分，不会造成巨大的历史包袱。祝您和您的团队协作愉快！