為項目添加 Prettier 及規範提交信息工具

1. 配置 Prettier 格式化代碼

安裝 Prettier 及相關插件

pnpm

pnpm add --save-dev --save-exact prettier @trivago/prettier-plugin-sort-imports prettier-plugin-jsdoc prettier-plugin-packagejson prettier-plugin-sort-json

npm

npm install --save-dev --save-exact prettier @trivago/prettier-plugin-sort-imports prettier-plugin-jsdoc prettier-plugin-packagejson prettier-plugin-sort-json

yarn

yarn add --dev --exact prettier @trivago/prettier-plugin-sort-imports prettier-plugin-jsdoc prettier-plugin-packagejson prettier-plugin-sort-json

Prettier 配置

新建 .prettierrc.yaml 配置如下

.prettierrc.yaml

plugins:
  - '@trivago/prettier-plugin-sort-imports'
  - 'prettier-plugin-packagejson'
  - 'prettier-plugin-sort-json'
  - 'prettier-plugin-vitepress'

printWidth: 120
semi: false
singleQuote: true
trailingComma: 'none'

importOrderSeparation: false
importOrderSortSpecifiers: true
importOrder:
  - '<THIRD_PARTY_MODULES>'
  - '^vitepress$'
  - '^vitepress([-/].*)?$'
  - '^vue$'
  - '^vite$'
  - '^@[a-zA-Z0-9-]+/(.*)$'
  - '^@/(.*)$'
  - '^./.*$'
  - '^../.*$'
  - '^[./]'
  - '^(.*)$'

overrides:
  - files: ['*.json']
    options:
      jsonRecursiveSort: true

創建 Prettier 忽略文件

新建 .prettierignore 配置如下

.prettierignore

dist
pnpm-lock.yaml
cache
temp
.temp
*.vue

使用 Prettier 格式化所有文件

pnpm

pnpm exec prettier . --write

npm

npx prettier . --write

yarn

yarn prettier . --write

配置 commit 自動格式化

安裝 simple-git-hooks 和 lint-staged 插件

pnpm install simple-git-hooks lint-staged

配置 package.json 示例

{
  "lint-staged": {
    "*": ["prettier --write --ignore-unknown"]
  },
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged"
  }
}

2. 安裝 cz-vinyl 和 commitizen 並配置

pnpm

pnpm add --save-dev cz-vinyl commitizen
# 或者本地全局安裝
pnpm add -g cz-vinyl commitizen

npm

npm install --save-dev cz-vinyl commitizen
# 或者本地全局安裝
npm install -g cz-vinyl commitizen

yarn

yarn add --dev cz-vinyl commitizen
# 或者本地全局安裝
yarn global add cz-vinyl commitizen

查看本地全局安裝配置

1. 在用戶主目錄創建 .czrc 配置文件，指定適配器路徑

echo '{ "path": "cz-vinyl" }' > ~/.czrc

2. 給 cz 命令設置別名，指向 git-cz（cz-vinyl 的執行命令）：

echo 'alias cz="git-cz"' >> ~/.zshrc
source ~/.zshrc

這樣你可以直接通過 cz 命令啟動交互式提交

配置 package.json 示例

{
  "config": {
    "commitizen": {
      "path": "cz-vinyl"
    }
  },
  "scripts": {
    "cz": "git-cz"
  }
}

cz-vinyl 選項配置示例

czvinyl.config.ts

import type { CzVinylConfig } from 'cz-vinyl'

const config: CzVinylConfig = {
  headerFormat: '{type}{scope}: {subject}',
  bodyFormat: '{body}',
  commitTypes: [
    { value: 'feat', description: '新增功能' },
    { value: 'fix', description: '修復缺陷' },
    { value: 'docs', description: '文檔更新' },
    { value: 'style', description: '代碼格式（不影響功能，例如空格、分號等）' },
    {
      value: 'refactor',
      description: '重構代碼（既不是新增功能，也不是修復 bug）'
    },
    { value: 'perf', description: '性能優化' },
    { value: 'test', description: '增加測試' },
    { value: 'chore', description: '構建過程或輔助工具變動' }
  ],
  maxCommitLineWidth: 72,
  typeQuestion: '請選擇提交類型:',
  scopeQuestion: '請選擇修改範圍（可選）:',
  skipScope: false,
  scopes: ['', 'types', 'hooks', 'utils', 'components', 'views', 'store'],
  ticketIdQuestion: '請輸入關聯的任務號（可選）:',
  skipTicketId: true,
  subjectQuestion: '請簡要描述提交內容（必填）:',
  subjectMaxLength: 50,
  subjectMinLength: 5,
  bodyQuestion: '請輸入詳細描述（可選）:',
  skipBody: true,
  skipBreakingChanges: true,
  issuesQuestion: '請輸入要關閉的issue（可選，例如:#1）:',
  skipIssues: false,
  openAiToken: null
}

export default config

3. 安裝及配置 commitlint 校驗工具

安裝 commitlint 及 Husky 集成

pnpm

pnpm add --save-dev @commitlint/cli @commitlint/config-conventional @commitlint/types husky
pnpm husky install

# 在package.json中配置腳本
npm pkg set scripts.commitlint="commitlint --edit"
echo "pnpm commitlint \${1}" > .husky/commit-msg

npm

npm install --save-dev @commitlint/cli @commitlint/config-conventional @commitlint/types husky
npx husky install

# 在package.json中配置腳本
npm pkg set scripts.commitlint="commitlint --edit"
echo "npm run commitlint \${1}" > .husky/commit-msg

yarn

yarn add --dev @commitlint/cli @commitlint/config-conventional @commitlint/types husky
yarn husky install

# 在package.json中配置腳本
npm pkg set scripts.commitlint="commitlint --edit"
echo "yarn commitlint \${1}" > .husky/commit-msg

commitlint 配置示例

新建 commitlint.config.ts 文件

commitlint.config.ts

import type { UserConfig } from '@commitlint/types'

const config: UserConfig = {
  extends: ['@commitlint/config-conventional']
}

export default config

commitlint.config.js

export default { extends: ['@commitlint/config-conventional'] }

CI 校驗提交信息

GitHub Actions 示例，自動檢查提交信息規範

.github/workflows/commitlint.yml

name: CI

on: [push, pull_request]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install required dependencies
        run: |
          sudo apt update
          sudo apt install -y sudo
          sudo apt install -y git curl
          curl -sL https://deb.nodesource.com/setup_22.x | sudo -E bash -
          sudo DEBIAN_FRONTEND=noninteractive apt install -y nodejs
      - name: Print versions
        run: |
          git --version
          node --version
          npm --version
          npx commitlint --version
      - name: Install commitlint
        run: |
          npm install conventional-changelog-conventionalcommits
          npm install commitlint@latest

      - name: Validate current commit (last commit) with commitlint
        if: github.event_name == 'push'
        run: npx commitlint --last --verbose

      - name: Validate PR commits with commitlint
        if: github.event_name == 'pull_request'
        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose