前端开发规范文档2026

前端开发规范（2026年修订版）

本文档基于原规范修订，结合2026年前端开发生态更新，旨在提升代码质量、开发效率和团队协作。

一、开发工具

1.1 编辑器与插件

推荐使用 VS Code，统一安装以下插件：

  • 必需
    • GitHub Copilot / 豆包（AI 辅助编码）
    • GitLens — Git supercharged（Git 可视化）
    • ESLint（代码检查）
    • Prettier - Code formatter（代码格式化）
    • Vue (Official)（Vue 3 支持，替代 Volar、Vetur）
    • ES7+ React/Redux/React-Native snippets（React 代码片段）
  • 可选
    • REST Client（接口测试）
    • Dotenv Official +Vault（环境变量高亮）
    • Error Lens（错误实时提示）

1.2 VS Code 配置（settings.json）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "editor.wordWrap": "on",
  "editor.detectIndentation": false,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  // TypeScript 配置
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.tsdk": "node_modules/typescript/lib",
  // Vue 3 配置
  "vue.inlayHints.missingProps": true,
  // Prettier 作为默认格式化工具
  "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[vue]": { "editor.defaultFormatter": "Vue.volar" },
  "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  // 编码与终端
  "files.autoGuessEncoding": true,
  "terminal.integrated.env.windows": { "LC_ALL": "en_US.UTF-8" },
  "diffEditor.ignoreTrimWhitespace": false
}

1.3 Prettier 配置（.prettierrc）

1
2
3
4
5
6
7
8
{
  "singleQuote": true,
  "semi": false,
  "trailingComma": "none",
  "printWidth": 100,
  "vueIndentScriptAndStyle": false,
  "endOfLine": "lf"
}

二、基本规范

2.1 命名规范

整体原则

  • 禁用拼音，使用英文语义化命名
  • 字母小写，专有名词大写（如 iPhone、API）
  • 共性在前，个性在后（如 userProfile、orderList）

项目/目录/文件

类型 规范 示例
项目 中划线拼接 my-project、webapp-admin
目录 中划线拼接，复数形式 components/、user-services/
Vue/TSX PascalCase（大驼峰） UserProfile.vue、OrderList.tsx
样式文件 中划线拼接 user-profile.scss
资源文件 下划线拼接 login_bg.png、icon_home.svg

