本文以一个真实企业级前端项目的开发实践为基础分享如何基于 React 19 Ant Design 5 TypeScript Vite 技术栈搭建项目、组织开发流程、管理多环境运行模式以及建立质量检查体系。文中已脱敏处理聚焦通用实践。技术栈选型技术版本选型理由React19并发特性、Server Components 前沿能力Ant Design5企业级 UI 组件库Design Token 体系完善TypeScript5.x类型安全大型项目必备Vite5.x极速 HMR原生 ESM 支持构建性能优秀一、项目结构总览一个规范的企业级前端项目目录结构应按职责清晰划分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_TITLEMy Application# .env.local本地覆盖不提交到仓库VITE_API_BASE_URLhttp://192.168.1.100:8080/api3.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 请求返回预设数据// mock/user.tsimport{MockMethod}fromvite-plugin-mockexportdefault[{url:/api/current-user,method:get,response:()({id:001,name:测试用户,roles:[admin],}),},]asMockMethod[]关键约束Mock 数据只服务本地开发和验证不作为正式数据源接入后端接口时必须同步补充同路径 MockMock 实现不需要编写单元测试3.4 开发代理配置在vite.config.ts中配置代理将请求转发到后端服务exportdefaultdefineConfig({server:{proxy:{/api:{target:process.env.VITE_BACKEND_HOST||http://localhost:3000,changeOrigin:true,},},},})四、构建与部署4.1 构建产物命令产物说明npm run builddist/标准构建产物npm run build:backenddist/manifest.json带资源清单的构建产物npm run packoutput/deploy.zip构建 打包为部署压缩包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 lintnpmtest5.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-request5.4 ESLint 与 Prettier 配置// eslint.config.jsFlat Config 格式importjsfromeslint/jsimporttseslintfromtypescript-eslintexportdefault[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 代码分层业务代码按职责严格分层层目录职责禁止APIsrc/api/请求发送、DTO 转换业务流程逻辑Servicessrc/services/业务流程编排DOM 操作Storessrc/stores/状态管理请求逻辑Modelssrc/models/数据模型定义UI 渲染Pagessrc/pages/页面组合可复用业务逻辑6.2 文件命名目录kebab-case如incident-ledger/组件文件PascalCase如UserAvatar.tsx工具文件kebab-case如date-utils.ts类型文件kebab-case如user-types.ts6.3 接口规范使用统一的 API 响应格式// 统一响应格式typeApiResponseT{code:numbermessage:stringdata:T}// API 请求层示例asyncfunctionfetchUserList(params:UserQuery):PromiseApiResponseUser[]{returnrequest.get(/api/users,{params})}6.4 错误处理// 统一错误处理asyncfunctionsafeRequestT(fn:()PromiseT):Promise[T|null,Error|null]{try{constdataawaitfn()return[data,null]}catch(error){console.error(Request failed:,error)return[null,errorasError]}}七、环境变量清单变量名用途使用位置VITE_API_BASE_URLAPI 基础路径请求层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 技术栈适用于中大型企业级前端项目。具体配置可根据团队实际情况调整。