前端工程基础配置

约 2368 字大约 8 分钟

2024-08-29

介绍一些前端项目的通用配置及相关资源，以便你了解项目中常见配置的含义以及配置方式。

.gitignore - 让 Git 提交时忽略文件
lint-staged - 对 git 暂存区匹配的文件执行动作
husky - 使用 git hooks 触发动作
commitlint - 确保 commit message 符合约定式提交规范
ESLint - 检查 JS 代码质量
Prettier - 美化代码格式
Stylelint - 检查 CSS 代码质量
commitzen - 命令行交互式生成符合约定式提交规范的 commit message

1. .gitignore - 让 Git 提交时忽略文件

通过 .gitignore 文件可将项目中符合规则的文件忽略掉，避免提交带有敏感信息或不需要共享的文件到 Git 仓库。

JavaScript 项目常用配置：

# 个性化配置
lib
bin
dist/config/data.json
*.DS_Store
*.lock
test/node_modules/
npm.test/node_modules/
watchNpmConfig.json
pkg
dist

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/
jspm_packages/

# TypeScript v1 declaration files
typings/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variables file
.env
.env.test

# parcel-bundler cache (https://parceljs.org/)
.cache

# next.js build output
.next

# nuxt.js build output
.nuxt

# vuepress build output
.vuepress/dist

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
.dynamodb/

gitignore 是 Github 官方维护的一份 git ignore 配置，可从中查找所需配置规则。

2. lint-staged - 对 git 暂存区匹配的文件执行动作

在提交代码前，通常会对代码进行质量检测、代码格式化等操作，但这些操作默认会对整个项目进行处理，对于稍大的项目，这个过程可能会异常慢。其实，我们只需要对本次要提交到 git 仓库的变更文件，进行检测即可避免代码流入仓库。通常每次提交所包含的变更文件是比较少的，这可以大大加速代码检测的速度。

借助 lint-staged 可以对 git 暂存区匹配的文件执行一组动作。

通过 pnpm 安装

pnpm add lint-staged -D

在 package.json 中配置匹配文件(glob 匹配模式)和要执行的动作命令。

{
    "lint-staged": {
        "./**/*.{js,ts,vue}": "eslint"
    },
}

配合下面的 husky 配置，对提交的符合 ./**/*.{js,ts,vue} 路径的文件执行 eslint 检测

3. husky - 使用 git hooks 触发动作

借助 husky 可以很方便的在 git push, git commit 等命令时执行一些附加动作，例如检查 commit message 是否符合规范、对代码进行检查和格式化等。

通过 pnpm 安装

# 安装 husky
pnpm add husky -D

# 初始化 husky (推荐)
# The init command simplifies setting up husky in a project. 
# It creates a pre-commit script in .husky/ and updates the prepare script in package.json. 
# Modifications can be made later to suit your workflow.
pnpm exec husky init

# 增加脚本
echo "lint-staged" > .husky/pre-commit

Git 提供了一系列客户端钩子（client-side hooks），这些钩子可以在特定的事件发生时自动触发自定义脚本。以下是所有 13 个客户端 Git 钩子：

钩子名称	触发时机	用途描述
applypatch-msg	`git am` 命令应用补丁前	验证补丁信息
pre-applypatch	`git am` 命令应用补丁前	检查即将应用的补丁
post-applypatch	`git am` 命令应用补丁后	通知或记录补丁的应用
pre-commit	`git commit` 命令创建提交前	代码检查或格式化
prepare-commit-msg	`git commit` 命令编辑提交消息前	自动生成或修改提交消息
commit-msg	`git commit` 命令编辑提交消息后	验证提交消息的格式
post-commit	`git commit` 命令完成提交后	通知或记录提交的完成
pre-rebase	`git rebase` 命令开始前	检查或准备 rebase 操作
post-checkout	`git checkout` 命令完成后	执行与切换分支相关的操作
post-merge	`git merge` 命令完成后	执行与合并相关的操作
pre-push	`git push` 命令开始前	检查推送内容或执行其他验证
pre-receive	接收端（服务器端）接收推送前	检查推送内容
update	接收端（服务器端）接收推送的每个分支更新前	检查推送内容

这些钩子可以通过在 .git/hooks 目录中创建相应的可执行脚本来配置和使用。每个钩子脚本的文件名与钩子的名称相同。

4. commitizen - 命令行交互式生成符合约定式提交规范的 commit message

使用 Commitizen 进行提交时，系统会提示您在提交时填写所有必需的提交字段，你只需要根据提示填写提交信息，Commitizen 会保证最终提交的消息符合约定式提交规范。

如果你的项目是对 Commitizen 友好的（即已经安装了 Commitizen 依赖），则在项目下提交消息时可直接使用npx git-cz来替代git commit命令。否则，你需要按照下面指引安装依赖，让你的项目变为对 Commitizen 友好的。

