编码规范

环境与工具版本

本规范面向 frontend/ 下的 monorepo（基于 Vben Admin 改造），统一代码风格、静态检查与提交流程，帮助团队在不依赖人工 review 的情况下保持代码一致性与可维护性。为保证全团队行为一致，请严格遵守以下版本要求：

Node：^22.18.0 || ^24.0.0
pnpm：>=11.0.0（仓库已通过 preinstall 脚本强制 only-allow pnpm，使用 npm/yarn 会直接报错）
主要检查工具：oxlint ^1.70.0、oxfmt ^0.55.0、eslint ^10.5.0、stylelint ^17.13.0、lefthook ^2.1.9、typescript ^6.0.3

编辑器基础约定

仓库根目录的 .editorconfig 已定义统一的基础格式，主流编辑器（VS Code、WebStorm）安装 EditorConfig 插件后会自动生效：

字符编码：utf-8
换行符：lf（务必不要提交 crlf）
缩进：2 个空格，禁用 Tab
字符串引号：单引号
行宽：100 字符（超出尽量换行，不强制）
文件末尾保留一个空行，去除行尾空白

提示：这些基础规则由编辑器和格式化工具共同保证，无需在 PR 中手动核对。

静态检查工具

oxlint（首选 Linter）

oxlint 用 Rust 编写，速度极快，是提交时第一道静态检查。配置位于 frontend/oxlint.config.ts，直接复用 Vben 官方配置 @vben/oxlint-config：

import { oxlintConfig } from '@vben/oxlint-config';
import { defineConfig } from 'oxlint';

export default defineConfig(oxlintConfig);

覆盖的文件类型：*.{js,jsx,ts,tsx,vue,cjs,mjs,cts,mts}。提交钩子中以 oxlint --fix --type-aware 运行，能自动修复的问题会直接回填到暂存区。

eslint（兼容性检查）

eslint 作为补充，处理 oxlint 暂未覆盖的规则与部分框架相关校验。配置极简，复用 @vben/eslint-config：

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

export default defineConfig();

stylelint（样式检查）

负责 .vue、.css、.less、.scss 中的样式规范，继承自 @vben/stylelint-config：

export default {
  extends: ['@vben/stylelint-config'],
  root: true,
};

格式化工具

oxfmt 负责代码格式化（含 .json / .jsonc），同样在提交时自动执行并回填。忽略列表在 frontend/oxfmt.config.ts 中定义，已排除 node_modules、dist、public、*.svg、*-lock.yaml 等产物与资源文件。

日常如需本地主动检查或修复，可运行：

pnpm lint：运行 vsh lint 做全量检查
pnpm format：运行 vsh lint --format 自动格式化

Git 钩子与 lefthook

仓库通过 lefthook（prepare 脚本在 postinstall 后自动安装）管理 Git 钩子，配置位于 frontend/lefthook.yml。

pre-commit

提交前串行执行以下任务（刻意不使用 parallel，避免低配机器内存/CPU 瞬时飙升）：

任务	工具	作用文件	说明
oxlint	`oxlint --fix --type-aware`	js/ts/vue 等	类型感知检查并自动修复，回填暂存区
oxfmt	`oxfmt`	js/ts/vue/json 等	格式化并回填
eslint	`eslint --fix`	js/ts/vue 等	兼容性检查并修复
stylelint	`stylelint --fix`	vue/css/less/scss	样式修复
checkType	`pnpm check:type`	全量	`turbo run typecheck` 类型检查

stage_fixed: true 表示自动修复后的文件会自动加回暂存区；若 oxlint/oxfmt/eslint/stylelint 无法自动修复（如类型错误），提交会失败，需手动修正后重新 add。

commit-msg

通过 commitlint 校验提交信息格式（见下文“提交信息规范”）。

post-merge

合并后自动执行 pnpm install，保证依赖与远端同步。

提交信息规范

提交信息遵循 Conventional Commits 规范，由 commitlint 在 commit-msg 钩子中校验，不满足格式将被拒绝。

推荐使用交互式提交命令 pnpm commit（基于 czg），按提示选择类型、填写范围与描述，可避免格式错误：

bash

pnpm commit

提交信息格式：

<type>(<scope>): <subject>

type：feat / fix / docs / style / refactor / perf / test / build / ci / chore / revert
scope（可选）：影响范围，如 web-ele、ui-kit、api
subject：简明扼要的变动描述，使用中文或英文均可，句末不加句号

示例：

feat(web-ele): 新增用户管理列表页
fix(ui-kit): 修复抽屉关闭时动画异常
docs: 补充编码规范文档

仓库根 package.json 指定 commitlint 配置为 @vben/commitlint-config，类型与范围须符合其约定。

代码风格约定

以下约定为 Vben 技术栈下团队共识，多数已由上述工具强制，少量需人工遵守。

