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

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

技术栈选型

一、项目结构总览

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

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中定义的脚本为准：

# 开发npminstall# 安装依赖npmrun dev# 启动本地开发服务（代理模式）npmstart# 等同于 npm run devnpmrun mock# 启动 Mock 模式开发服务# 构建npmrun build# 执行正式部署构建npmrun build:backend# 使用 staging 模式构建部署产物npmrun pack# 构建并打包为部署交付压缩包# 质量检查npmrun typecheck# TypeScript 类型检查npmrun lint# ESLint 检查npmrun lint:fix --<文件># ESLint 自动修复npmrunformat--<文件># Prettier 格式化npmtest# 运行单元测试npmrun verify:quality# 依次执行 typecheck + lint + test

三、多环境运行模式

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

3.1 环境变量管理

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

# .env（基础配置，所有模式共享）VITE_API_BASE_URL=/apiVITE_APP_TITLE=My Application# .env.local（本地覆盖，不提交到仓库）VITE_API_BASE_URL=http://192.168.1.100:8080/api

3.2 三种运行模式

3.3 Mock 模式的实现

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

// mock/user.tsimport{MockMethod}from'vite-plugin-mock'exportdefault[{url:'/api/current-user',method:'get',response:()=>({id:'001',name:'测试用户',roles:['admin'],}),},]asMockMethod[]

关键约束：

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

3.4 开发代理配置

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

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

四、构建与部署

4.1 构建产物

4.2 Manifest 文件

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

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

4.3 部署注意事项

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

五、质量检查体系

5.1 检查流程

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

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

# 完整质量检查（CI 或发版前）npmrun verify:quality# 日常开发：定向检查npmrun typechecknpmrun lintnpmtest

5.2 自动修复

# ESLint 自动修复（指定文件）npmrun lint:fix -- src/pages/user/api.ts# Prettier 格式化（指定文件）npmrunformat-- src/pages/user/api.ts

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

5.3 测试策略

采用最小影响链路原则：

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

# 运行边界测试（所有 src 改动的固定基线）npmrun test:unit:boundaries# 运行指定模块测试npmrun test:unit ----dirapi-request

5.4 ESLint 与 Prettier 配置

// eslint.config.js（Flat Config 格式）importjsfrom'@eslint/js'importtseslintfrom'typescript-eslint'exportdefault[js.configs.recommended,...tseslint.configs.recommended,{rules:{'@typescript-eslint/no-explicit-any':'warn','no-console':['warn',{allow:['warn','error']}],},},]

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

六、开发规范要点

6.1 代码分层

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

6.2 文件命名

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

6.3 接口规范

使用统一的 API 响应格式：

// 统一响应格式typeApiResponse<T>={code:numbermessage:stringdata:T}// API 请求层示例asyncfunctionfetchUserList(params:UserQuery):Promise<ApiResponse<User[]>>{returnrequest.get('/api/users',{params})}

6.4 错误处理

// 统一错误处理asyncfunctionsafeRequest<T>(fn:()=>Promise<T>):Promise<[T|null,Error|null]>{try{constdata=awaitfn()return[data,null]}catch(error){console.error('Request failed:',error)return[null,errorasError]}}

七、环境变量清单

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

八、常见问题

Q1: Mock 模式下接口返回 404

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

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

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

Q3: 构建产物过大

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

Q4: 代理模式请求超时

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

总结

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

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

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

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