Vue3项目工程化配置：husky+lintstaged+commitlin+commitizen + cz-git

配置 husky + lintstaged + commitlint+ cz-git + conventional-changelog-li。

• husky：管理git钩子 文档
• lintstaged：定义暂存的文件的校验规则 文档
• commitlint: 规范格式化git提交信息 文档
• cz-git: 自定义的commitlint适配器 文档
• conventional-changelog-li： 从git元数据生成变更日志 文档

Husky

husky是一个流行的用于配置 Git 钩子的工具。 可以在Git提交或推送时，自动化 检查提交信息、检查代码 和 运行测试。

安装与使用

1. 安装husky

npm install --save-dev husky

2. 初始化 husky
husky init 命令简化了项目中的 husky 设置。它会在 .husky/ 中创建 pre-commit 脚本，并更新 package.json 中的 prepare 脚本。随后可根据你的工作流进行修改。

npx husky init

3. 运行 git commit 测试一下：

git commit -m "Keep calm and commit"
# 测试脚本会在每次提交时运行

添加新 Hook
添加 hook 与创建文件一样简单。可以通过你喜欢的编辑器、脚本或 echo 命令来实现。例如，在 Linux/macOS 中：

echo "npm test" > .husky/pre-commit

lint-staged

对已暂存的Git文件运行格式化器和代码检查工具，不要让垃圾代码混入你的代码库！

1. 安装lint-staged

npm install --save-dev lint-staged

2. 设置预提交的git钩子以运行lint-staged

echo "npx lint-staged" > .husky/pre-commit

3. 安装校验工具和格式化工具(具体配置不在这里展开说明)

npm install --save-dev eslint prettier stylelint

• eslint： 语法校验
• prettier：代码格式化
• stylelint : css代码检查

4. 配置 lint-staged 以运行代码检查器和其他任务
   在根目录新建配置文件 .lintstagedrc.json

{
  "src/**/*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"],
  "src/**/((?!iconfont.css|*.min.css|demo.css)(*.{vue,css,less,scss,sass}))": [
    "stylelint --allow-empty-input",
    "prettier --write"
  ],
  "*.{json,md}": ["prettier --write"]
}

5. 使用

git commit -m "XXX"

commitlint

对提交信息进行代码审查有助于你的团队遵守提交规范。

1. 安装
   安装 @commitlint/cli 和你选择的 @commitlint/config-* / commitlint-config-* 作为开发依赖，并配置 commitlint 使用它。

npm install -D @commitlint/cli @commitlint/config-conventional

2. 添加配置文件commitlint.config.js

echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

3. 使用 Husky 的 commit-msg 钩子进行代码检查。
   通过在撰写提交信息时进行代码检查，可以获得高质量的提交信息和快速反馈周期。

echo "npx --no -- commitlint --edit `$1" > .husky/commit-msg

4. 使用

git commit -m "feat: XXX"

报错处理：

报错1：

.husky/commit-msg: .husky/commit-msg: cannot execute binary file
husky - commit-msg script failed (code 126)

解决：编码问题，.husky/commit-msg 默认是utf-16； 在vscode底部将文件编码改成utf-8

报错2：

file:///D:/Vue3/vue-spa-project/node_modules/@commitlint/cli/lib/cli.js:132
throw err;
Error [ERR_INTERNAL_ASSERTION]: Cannot require() ES Module D:\Vue3\vue-spa-project\commitlint.config.js because it is not yet fully loaded. This may be caused by a race condition if the module is simultaneously dynamically
import()-ed via Promise.all(). Try await-ing the import() sequentially in a loop instead. (from D:\Vue3\vue-spa-project\node_modules\cosmiconfig\dist\loaders.js)
This is caused by either a bug in Node.js or incorrect usage of Node.js internals.

解决：也是编码问题，将 commitlint.config.js 的编码改成utf-8

Commitizen

当你使用Commitizen进行提交时，将会进入一个交互式的Commitizen会话，系统会提示你填写任何所需的提交字段。

1. 安装 commitizen

npm install --save-dev commitizen