使项目对 Commitizen 友好

通过 pnpm 安装

pnpm add commitizen -D

初始化适配器

# npm
npx commitizen init cz-conventional-changelog --save-dev --save-exact
# yarn
npx commitizen init cz-conventional-changelog --yarn --dev --exact
# pnpm
npx commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact

在 package.json 中进行配置

{
    "scripts": {
        "commit": "cz"
    },
}

提交代码

git add . # 暂存修改的代码
pnpm commit # 提交代码，该命令替代 git commit
pnpm commit  --retry # 重新提交（使用上次输入的 commit 消息）

参考 Commit message 和 Change log 编写指南。

5. ESLint - 检查 JS 代码质量

ESLint 是一个可插拔的 JS 和 JSX 检查工具。

检查指定文件

通过 pnpm 安装

pnpm add eslint -D

执行下面命令后，根据提示创建 eslint 简易的配置文件

npx eslint --init

eslint 配置： https://eslint.org/docs/latest/use/getting-started#configuration

创建 .eslintrc 配置文件进行自定义，如果不知道如何配置，可执行eslint --init，然后根据提示做出选择，eslint 会自动生成一份配置文件。

6. Prettier - 美化代码格式

Prettier 是一个代码格式化程序（处理缩进、换行、空格等），它解析代码成抽象语法树(AST)并根据自定义格式重新输出代码，保证代码逻辑不变的前提下代码格式统一。它支持众多常见语言，例如 js/jsx/ts/tsx/json/css/scss/vue/yaml 等。

格式化指定文件

通过 pnpm 安装

pnpm add prettier eslint-plugin-prettier eslint-config-prettier -D

配合 eslint 进行进行使用，eslint.config.mjs 文件中增加配置

import globals from 'globals';
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';

export default [
    eslintPluginPrettierRecommended,
    {ignores: ['node_modules', 'dist', 'bin']},
    {files: ['**/*.js'], languageOptions: {sourceType: 'commonjs'}},
    {languageOptions: {globals: globals.node}},
    {
        rules: {
            'no-console': 'error',
            'prettier/prettier': [
                'error',
                {
                    printWidth: 100000000, // 一行代码超过这个值换行
                    tabWidth: 4,
                    singleQuote: true, // 启动单引号
                    semi: true, // 语句结尾无分号
                    useTabs: false,
                    bracketSpacing: false,
                    jsxBracketSameLine: true,
                    trailingComma: 'none', // 对象/数组最后一个属性不添加逗号
                    arrowParens: 'avoid' // 箭头函数参数不加()
                }
            ]
        }
    }
];

格式化本次 git 提交的文件

在 package.json 中添加如下配置，之后执行 git commit 前会对本次提交的文件进行格式化，并添加到本次提交内容中。也可以直接执行 npx lint-staged 格式化本次待提交文件。

  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}": [
      "prettier --write",
      "git add"
    ]
  }

创建 .prettierrc 配置文件进行自定义。

Stylelint- 检查 CSS 代码质量

Stylelint 是一个强大的现代 CSS 检测器，可以让你在样式表中遵循一致的约定和避免错误。

通过 npm 安装

npm install --save-dev stylelint

使用 CLI 检测样式文件

npx stylelint "src/**/*.css"

结合 husky 使用，在提交代码前执行检查

  "husky": {
    "hooks": {
      "pre-commit": "stylelint src/**/*.css"
    }
  }

结合 husky 和 lint-staged 一起使用，检查本次提交中修改的文件

  "lint-staged": {
    "src/**/*.css": "stylelint"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  }

创建 .stylelintrc 配置文件进行自定义。

预设配置

stylelint-config-recommended

commitlint - 确保 commit message 符合约定式提交规范

借助 commitizen 可以辅助生成符合约定式提交规范的 commit message，但是这种方式无法确保项目其他成员也会遵循，即使有开发文档约束，但缺乏强制力，依然会有成员忘记按这种规范编写 commit message。此时，需要借助 commitlint 在提交之前检测 commit message 是否合乎规范。

通过 npm 安装

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

在 package.json 中进行配置

{
  "commitlint": {
    "extends": [
      "@commitlint/config-conventional"
    ]
  }
}

约定式提交规范规定 commit message 需满足下面格式，其中 type 和 description 是必填项，有效的 type 值有 fix/feat/chore/docs/refactors/build/ci/style/perf/test 以及其他。

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

命令行测试

# Error，会输出错误信息
echo "xxx" | npx commitlint

# OK
echo "fix: xxx" | npx commitlint

与 husky 一起配合使用，提交前对 commit message 进行校验

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}