编程规范基本解决方案一、编程规范 1.1 为什么需要编程规范大型项目需要团队开发但是团队中的成员对技术的理解各不相同

写这篇文章的原因是公司新来的大二实习小伙伴，做这个任务的时候以直报怨说网上的方案千篇一律，没有能够完整通下来的，总是会遇到各种各样的问题。所以打算试一试，看看是否如其所说。所以，本文对比其它也没有什么不同，唯一不同的是针对一些特殊的问题，做了一些说明。总结小伙伴的原因，基本就是：网上的文章都是很久以前的，当时各个依赖版本低，现在安装高版本会有一些差异化。另外需要注意的是，本篇文章知识记录几个工具的基本使用方式，公司项目会有更复杂且个性化的配置，再此不赘述。

一、编程规范

1.1 为什么需要编程规范

大型项目需要团队开发
但是团队中的成员对技术的理解各不相同，编码风格各不相同
一个项目如果没有统一的规范，就像是拼接起来的补丁，项目代码混乱
项目可读性大大提升

1.2 代码检测工具ESlint

2013年6月创建的开源项目
提供一个插件化的代码检查工具

1.3 代码格式化工具Prettier

代码格式化工具
开箱即用
直接集成到VSCode
保存时即可让代码直接符合ESlint

1.4 Prettier的使用

插件系统直接搜索点击安装

安装后创建配置文件

找到编辑器的设置

这样就可以直接使用啦
如果不好用请检查一下默认的格式化方式是不是prettier 编辑器内右键如下

1.4 git提交规范

方便排查问题、定位问题
项目管理（分支、tag）
支持持续集成和部署流程
规范地址

1.5 commitizen规范化提交代码

全局安装

npm install -g commitizen

安装cz-customizable插件

npm i cz-customizable -D -S

添加配置到package.json中

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

在项目根目录下创建.cz-config.js文件，自定义提示内容

module.exports = {
  // 可选类型
  types: [
    { value: 'feat', name: 'feat: 新功能' },
    { value: 'fix', name: 'fix: 修复' },
    { value: 'docs', name: 'docs: 文档' },
    { value: 'style', name: 'style: 样式' },
    { value: 'refactor', name: 'refactor: 重构' },
    { value: 'perf', name: 'perf: 性能优化' },
    { value: 'test', name: 'test: 测试' },
    { value: 'chore', name: 'chore: 构建' },
    { value: 'revert', name: 'revert: 回退' }
  ],
  // 步骤
  messages: {
    type: '选择一种你的提交类型:',
    customScope: '请输入修改范围(可选):',
    subject: '请简要描述提交(必填):',
    body: '请输入详细描述(可选):',
    footer: '请输入关联的issue(可选):',
    confirmCommit: '确定要使用以上信息提交吗？(y/n)'
  },
  //subject长度限制
  subjectLimit: 100
  // 跳过步骤
  // skipQuestions: ['body', 'footer']
}

需要注意的是最新版本中customScope这一步会被跳过，如需要请使用v6.9.0及之前版本，该问题这个库作者一直未修复，社区内很多pr也未被合并。具体情况为何如此暂不可知。具体解决办法可以参照社区修改部署到自己公司的私服上使用

1.6 git hooks

也就是git的钩子或者说是git的回调，类似于vue的生命周期
在执行某个事件之前或之后做一些额外的操作
我们最常用的就是两个钩子
- pre-commit
  - git commit执行前，不接受任何参数
  - 在获取提交消息并执行前调用
  - 以非零状态退出会导致命令在创建前中止
- commit-msg
  - git commit 执行前
  - 可以用于将消息规范化为某种项目标准格式
  - 检查文件消息后拒绝提交

1.7 使用husky+commitlint检查提交是否符合规范

npm必须在7.x版本以上

npm -v检查npm版本

安装依赖

npm i --save-dev @commitlint/config-conventional @commitlint/cli

创建commitlint.config.js
并增加如下代码

module.exports = {
  extends: ['@commitlint/config-conventional']
}

自定义规则

module.exports = {
  // 继承的规则
  extends: ['@commitlint/config-conventional'],
  // 自定义规则
  rules: {
    // type的类型定义，表示type的类型必须在以下范围之内，2表示警告，always表示必须遵守
    'type-enum': [
      2, //错误级别
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'revert'
      ]
    ],
    // subject大小写不做校验
    'subject-case': [0, 'never']
  }
}

需要注意的是这个文件必须是utf-8的编码格式，否则会导致报错

综上commitlint的工作完成了下面要进行husky的安装配置了
安装依赖

接下来就是安装husky了

安装依赖

npm install husky -D-S

启动hooks 生成.husky文件夹

npm set-script prepare "husky install"

注意上述方式可能在高版本的npm下无效，我们可以直接在package.json中添加代码

或者执行以下命令

npm pkg set scripts.prepare="husky install"

启动命令

我们会发现提示husky - install command is DEPRECATED（husky - install命令已弃用）

这是因为我们使用了高版本的husky，要解决这个问题我们有两种办法，一种是降低版本到7.x 另一种就是使用高版本方式，也就是我们在安装完husky依赖之后直接跳到这一步

初始化husky,生成如图

npx husky init

生成commit-msg文件

echo “npx --no – commitlint --edit $1” > .husky/commit-msg

此时我们git commit -m "xxx" 提交代码会报错原因是生成的pre-commit中的命令无效我们删除掉该文件或者配置我们需要的脚本命令即可。

到此为止，我们不符合规范的提交将无法被提交。

接下里我们需要用pre-commit来检测提交时的代码规范

创建pre-commit文件

这样提交时有不符合规范的代码就会被拦截

需要注意的是，当错误特别多或者我们为一个项目添加该检测时，会出现大量的问题，我们不可能耗时间的去一一修改这些问题，这时，我们可以借助工具来实现。

1.8 lint-staged的使用

只检查本次修改跟更新的代码，并在出现错误的时候自动修复并且推送

pkg中加入如下代码

pre-commit改为如下

1.9 错误收集

1.9.1`husky - '~/.huskyrc' is DEPRECATED, please move your code to ~/.config/husky/init.sh`

这个意思是~/.huskyrc在新版本中被弃用了，需要在~/.config/husky/init.sh中添加配置

我们直接执行如下步骤即可

cat ~/.huskyrc复制其中内容
新建指定文件,执行下边的命令即可

echo '# This loads nvm.sh and sets the correct PATH before running hook
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' > ~/.config/husky/init.sh

添加执行权限

chmod +x ~/.config/husky/init.sh

验证内容

cat ~/.config/husky/init.sh

删除旧文件

rm ~/.huskyrc

到此，这个问题就会被解决啦

1.9.2 Some of your tasks use `git add` command. Please remove it from the config since all modifications made by tasks will be automatically added to the git commit index.

这个错误的意思就是你的配置里包含了git add命令，但系统会自动处理文件并添加git索引，所以需要移除这个命令

所以，pkg中去掉git add即可

Cursor 2025-08-12 15.53.55.png

1.9.3 针对按照网上大部分教程遇到的问题

遇到的绝大部分问题都是由于版本导致的，如按照教程安装，请注意各个工具的版本问题。

编程规范基本解决方案