2. 我们将设置我们的仓库以使用AngularJS的提交信息约定，也称为 conventional-changelog。
   初始化您的项目以使用cz-conventional-changelog适配器:

npx commitizen init cz-conventional-changelog --save-dev --save-exact --force

上述命令为您做了三件事：

• 安装了 cz-conventional-changelog 适配器 npm 模块
• 将其保存到 package.json 的 dependencies 或 devDependencies 中
• 在您的 package.json 文件的根部添加了 config.commitizen 键，如下所示：

"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

或者，Commitizen 配置也可以添加到 .czrc 文件中。

{
  "path": "cz-conventional-changelog"
}

这仅仅告诉Commitizen，我们希望我们的贡献者在尝试向这个仓库提交代码时实际使用哪个适配器。

3. 使用命令行工具 git cz 或者 cz 代替 git commit 提交代码。 也可以使用 cz 的别名 git-cz。
   在使用npm版本5.2或更高版本时，你可以选择使用npx。

npx cz

或者 添加一个npm脚本， 只需运行npm run c

 "scripts": {
    "c": "cz"
  }

注意： 如果你使用了类似husky的预提交钩子，你需要将你的脚本命名为其他名称（例如“cm”: “cz” 或者 "c": "cz"）。原因是npm脚本有一个特性，它会自动运行名为prexxx的脚本，其中xxx是另一个脚本的名称。换句话说，如果脚本名称为“commit”，npm和husky将会运行两次预提交脚本，解决方法是防止npm触发的预提交脚本。

cz-git

一款工程性更强，轻量级，高度自定义，标准输出格式的 commitizen 适配器。文档

1. 安装

npm install -D cz-git

2. 修改 package.json 添加 config 指定使用的适配器

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-git"
    }
  }
}

3. (可选，使用默认) 添加自定义配置
   有两种配置方式:
   1） (推荐) cz-git 与 commitlint 进行联动给予校验信息，所以可以编写于 commitlint 配置文件之中。
   例如: (⇒ 配置模板)