组件与CSS

  • 组件：声明和使用均用 PascalCase
    1
    2
    3
    4
    5
    6
    <script setup lang="ts">
    import UserProfile from '@/components/UserProfile.vue'
    </script>
    <template>
      <UserProfile />
    </template>
  • CSS：类名中划线，ID 驼峰；推荐使用 CSS Modules 或 Scoped CSS
    1
    2
    3
    4
    /* 普通类名 */
    .user-profile { color: #333; }
    /* CSS Modules（推荐） */
    .userProfile { color: #333; }

JavaScript/TypeScript

类型 规范 示例
常量 大写+下划线 MAX_PAGE_SIZE = 50
私有变量 下划线开头+小驼峰 _userName = '张三'
普通变量 小驼峰 userName、orderList
函数 小驼峰，动词开头 getUserInfo()、submitForm()
类/接口 PascalCase class UserService {}、interface User {}

形参规范（保持原规范，补充类型）

1
2
3
function handleTabSwitch(i: number) { /* 索引 */ }
function handleInputChange(e: Event) { /* 事件 */ }
function setData(v: string | number) { /* 基本类型值 */ }

2.2 编码规范（TypeScript 优先）

引用与变量

  • 优先使用 const，需重新赋值用 let，禁用 var
  • 使用 TypeScript 类型注解
    1
    2
    3
    4
    5
    // bad
    var count = 1
    // good
    const count: number = 1
    let userName: string = '张三'

对象与数组

  • 使用字面值创建，对象属性/方法简写
  • 使用扩展运算符复制数组，Array.from 转换类数组
    1
    2
    3
    4
    5
    6
    7
    // 对象
    const user = { name: '张三', age: 18 }
    const newUser = { ...user, age: 19 } // 扩展
    // 数组
    const list = [1, 2, 3]
    const newList = [...list, 4]
    const nodes = Array.from(document.querySelectorAll('.node'))

解构赋值

  • 优先使用对象/数组解构，结合 TypeScript 类型
    1
    2
    3
    4
    5
    interface User { name: string; age: number }
    function getUserName({ name }: User): string {
      return name
    }
    const [first, second] = [1, 2]

字符串与函数

  • 模板字符串替代字符串拼接
  • 箭头函数用于回调，函数声明用于具名函数
    1
    2
    3
    4
    5
    6
    7
    8
    // 字符串
    const name = '张三'
    const greeting = `你好，${name}`
    // 函数
    const add = (a: number, b: number): number => a + b
    function fetchUser(id: string): Promise<User> {
      return fetch(`/api/user/${id}`).then(res => res.json())
    }

模块与导入

  • 使用 ES Modules（import/export）
  • 避免通配符导入，优先命名导入
    1
    2
    3
    4
    5
    // bad
    import * as utils from './utils'
    // good
    import { formatDate, debounce } from './utils'
    export default function UserService() {}

2.3 注释规范

原则

  • 如无必要，勿增注释；代码即文档
  • 使用 JSDoc 配合 TypeScript 类型（类型优先，JSDoc 补充说明）

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/**
 * @description 获取用户信息
 * @param id - 用户ID
 * @returns 用户信息Promise
 * @example
 * ```ts
 * const user = await getUser('123')
 * ```
 */
async function getUser(id: string): Promise<User> {
  return fetch(`/api/user/${id}`).then(res => res.json())
}

// 单行注释：说明复杂逻辑
const total = list.reduce((sum, item) => sum + item.price, 0) // 计算订单总价

三、代码提交规范

3.1 遵循 Conventional Commits

格式：<type>(<scope>): <subject>

  • type：
    • feat：新功能
    • fix：修复bug
    • docs：文档更新
    • style：代码格式（不影响逻辑）
    • refactor：重构
    • test：测试相关
    • chore：构建/工具链
  • subject：简洁描述，结尾附禅道/任务编号（如 #123）

3.2 示例

1
2
3
feat(login): #9047 增加手机号验证码登录
fix(order): #123 修复订单列表分页bug
docs: 更新README部署文档

3.3 工具配置

  • 使用 commitizen 辅助生成提交信息
  • 使用 commitlint + husky 强制规范
    1
    2
    3
    4
    5
    # 安装依赖
    npm install -D commitizen @commitlint/cli @commitlint/config-conventional husky
    # 初始化husky
    npx husky install
    npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

四、版本规范

4.1 语义化版本（推荐）

格式：主版本号.次版本号.修订号（如 2.1.3）

  • 主版本：不兼容的 API 变更
  • 次版本：向下兼容的功能新增
  • 修订号：向下兼容的问题修复

4.2 敏捷开发版本（可选）

仅用于内部快速迭代项目：主版本号.YYMM.DHHmm（如 1.2603.11021）

  • 主版本：框架升级
  • 次版本：年月（2603 = 2026年3月）
  • 修订号：日时分（11021 = 1日10点21分）

五、开发与发布流程

5.1 Git 分支管理

分支命名

  • 功能分支：feature/任务编号-功能描述（如 feature/#9527-user-login）
  • Bug修复：bugfix/任务编号-问题描述（如 bugfix/#123-order-list）
  • 紧急修复：hotfix/日期-问题描述（如 hotfix/20260313-login-error）

工作流（GitHub Flow）

  1. 从 main 拉取分支
  2. 开发完成后提交 PR（Pull Request）
  3. 代码审查通过后合并到 main
  4. 打 Tag 发布（如 v2.1.3）
  5. 删除已合并分支

5.2 发布流程

  1. 开发环境：分支 → alpha（自动部署）
  2. 测试环境：alpha → beta（测试验证）
  3. 正式环境：
    • 合并到 main，打 Tag
    • 通过 Jenkins 流水线发布（特殊情况需负责人审批手动发布）
    • 发布前检查：
      • 环境变量为正式环境
      • package.json 版本号已更新
    • 发布后检查：
      • Jenkins 日志无异常
      • 核心功能（登录、支付等）验证正常
      • 持续跟进24小时运行情况

六、框架与库选型

6.1 核心框架

场景 推荐选型 说明
前端框架 Vue 3.x（Composition API） / React 18+ Vue 3 兼容 Chrome 64+，React 18 支持并发特性
语言 TypeScript 5.x 类型安全，提升可维护性

6.2 UI 框架

场景 推荐选型 文档链接
PC/CMS Ant Design Vue 4.x / Element Plus 2.x Ant Design Vue
H5/移动端 Vant 4.x / NutUI 4.x Vant
移动端设计 Ant Design Mobile 6.x Ant Design Mobile

6.3 项目模板

场景 内部模板 开源参考
Vite - vite
CMS cms-v3（每季度同步 vue-vben-admin） vue-vben-admin
Electron - electron-vite quasar

七、TypeScript 专项规范

7.1 类型定义

  • 使用 interface 定义对象结构，type 定义联合类型
    1
    2
    3
    4
    5
    6
    7
    8
    // 对象结构
    interface User {
      id: string
      name: string
      age?: number // 可选属性
    }
    // 联合类型
    type Status = 'pending' | 'success' | 'error'

7.2 泛型与工具类型

  • 使用泛型提高复用性
  • 利用 TS 内置工具类型（Partial、Pick、Omit 等）
    1
    2
    3
    4
    5
    6
    // 泛型函数
    function fetchData<T>(url: string): Promise<T> {
      return fetch(url).then(res => res.json())
    }
    // 工具类型：只取User的name和age
    type UserProfile = Pick<User, 'name' | 'age'>

八、测试规范

8.1 单元测试

  • 工具：Vitest（推荐）/ Jest
  • 覆盖核心逻辑（工具函数、状态管理）
    1
    2
    3
    4
    5
    6
    7
    import { describe, it, expect } from 'vitest'
    import { add } from './utils'
    describe('add', () => {
      it('should return sum', () => {
        expect(add(1, 2)).toBe(3)
      })
    })

8.2 E2E 测试

  • 工具：Playwright（推荐）/ Cypress
  • 覆盖核心流程（登录、下单等）

九、性能与安全

9.1 性能优化

  • 代码分割：路由懒加载（Vue defineAsyncComponent、React React.lazy）
  • 图片优化：使用 WebP/AVIF 格式，配合 CDN 缩放
  • 缓存策略：合理使用 HTTP 缓存、Service Worker（PWA）
  • 构建优化：Vite 自动 Tree Shaking，生产环境禁用 source map

9.2 安全规范

  • XSS 防护：避免 innerHTML，使用 textContent；Vue/React 默认自动转义
  • CSRF 防护：请求携带 Token
  • 依赖安全：定期运行 npm audit 或 snyk 检查漏洞
  • HTTPS：所有环境强制 HTTPS

十、调试与部署

10.1 嵌入式页面调试

  • 工具：Eruda 3.x / vConsole
  • 动态加载（推荐）
    1
    2
    3
    4
    5
    6
    7
    // 非生产环境加载
    if (import.meta.env.MODE !== 'production') {
      const script = document.createElement('script')
      script.src = 'https://public.yitong.com/libs/eruda/3.0.1/eruda.min.js'
      document.body.appendChild(script)
      script.onload = () => eruda.init()
    }

10.2 CDN 使用

  • 优先使用公司内部 CDN，第三方资源同步到内部
  • 示例：
    1
    2
    原地址：https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js
    内部地址：https://public.yitong.com/npm/lodash@4.17.21/lodash.min.js

十一、团队协作

11.1 项目管理

  • 每日查看禅道任务，按优先级开发
  • 每日填报工时，任务完成及时流转
  • 每日提交日报，每周四提交周报（包含任务编号、进度、对接人）

11.2 代码审查

  • PR 至少1人审查通过方可合并
  • 审查重点：类型安全、逻辑正确性、性能影响

文档版本：v3.0（2026-03-12）
维护人：前端团队
更新周期：每季度回顾更新

#前端 #规范
前端开发规范文档2026
https://cszy.top/20260312-前端开发规范文档2026/
作者
csorz
发布于
2026年3月12日
许可协议