命名

文件/目录：组件用 PascalCase（如 UserTable.vue），其他模块用 kebab-case（如 use-user.ts）。
变量/函数：camelCase；组件内 ref 变量与模板 ref 保持一致语义。
常量：UPPER_SNAKE_CASE。
类型/接口/类：PascalCase，接口可不加 I 前缀（与 Vben 默认一致）。

组合式 API 与 `<script setup>`

统一使用 <script setup lang="ts"> 语法糖编写组件。
复用逻辑抽离为 composables（以 use* 开头的函数，如 useUser、useAccess）。
优先使用 ref / computed / watch，避免 Options API。

导入顺序

第三方依赖 → 内部 @vben/* / @core/* → 相对路径，按 eslint-plugin-perfectionist 自动排序，无需手动整理。
monorepo 内部包通过 workspace 别名引用（@vben/web-ele、@core/ui-kit 等），不要写相对路径跨包引用。

样式

样式优先使用 Tailwind 原子类；复杂样式写 scoped 的 <style>。
颜色、间距等遵循设计令牌（Vben 主题变量），不要硬编码魔法值。
样式顺序由 stylelint + stylelint-config-recess-order 自动整理。

TypeScript

开启严格模式，禁止 any（确有必要时局部 // eslint-disable 并说明）。
接口入参/出参使用类型定义，避免隐式 any。
公共函数与组件 props 显式标注类型。

Vben 组件约定

项目 UI 基于 @core/ui-kit 与 @core/base 等内部包，使用 shadcn 风格组件体系。业务开发中应遵循以下约定：

优先使用 UI-Kit 而非原生组件

packages/@core/ui-kit 包含了已封装、风格统一的基础组件，开发时优先复用：

shadcn-ui：按钮、输入框、对话框、下拉、表格等基础原子组件
form-ui：表单体系，基于 schema 驱动
popup-ui：弹窗/抽屉封装
layout-ui：布局骨架
menu-ui：菜单
tabs-ui：多标签页

表单与弹窗范式

表单统一使用 form-ui 的 schema 配置驱动，避免手写大量 el-form-item。
新增/编辑场景优先使用 popup-ui 的 Modal / Drawer 封装，统一标题、确认/取消按钮与 loading 态。
列表页使用统一的表格封装与分页约定（详见《页面开发范式》）。

业务组件沉淀

跨页面复用的逻辑或 UI 收敛到 packages/business/*。
组件 props 提供默认值与类型，保持无副作用、可独立测试。
组件内不发起直接接口请求；数据获取统一走 api 适配层（详见《接口请求与适配层》）。

图标

统一使用 Iconify（@iconify/vue），通过 Vben 提供的图标组件引用，不要引入散落的图片图标。

常用命令速查

bash

# 安装依赖（合并后钩子也会自动执行）
pnpm install

# 启动前端（web-ele）
pnpm dev:ele

# 本地全量检查 / 格式化
pnpm lint
pnpm format

# 类型检查（pre-commit 会执行）
pnpm check:type

# 拼写检查 / 依赖 / 循环依赖检查
pnpm check:cspell
pnpm check:dep
pnpm check:circular

# 单元测试 / e2e
pnpm test:unit
pnpm test:e2e

# 交互式提交
pnpm commit

常见问题

提交被 oxlint/eslint 拦截且无法自动修复？ 多为类型错误或真实代码缺陷，根据终端提示定位文件与行号手动修正，再 git add 重新提交。

check:type 耗时较长？ 它是全量 vue-tsc 类型检查，pre-commit 中串行执行以控制资源占用，属正常现象；本地可先用 pnpm dev:ele 的即时编译兜底。

误装了 npm/yarn 依赖？ 仓库 preinstall 已禁止非 pnpm 安装，请改用 pnpm install。

换行符变成 CRLF 导致大量 diff？ 确保编辑器启用 EditorConfig（.editorconfig 已设 end_of_line=lf），对历史文件可用 pnpm format 统一。

想跳过钩子临时提交？ 不推荐。如遇紧急情况可用 git commit --no-verify，但需在合并前补齐检查，避免破坏 CI。

编码规范 ​

环境与工具版本 ​

编辑器基础约定 ​

静态检查工具 ​

oxlint（首选 Linter） ​

eslint（兼容性检查） ​

stylelint（样式检查） ​

格式化工具 ​

Git 钩子与 lefthook ​

pre-commit ​

commit-msg ​

post-merge ​

提交信息规范 ​

代码风格约定 ​

命名 ​

组合式 API 与 <script setup> ​

导入顺序 ​

样式 ​

TypeScript ​

Vben 组件约定 ​

优先使用 UI-Kit 而非原生组件 ​

表单与弹窗范式 ​

业务组件沉淀 ​

图标 ​

常用命令速查 ​

常见问题 ​