React 19 + Vite 企业级前端项目：从零搭建到规范交付

本文以一个真实企业级前端项目的开发实践为基础，分享如何基于 React 19 + Ant Design 5 + TypeScript + Vite 技术栈搭建项目、组织开发流程、管理多环境运行模式，以及建立质量检查体系。文中已脱敏处理，聚焦通用实践。

技术栈选型

技术	版本	选型理由
React	19	并发特性、Server Components 前沿能力
Ant Design	5	企业级 UI 组件库，Design Token 体系完善
TypeScript	5.x	类型安全，大型项目必备
Vite	5.x	极速 HMR，原生 ESM 支持，构建性能优秀

一、项目结构总览

一个规范的企业级前端项目，目录结构应按职责清晰划分：

bash 复制代码

project-root/
├── src/                  # 业务源码
│   ├── api/              # API 请求层
│   ├── components/       # 公共组件
│   ├── hooks/            # 共享 Hooks
│   ├── layouts/          # 布局组件
│   ├── models/           # 数据模型
│   ├── pages/            # 页面模块
│   ├── services/         # 业务流程层
│   ├── stores/           # 状态管理
│   ├── styles/           # 全局样式
│   ├── constants/        # 常量定义
│   ├── events/           # 事件通道
│   ├── lib/              # 工具库
│   ├── router/           # 路由配置
│   └── runtime/          # 运行时配置
├── mock/                 # Mock 数据与接口替身
├── __tests__/            # 单元测试
├── scripts/              # 构建与维护脚本
├── docs/                 # 项目文档
├── public/               # 静态资源
├── .env                  # 基础环境变量
├── .env.mock             # Mock 模式环境变量
├── .env.staging          # 构建部署环境变量
└── package.json

核心原则：

src/ 只放浏览器端业务代码
mock/ 只放接口替身和 Mock 数据
__tests__/ 按功能模块组织测试
docs/ 按主题归类文档
不使用 src/utils/，通用工具统一进入 src/lib/

二、常用命令速查

以 package.json 中定义的脚本为准：

bash 复制代码

# 开发
npm install              # 安装依赖
npm run dev              # 启动本地开发服务（代理模式）
npm start                # 等同于 npm run dev
npm run mock             # 启动 Mock 模式开发服务

# 构建
npm run build            # 执行正式部署构建
npm run build:backend    # 使用 staging 模式构建部署产物
npm run pack             # 构建并打包为部署交付压缩包

# 质量检查
npm run typecheck        # TypeScript 类型检查
npm run lint             # ESLint 检查
npm run lint:fix -- <文件>  # ESLint 自动修复
npm run format -- <文件>    # Prettier 格式化
npm test                 # 运行单元测试
npm run verify:quality   # 依次执行 typecheck + lint + test

三、多环境运行模式

企业级项目通常需要支持多种运行模式，以适应不同的开发和调试场景。

3.1 环境变量管理

Vite 通过 .env 文件管理环境变量，只有 VITE_ 前缀的变量会暴露给浏览器端：

bash 复制代码

# .env（基础配置，所有模式共享）
VITE_API_BASE_URL=/api
VITE_APP_TITLE=My Application

# .env.local（本地覆盖，不提交到仓库）
VITE_API_BASE_URL=http://192.168.1.100:8080/api

3.2 三种运行模式

模式	启动方式	环境文件	适用场景
代理模式	`npm run dev`	`.env` + `.env.local`	内网联调，请求代理到后端服务
Mock 模式	`npm run mock`	`.env` + `.env.mock`	本地开发、离线验证、回归检查
构建模式	`npm run build`	`.env` + `.env.staging`	生成部署产物，接入真实后端

3.3 Mock 模式的实现

Mock 模式的核心是通过 vite-plugin-mock 拦截 API 请求，返回预设数据：

typescript 复制代码

// mock/user.ts
import { MockMethod } from 'vite-plugin-mock'

export default [
  {
    url: '/api/current-user',
    method: 'get',
    response: () => ({
      id: '001',
      name: '测试用户',
      roles: ['admin'],
    }),
  },
] as MockMethod[]

关键约束：

Mock 数据只服务本地开发和验证，不作为正式数据源
接入后端接口时必须同步补充同路径 Mock
Mock 实现不需要编写单元测试

3.4 开发代理配置

在 vite.config.ts 中配置代理，将请求转发到后端服务：

typescript 复制代码

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: process.env.VITE_BACKEND_HOST || 'http://localhost:3000',
        changeOrigin: true,
      },
    },
  },
})

四、构建与部署

4.1 构建产物

命令	产物	说明
`npm run build`	`dist/`	标准构建产物
`npm run build:backend`	`dist/` + `manifest.json`	带资源清单的构建产物
`npm run pack`	`output/deploy.zip`	构建 + 打包为部署压缩包

4.2 Manifest 文件

manifest.json 记录构建产物的资源映射关系，供后端框架（如 Node SSR、Java Thymeleaf）引用：