/** @type { import('cz-git').UserConfig } */
export default {
  rules: {
    // @see: https://commitlint.js.org/#/reference-rules
    // type的类型定义：表示 git 提交的 type 必须在以下类型范围之内
    'type-enum': [
      2, // 代表必须输入
      'always', // 在什么情况下进行验证
      [
        'docs', // Adds or alters documentation. 仅仅修改了文档，比如README, CHANGELOG, CONTRIBUTE等等
        'ci', // Other changes that don't modify src or test files. 改变构建流程、或者增加依赖库、工具等
        'chore', // 改变构建流程、或者增加依赖库、工具等
        'feat', // Adds a new feature. 新增feature
        'fix', // Solves a bug. 修复bug
        // 'merge', // Merge branch ? of ?.
        'perf', // Improves performance. 优化相关，比如提升性能、体验
        'refactor', // Rewrites code without feature, performance or bug changes. 代码重构，没有加新功能或者修复bug
        'revert', // Reverts a previous commit. 回滚到上一个版本
        'style', // Improves formatting, white-space. 仅仅修改了空格、格式缩进、都好等等，不改变代码逻辑
        'test', // Adds or modifies tests. 测试用例，包括单元测试、集成测试等
        'build', // 改变了build工具 如 grunt换成了 npm
        // 'wip', // Work In Process 正在进行的工作
        // 'rfr', // Ready For Review 代码开发完毕，可以检视合入
      ],
    ],
  },
  prompt: {
    // alias: { fd: 'docs: fix typos' },
    messages: {
      type: '选择你要提交的类型 :',
      scope: '选择一个提交范围（可选）:',
      customScope: '请输入自定义的提交范围 :',
      subject: '填写简短精炼的变更描述 :\n',
      body: '填写更加详细的变更描述（可选）。使用 "|" 换行 :\n',
      breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行 :\n',
      footerPrefixesSelect: '选择关联issue前缀（可选）:',
      customFooterPrefix: '输入自定义issue前缀 :',
      footer: '列举关联issue (可选) 例如: #31, #I3244 :\n',
      confirmCommit: '是否提交或修改commit ?',
    },
    types: [
      { value: 'feat', name: 'feat:     ✨  新增功能 | A new feature', emoji: ':sparkles:' },
      { value: 'fix', name: 'fix:      🐛  修复缺陷 | A bug fix', emoji: ':bug:' },
      {
        value: 'docs',
        name: 'docs:     📝  文档更新 | Documentation only changes',
        emoji: ':memo:',
      },
      {
        value: 'style',
        name: 'style:    💄  代码格式 | Changes that do not affect the meaning of the code',
        emoji: ':lipstick:',
      },
      {
        value: 'refactor',
        name: 'refactor: ♻️   代码重构 | A code change that neither fixes a bug nor adds a feature',
        emoji: ':recycle:',
      },
      {
        value: 'perf',
        name: 'perf:     ⚡️  性能提升 | A code change that improves performance',
        emoji: ':zap:',
      },
      {
        value: 'test',
        name: 'test:     ✅  测试相关 | Adding missing tests or correcting existing tests',
        emoji: ':white_check_mark:',
      },
      {
        value: 'build',
        name: 'build:    📦️  构建相关 | Changes that affect the build system or external dependencies',
        emoji: ':package:',
      },
      {
        value: 'ci',
        name: 'ci:    🎡  持续集成 | Changes to our CI configuration files and scripts',
        emoji: ':ferris_wheel:',
      },
      {
        value: 'chore',
        name: "chore:    🔨  其他修改 | Other changes that don't modify src or test files",
        emoji: ':hammer:',
      },
      {
        value: 'revert',
        name: 'revert:   ⏪️  回退代码 | Reverts a previous commit',
        emoji: ':rewind:',
      },
    ],
    useEmoji: true,
    emojiAlign: 'center',
    useAI: false,
    aiNumber: 1,
    themeColorCode: '',
    scopes: [
      'components',
      'directives',
      'utils',
      'plugins',
      'packages',
      'filters',
      'views',
      'service',
      'pinia',
      'router',
      'filters',
      'scripts',
      'other',
    ],
    allowCustomScopes: true,
    allowEmptyScopes: true,
    customScopesAlign: 'bottom',
    customScopesAlias: 'custom',
    emptyScopesAlias: 'empty',
    upperCaseSubject: null,
    markBreakingChangeMode: false,
    allowBreakingChanges: ['feat', 'fix'],
    breaklineNumber: 100,
    breaklineChar: '|',
    skipQuestions: ['body', 'breaking', 'footerPrefixesSelect', 'customFooterPrefix', 'footer'],
    issuePrefixes: [{ value: 'closed', name: 'closed:   ISSUES has been processed' }],
    // 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: '',
  },
}

2)在 package.json 下 config.commitizen 下添加自定义配置，但过量的配置项会导致 package.json 臃肿，适合简单自定义。例如:

{
  "scripts": {
    "c": "cz"
  },
  "config": {
    "commitizen": {
      "path": "node_modules/cz-git",
      "useEmoji": true
    }
  }
}

4. 使用

npm run c

conventional-changelog

从git元数据生成变更日志 参考文档

安装使用

1. 安装

npm i --save-d conventional-changelog-cli

2. 根目录创建CHANGELOG.md文件，并在package.json中添加脚本

 "scripts": {
    "changelog":"conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
  },   

conventional-changelog 常用选项：

• -i：读取 CHANGELOG.md 的输入文件。
• -o：输出文件。
• -p：预置名称，基本都会使用 angular 规范标准。
• -u：代表未归入版本（unrelease）的日志。
• -r：代表输出几个版本，0 则代表输出所有并覆盖输出文件。
• -s：代表输出与输入为相同文件。

3. 运行脚本生成CHANGELOG.md

npm run changelog

推荐工作流程：

1. Make changes：做出变更；
2. Commit those changes：提交变更；
3. Make sure Travis turns green： 确保CI构建成功
4. Bump version in package.json：修改 package.json 中的版本号；
5. conventionalChangelog： 使用脚本生成CHANGELOG.md；
6. Commit package.json and CHANGELOG.md files：提交package.json和CHANGELOG.md文件；
7. Tag： 打标签；
8. Push：推送提交；