# project-formatting

**Repository Path**: web-script/project-formatting

## Basic Information

- **Project Name**: project-formatting
- **Description**: 项目规范化实战，加入Eslint、Prettier、Git钩子、预提交工具、校验commit内容格式、支持项目级命令行提交规范提交内容
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue 3 + TypeScript + Vite 代码规范化实践

> **系统环境：** **node**：20.x | **pnpm**：10.x
>
> **项目架构：**`Vue3` + `TypeScript` + `Vite`
>
> **官网地址：**
> [Eslint 官网](https://eslint.org/docs/latest/) |
> [Prettier 官网](https://prettier.io/docs/) |
> [husky 官网](https://typicode.github.io/husky/) |
> [commitlint 官网](https://commitlint.nodejs.cn/reference/community-projects.html) |

## 创建项目
```bash
## 创建项目
pnpm create vite vue3-ts --template vue-ts
# 切换目录
cd vue3-ts
## 安装依赖
pnpm install
## 运行项目
pnpm dev
```

## `Eslint`
### 安装与初始化
```bash
# 安装eslint
pnpm create @eslint/config@latest
# 初始化eslint配置文件
npm init @eslint/config
```
![alt text](image.png)
### 自定义脚本命令行
```json
// package.json
{
  "scripts": {
    "lint": "pnpm dlx eslint src/**" // 校验src目录下的所有文件
    // "lint": "eslint" // 全局校验
  }
}
```

### 自定义规则
```js
// eslint.config.js 增加自定义规则
export default defineConfig([
  // ...默认配置
  {
    rules: {
      "no-unused-vars": "warn",
      "no-undef": "warn",
    },
  },
]);
```
### 测试是否生效
```typescript
// 在main.ts文件内写入
var a = 0
```
运行脚本
```bash
# 校验所有文件
pnpm lint
```
有错误提示，说明生效了
![alt text](image-1.png)


## `Prettier`
### 安装与初始化
```bash
# 安装prettier
pnpm add --save-dev --save-exact prettier
# 初始化.prettierrc文件
node --eval "fs.writeFileSync('.prettierrc','{}\n')"
# 初始化.prettierignore文件
node --eval "fs.writeFileSync('.prettierignore','# Ignore artifacts:\nbuild\ncoverage\n')"
```
### 设置忽略图片文件
```bash
# .prettierignore 文件下加一行
src/assets
```
### 自定义脚本命令行
```json
// package.json
{
  "scripts": {
    "format": "prettier . --write", // 格式化所有文件
    "format:check": "prettier . --check" // 检查所有文件
  }
}
```
`--write` 选项用于检查并格式化文件，`--check` 选项只用于检查文件不会格式化操作。

## `Git` 钩子
### 安装 `husky` 和 `lint-staged`
```bash
# 安装 husky 和 lint-staged
pnpm add --save-dev husky lint-staged
# 初始化 husky
pnpm exec husky init
# 增加 husky 配置文件
node --eval "fs.writeFileSync('.husky/pre-commit','pnpm exec lint-staged\n')"
```
### 添加`lint-staged` 配置
> 如果用了 `ESLint`, `lint-staged` 需要优先执行 `ESLint` 校验，然后再执行`prettier`格式化。具体配置见[预提交工具](/docs/practice/formatting/guide.html#预提交工具-lint-staged)
```json
// package.json
{
  "script": {
    // ...省略
  },
  "lint-staged": {
    "**/*": "prettier --write"
  }
}
```

## 预提交工具 `lint-staged`
> 此操作在安装`Perttier`格式化插件的基础上，[具体安装点击这里](/docs/practice/formatting/guide.html#prettier)
### 安装
```bash
# 安装 `mrm@2` `lint-staged`，并且在package.json 添加预提交钩子自动化格式配置内容
npx mrm@2 lint-staged
```
```json
// 自动生成的package.json内容为
"scripts": {
  "prepare": "husky && husky install"
},
"lint-staged": {
  "*": "prettier --write",
  "*.ts": "eslint --fix"
},
```
> [其他方式见官网](https://prettier.io/docs/precommit#option-1-lint-staged)
### 修改配置
> 根据[Prettier关于Git hooks的提示](https://prettier.io/docs/install#git-hooks), 同时使用`Eslint`和`Prettier`需要优先执行`Eslint`命令。而自动生成的脚本，是同一时间执行的，所以要进行如下修改。
```json
// package.json
"lint-staged": {
  "**/*.{js,mjs,cjs,ts,mts,cts,vue}": ["eslint --fix", "prettier --write"]
},
```
### 测试
写入错误代码后测试
```bash
pnpm exec lint-staged
```
测试通过！
### 深度测试
删除`node_module`目录，重新安装依赖
```bash
pnpm install
```
**报错**：`husky - install command is DEPERECATED`
#### 修复
1. 新建文件`.husky/install.mjs`
```bash
// .husky/install.mjs
if (process.env.NODE_ENV === "production" || process.env.CI === "true") {
  process.exit(0);
}
const husky = (await import("husky")).default;
console.log(husky());
```
2. 修改`package.json`文件
```json
"scripts": {
  "prepare": "node .husky/install.mjs"
}
```
3. 安装
```bash
pnpm install
```
安装成功！
4. 写入错误代码后测试
```bash
git add .
git commit -m "test"
```
报错，终止提交！=> 测试通过！

## 校验 `git commit` 信息
> 默认支持如下类型：`feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`
### 安装 `commitlint`
```bash
pnpm add -D @commitlint/cli @commitlint/config-conventional
```
### 配置文件
```js
// 新建commitlint.config.js
export default {
  extends: ["@commitlint/config-conventional"],
};
```
### 规范 `git commit` 信息格式
```bash
# 新建文件 ./husky/commit-msg
pnpm commitlint $1
```
### 添加脚本
```json
"scripts": {
  "commitlint": "commitlint --edit"
},
```
### 简单测试
```bash
npx commitlint --from HEAD~1 --to HEAD --verbose
```
测试通过！
### 钩子测试
```bash
git add .
git commit -m "test" # 提交失败
git commit -m "feat: commitlint 提交信息检查" # 提交成功
```
测试通过！

## 支持emoj标记和自定义
> [commitizen 官网](https://commitizen.github.io/cz-cli/) |
> [cz-emoji 官网](https://github.com/ngryman/cz-emoji) |
> [gitmoji 官网](https://gitmoji.dev/) |
### 全局安装`commitizen`
```bash
npm install -g commitizen
```
### 使用`cz-conventional-changelog`适配器初始化项目
```bash
commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact
```
### 新建脚本`commit`
```json
// package.json
"scripts": {
  "commit": "git-cz"
}
```
### 新建 `.czrc` 文件
[文件内容见](https://gitee.com/web-script/project-formatting/blob/main/.czrc)
### 新增 `commitizen` 配置项
```json
"config": {
  "commitizen": {
    "path": ".czrc"
  }
}
```
### 新建 `commitlint.config.js`
[文件内容见](https://gitee.com/web-script/project-formatting/blob/main/commitlint.config.js)
### 测试
```bash
# 此处省略使用文件添加到暂存区步骤
# 执行脚本
pnpm commit
```
![alt text](image-2.png)
按照提示进行操作，最后得到这样格式的提交信息：`♻️ refactor: 将commitizen相关配置提取到独立的文件`，测试通过！