json 复制代码

{
  "src/main.tsx": {
    "file": "assets/main-[hash].js",
    "css": ["assets/main-[hash].css"]
  },
  "index.html": {
    "file": "index.html"
  }
}

4.3 部署注意事项

构建产物只表达前端静态资源，不包含后端集成逻辑
部署前确认环境变量已正确配置
生产构建默认启用代码分割和资源哈希

五、质量检查体系

5.1 检查流程

提交代码前，按改动范围运行定向检查：

bash 复制代码

代码改动 → TypeScript 检查 → ESLint 检查 → 单元测试 → 提交

bash 复制代码

# 完整质量检查（CI 或发版前）
npm run verify:quality

# 日常开发：定向检查
npm run typecheck
npm run lint
npm test

5.2 自动修复

bash 复制代码

# ESLint 自动修复（指定文件）
npm run lint:fix -- src/pages/user/api.ts

# Prettier 格式化（指定文件）
npm run format -- src/pages/user/api.ts

注意：自动修复后必须 review 实际 diff，不要因为命令执行成功就跳过检查。

5.3 测试策略

采用最小影响链路原则：

页面改动 → 运行 boundaries/ 基线测试
共享逻辑改动 → 扩大到受影响模块的测试
全局能力改动 → 扩大到相关页面和组件的定向测试

bash 复制代码

# 运行边界测试（所有 src 改动的固定基线）
npm run test:unit:boundaries

# 运行指定模块测试
npm run test:unit -- --dir api-request

5.4 ESLint 与 Prettier 配置

javascript 复制代码

// eslint.config.js（Flat Config 格式）
import js from '@eslint/js'
import tseslint from 'typescript-eslint'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': ['warn', { allow: ['warn', 'error'] }],
    },
  },
]

javascript 复制代码

// prettier.config.js
export default {
  semi: false,
  singleQuote: true,
  trailingComma: 'all',
  printWidth: 100,
}

六、开发规范要点

6.1 代码分层

业务代码按职责严格分层：

层	目录	职责	禁止
API	`src/api/`	请求发送、DTO 转换	业务流程逻辑
Services	`src/services/`	业务流程编排	DOM 操作
Stores	`src/stores/`	状态管理	请求逻辑
Models	`src/models/`	数据模型定义	UI 渲染
Pages	`src/pages/`	页面组合	可复用业务逻辑

6.2 文件命名

目录：kebab-case（如 incident-ledger/）
组件文件：PascalCase（如 UserAvatar.tsx）
工具文件：kebab-case（如 date-utils.ts）
类型文件：kebab-case（如 user-types.ts）

6.3 接口规范

使用统一的 API 响应格式：

typescript 复制代码

// 统一响应格式
type ApiResponse<T> = {
  code: number
  message: string
  data: T
}

// API 请求层示例
async function fetchUserList(params: UserQuery): Promise<ApiResponse<User[]>> {
  return request.get('/api/users', { params })
}

6.4 错误处理

typescript 复制代码

// 统一错误处理
async function safeRequest<T>(fn: () => Promise<T>): Promise<[T | null, Error | null]> {
  try {
    const data = await fn()
    return [data, null]
  } catch (error) {
    console.error('Request failed:', error)
    return [null, error as Error]
  }
}

七、环境变量清单

变量名	用途	使用位置
`VITE_API_BASE_URL`	API 基础路径	请求层
`VITE_BACKEND_HOST`	后端服务地址	开发代理
`VITE_APP_TITLE`	应用标题	HTML 模板
`VITE_DEPLOY_NAME`	部署名称	构建产物目录

只使用 VITE_ 前缀变量，确保不会泄露服务端密钥到浏览器端。

八、常见问题

Q1: Mock 模式下接口返回 404

检查 Mock 文件的 url 是否与实际请求路径一致，确保 Mock 文件已正确导出。

Q2: TypeScript 检查报错但编辑器不报错

运行 npm run typecheck 确认，编辑器可能需要重启 TypeScript 服务。

Q3: 构建产物过大

检查是否有未使用的依赖，使用 npx vite-bundle-visualizer 分析打包产物。

Q4: 代理模式请求超时

确认 VITE_BACKEND_HOST 配置正确，检查网络连通性和防火墙设置。

总结

一个规范的企业级前端项目应该具备：

清晰的目录结构：按职责划分，每个目录有明确的边界
多环境支持：代理模式、Mock 模式、构建模式各有适用场景
自动化质量检查：TypeScript + ESLint + Prettier + 单元测试
统一的代码分层：API → Services → Stores → Models → Pages
完善的文档体系：入口文档驱动，变更同步更新

这些实践的核心目标是：让正确的做法成为阻力最小的做法。当规范足够清晰、工具足够好用时，团队自然会遵循，而不是靠口头约束。

本文基于 React 19 + Ant Design 5 + TypeScript + Vite 技术栈，适用于中大型企业级前端项目。具体配置可根据团队实际情况调整。