工具规范

SoybeanAdmin 通过一套统一的工具链来保证代码质量、规范 Git 工作流并提升开发效率。本页对项目中实际使用的工具做整体概览，包括代码质量工具、Git 工作流工具、包管理以及 @soybeanjs/cli 命令行，帮助你快速了解各工具的职责与协作方式。

工具链概览

类别	工具	作用
代码质量	`@soybeanjs/eslint-config`（ESLint + Prettier）	代码检查与格式化
Git 工作流	`simple-git-hooks`、`lint-staged`	提交前校验与暂存文件检查
命令行	`@soybeanjs/cli`（`soy` / `sa`）	提交、清理、发布、更新依赖等
包管理	`pnpm`	安装、运行脚本与版本管理

代码质量：ESLint + Prettier

项目使用 @soybeanjs/eslint-config 统一处理代码检查与格式化，它在内部整合了 ESLint 与 Prettier，并附带一系列自定义规则。

eslint.config.js 使用 Flat Config 形式，按需开启 vue 与 markdown 等能力：

import { defineConfig } from '@soybeanjs/eslint-config';

export default defineConfig({
  vue: true,
  formatter: {
    markdown: true
  }
});

执行检查与自动修复：

bash

pnpm lint

该脚本对应 eslint . --fix。更多关于 ESLint、Prettier 与 lint-staged、simple-git-hooks 的配置细节，请参阅格式化检查。

Git 工作流工具

为保证每次提交的质量与提交信息的规范，项目通过 simple-git-hooks 配置 Git 钩子，并配合 lint-staged 仅检查本次暂存的文件：

json

{
  "simple-git-hooks": {
    "commit-msg": "pnpm sa git-commit-verify",
    "pre-commit": "pnpm typecheck && pnpm lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  }
}

pre-commit：提交前先做类型检查（typecheck），再对暂存文件执行 ESLint 自动修复。
commit-msg：通过 sa git-commit-verify 校验提交信息是否符合 Conventional Commits 规范。

推荐使用 @soybeanjs/cli 提供的交互式提交命令来生成规范的提交信息，避免手写出错：

bash

# 交互式生成符合 Conventional Commits 规范的提交信息
pnpm commit

# 生成中文提交信息
pnpm commit:zh

如需了解 Git 钩子的设计初衷与移除方式，请参阅 Git Hooks。

包管理：pnpm

项目使用 pnpm 作为包管理器，并在 package.json 的 engines 中约束了运行环境：

json

{
  "engines": {
    "node": ">=20.19.0",
    "pnpm": ">=8.7.0"
  }
}

常用命令：

bash

# 安装依赖
pnpm install

# 启动文档开发服务
pnpm dev

# 构建文档
pnpm build

命令行工具：@soybeanjs/cli

@soybeanjs/cli 提供了 soy（亦可用 sa）命令，封装了一系列常用的工程化能力。这些命令已在 package.json 的 scripts 中按需绑定：

命令	说明	对应脚本
`git-commit`	交互式生成符合 Conventional Commits 规范的提交信息	`pnpm commit`
`git-commit-verify`	校验提交信息是否符合规范（用于 `commit-msg` 钩子）	—
`cleanup`	删除 `node_modules`、`dist` 等目录	`pnpm cleanup`
`ncu`	更新 `package.json` 中的依赖版本	`pnpm update-pkg`
`release`	更新版本、生成 changelog 并提交代码	`pnpm release`
`changelog`	生成 changelog	—

命令的完整列表与说明请参阅命令行与命令。

工具规范 ​

工具链概览 ​

代码质量：ESLint + Prettier ​

Git 工作流工具 ​

包管理：pnpm ​

命令行工具：@soybeanjs/cli ​

推荐的编辑器与插件 ​

工具规范

工具链概览

代码质量：ESLint + Prettier

Git 工作流工具

包管理：pnpm

命令行工具：@soybeanjs/cli

推荐的编辑器与插件