前端规范

当前采用较为宽松的方式：像 HTML、CSS 那类细则规范已经移除，基本不强制统一，主要围绕技术栈方向来整合。

本规范用于统一团队前端项目的技术选型、环境配置与编码约定。原则上新项目一律按此规范执行，存量项目按实际情况逐步靠拢。规范不追求绝对一致，少量不一致不影响整体协作即可，重点是把方向定下来。

技术选型

新项目首选以下技术栈：

• Vue 3 —— 统一使用组合式 API（<script setup>）
• TypeScript —— 全量 TS，避免裸 JS
• Element Plus —— 中后台 UI 组件库
• TailwindCSS —— 原子化 CSS，优先用工具类，少写自定义样式
• Vite —— 构建工具
• 包管理 —— monorepo 项目用 pnpm，其他项目用 npm

选型为首选而非强制。若有特殊场景（如老项目、特定平台限制）需偏离，确认后即可，不强求完全一致。

AI 驱动开发

团队开发以 AI 驱动为主导方式：

• 优先借助 AI 完成编码、重构、补全、测试与文档
• 配合团队的 AI 接入文档 与 AI Commit 插件 使用
• 规范、目录结构、命名尽量清晰可预测，便于 AI 理解上下文、生成一致的代码

电脑环境配置

Node 版本管理

使用 n 或 nvm 管理与切换 Node 版本，按实际项目需求安装对应版本：

Node 版本	用途
8	维护 GitBook 类老项目
14 / 16 / 18	存量项目维护
22 / 24	新项目开发（推荐）

nvm 常用命令：

nvm install 22        # 安装指定版本
nvm use 22            # 切换当前使用版本
nvm alias default 22  # 设置默认版本
nvm ls                # 查看已安装版本

n 常用命令：

n 22      # 安装并切换到指定版本
n         # 交互式选择已安装版本
n ls      # 查看可用版本

不必把所有版本都装上，按手头项目需要安装即可。维护 GitBook 项目时再切到 8。

包管理工具

按项目类型选择包管理工具：

• 普通项目 —— 使用 npm
• monorepo 项目 —— 使用 pnpm（workspace 方案管理）

全局安装 pnpm（用于 monorepo 项目）：

npm i -g pnpm

编码规范

ESLint

• 启用严格 ESLint 模式
• 提交前确保通过 lint 检查
• 出现少量不一致问题，影响不大时可接受，但不应放任规则形同虚设
• TS / JS 行尾不加分号（;）

缩进

• 使用 Tab 缩进，且 1 个 Tab 宽度等于 2 个空格
• 统一使用 Tab，不混用空格缩进
• 建议在 .editorconfig / 编辑器中固化该约定：

# .editorconfig
root = true

[*]
indent_style = tab
indent_size = 2
tab_width = 2
end_of_line = lf
charset = utf-8
insert_final_newline = true
trim_trailing_whitespace = true

组件化

Vue 开发过程中要始终保有组件化思想：

⚠️ 重点：时间充足时必须组件化

时间充足时，必须进行组件化构建 —— 合理拆分组件、抽离可复用逻辑（Hook）、保持单一职责，这是硬性要求，不可省略。

• 项目追求速度时，AI 直接产出、未做组件化拆分的代码可以接受，作为临时方案
• 后续优化时无需重写，只需让 AI 对已有代码做组件化重构，或在 prompt 阶段就给出组件化的相应提示，让 AI 一次到位

其他约定

• 组件、Hook、工具方法优先复用团队 公共包
• 命名清晰、语义化，目录结构可预测
• 提交信息遵循 git commit 规范