企业官网建设流程全解析

这篇是《使用vite+react+ts+Ant Design开发后台管理项目》系列文章的第4篇。前三篇我们把项目初始化、目录结构、布局菜单、路由拆解、状态管理这些基础工作做完了，项目已经能跑起来，页面也能正常跳转。但这会儿往往是最慌的时候：登录之后的权限怎么做？接口怎么统一封装？页面要上图表、要适配大屏怎么办？最后怎么区分测试环境打包？这些都属于“项目能跑”和“项目能上线”之间的硬骨头，也是本篇要解决的问题。

我默认你已经有一份 Vite + React + TypeScript + Ant Design 5 的可用项目，如果是从零开始，建议先把前三篇的基础搭完再来读这篇。这篇的内容更偏实战，我会直接把方案、代码和踩过的坑一起放出来，方便直接抄作业。

1. 权限控制：先拆掉“假权限”，再做动态路由

1.1 先把权限模型想清楚，再写代码

后台管理系统的权限，表面上看起来是“登录之后显示哪些菜单”，实际上包含三层：第一层是路由能不能访问，第二层是菜单能不能看到，第三层是按钮点不了。这三层如果全在前端写死，那叫假权限。碰上稍微讲究一点的项目，光登录后返回一个用户角色根本不够用。

我比较推荐的做法是基于 RBAC 的简化版：用户登录后，后端返回当前用户的权限码列表，比如['system:user:list', 'system:role:add']，前端拿这串权限码去匹配路由表和菜单表。路由表里能找到且有权限的，才挂载到路由实例上；菜单只渲染有权限的路由；按钮通过组件或自定义 Hook 判断权限码是否存在。

为什么不用角色直接判断？因为项目一旦变大，角色和菜单的对应关系会非常容易被改乱。权限码是原子化的，一个接口对应一个权限点，不管角色怎么变，前端只需要问“你有没有这个权限码”，逻辑简单清晰。你可以把权限码理解成钥匙，角色只是一个装钥匙的钥匙串，真正开门时看的是钥匙，不是钥匙串。

这里需要特别注意类型约束。权限码最好用 TypeScript 的字符串字面量联合类型维护，而不是散落的魔法字符串：

export type PermissionCode = | 'dashboard:view' | 'system:user:list' | 'system:user:add' | 'system:role:list' | 'system:role:update'; export interface AuthUser { id: string; name: string; permissions: PermissionCode[]; }

这样写的好处是，后续写路由 meta、写按钮组件时都有类型提示，权限码拼错直接编译报错，不用等上线后才发现某个按钮显示错了。这也是 TypeScript 在后台项目里最大的价值之一。

1.2 动态路由生成与刷新白屏

静态路由好做，直接在 router 里createBrowserRouter配完就行。问题出在动态路由：不同用户登录进去看到的菜单不同，这意味着路由表不能一次性全部注册，必须登录后根据权限动态挂载。

我的实现思路分三步。第一步，把所有需要权限的路由放在一个单独的asyncRoutes数组里，每个路由的 meta 上标记需要的权限码。第二步，登录后请求用户信息，拿到权限码列表，过滤出用户能访问的路由。第三步，用router.addRoute逐个挂载。

这里有个特别容易踩的坑：Vite 动态导入文件名不能纯变量，否则打包出来的 chunk 会被拆得乱七八糟，严重时会变成每个文件单独一个 chunk。建议用import.meta.glob统一读取页面模块：

const modules = import.meta.glob('@/pages/**/*.tsx');

然后通过路径匹配到对应的加载函数，比如modules[@/pages${route.component}.tsx]。这样既能保证路由组件被正确分包懒加载，也不会出现开发环境正常、生产环境白屏的问题。

刷新白屏是另一个高频问题。原因很好理解：页面刷新后，pinia里的用户信息被清空了，路由守卫一进来发现没有权限码，直接把用户踢回登录页，或者因为路由还没挂载完成导致找不到路径。解决办法是把用户信息和权限码持久化到 localStorage，刷新时先恢复再进路由。或者更稳妥一点，在路由守卫里判断当前路由是否已经在动态路由表中，不在就重新生成一次动态路由：

router.beforeEach(async (to, _from, next) => { const userStore = useUserStore(); if (!userStore.token) { if (to.path === '/login') return next(); return next(`/login?redirect=${encodeURIComponent(to.fullPath)}`); } if (userStore.routesLoaded) return next(); try { const routes = await userStore.generateRoutes(); routes.forEach((route) => router.addRoute(route)); return next({ ...to, replace: true }); } catch (error) { userStore.reset(); return next('/login'); } });

注意next({ ...to, replace: true })这一段。如果不写，路由刚添加完就立即next()，有可能因为路由匹配已经结束了，导致跳转目标仍然是原来的空白页。加一次重定向，让 Vue Router 重新匹配一次新挂载的路由，刷新白屏问题基本就没了。

1.3 按钮级权限：React 里别用指令思维

从若依这类 Vue 后台管理系统转过来的同学，容易习惯性地想做类似v-permission的自定义指令。React 没有指令的概念，硬要做也能搞，但更自然的方案是封装成组件。

import type { PermissionCode } from '@/types/auth'; interface AuthProps { permission: PermissionCode; children: React.ReactNode; } export default function Auth({ permission, children }: AuthProps) { const hasPermission = useAuthPermission(permission); if (!hasPermission) return null; return <>{children}</>; }

使用的时候很简单：

<Auth permission="system:user:add"> <Button type="primary">新增用户</Button> </Auth>

再往外延伸一点，可以封装一个useAuthPermissionHook，判断逻辑集中在里面。这样临时写着玩的小页面可以用 Hook，正式页面用组件，整个权限判断链路在代码里一眼就能看清。

还要提醒一句：前端按钮禁用不等于后端接口安全，真正重要的是后端接口做权限校验。前端隐藏按钮只是提升体验，别把安全希望寄托在这层。

2. 请求层：封装 axios 时把类型和安全一起解决

2.1 axios 实例与拦截器设计

后台管理系统里接口调用频率很高，如果每个页面都单独写axios.post的完整配置，项目后期改 API 域名或者加公共参数时就非常痛苦。我的习惯是工程项目启动后第一件事，就是把请求层封装好。

axios 实例基础配置如下：

import axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios'; const service: AxiosInstance = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || '/api', timeout: 15000, });

请求拦截器里通常只做两件事：带 token、带必要的公共参数。响应拦截器里做的事情多一点：统一处理 HTTP 错误码、处理业务 Code、处理 token 过期。业务 Code 的处理是重点，我见过很多项目把业务失败和网络失败混在一起处理，页面里每个接口都要写if (res.code !== 200)，这是灾难。

我这边的约定是：HTTP 状态 200 时，再看业务code，非 2xx 时统一弹出错误提示，只在特定场景下放开。核心代码如下：

service.interceptors.response.use( (response) => { const res = response.data; if (res.code !== 0) { if (res.code === 401) { // 登录过期，清理本地状态并跳转登录页 return Promise.reject(new Error('登录已过期')); } message.error(res.message || '请求失败'); return Promise.reject(new Error(res.message || '请求失败')); } return res; }, (error) => { message.error(error.message || '网络异常'); return Promise.reject(error); } );

这里我把业务成功的code定成了0，不同项目可能用200或'000000'，关键是全公司统一。如果后端接口还没规范好，前端可以在拦截器层面做一层兼容，避免页面代码被后端的小变动反复改。

2.2 用泛型和自定义 Hook 让请求有类型、有状态

axios 自带泛型支持，但它默认的response.data类型是any，这会让 TypeScript 在接口层形同虚设。我一般会封装一个带泛型的请求方法，把响应体结构和业务数据类型彻底分开：

export interface ApiResponse<T = unknown> { code: number; message: string; data: T; } export function request<T>(config: AxiosRequestConfig): Promise<T> { return service.request<ApiResponse<T>>(config).then((res) => res.data.data); }

调用时直接指定业务数据类型：

interface UserItem { id: string; name: string; email: string; } const userList = await request<UserItem[]>({ url: '/user/list', method: 'get', });

此时userList的类型是UserItem[]，所有字段都有提示，再往前端页面传参时不容易写错。这就是 ts 泛型的实际价值，不是用来炫技的，是为了让接口数据在代码里流动时类型不丢失。

时间久了你会发现，页面组件里大量重复的 loading、error、data 状态管理非常枯燥，而且很容易忘记在请求结束时恢复 loading。我会抽一个useRequestHook，把请求状态统一管理起来：

function useRequest<T>(fetcher: () => Promise<T>, deps: unknown[] = []) { const [data, setData] = useState<T | null>(null); const [loading, setLoading] = useState(false); const [error, setError] = useState<Error | null>(null); const run = useCallback(async () => { setLoading(true); setError(null); try { const result = await fetcher(); setData(result); } catch (e) { setError(e as Error); } finally { setLoading(false); } }, deps); useEffect(() => { run(); }, [run]); return { data, loading, error, refresh: run }; }

这里要注意一个很隐蔽的问题：组件卸载后请求才返回，此时再setState会触发 React 的警告，严重的还会造成数据竞争。处理方式是在 Hook 内部加一个mounted标志位，或者用AbortController在卸载时取消未完成的请求。最简单可靠的方案是加一个 mounted 判断：

useEffect(() => { let isMounted = true; // 请求完成后判断 if (isMounted) setData(result); return () => { isMounted = false; }; }, []);

2.3 Mock 环境：让后端还没写好接口也能开工

很多团队开发后台管理时前后端并行，前端依赖的接口还没写，老办法是写死数据，等后端接口出来再一个个替换，效率极低。现在的主流做法是本地 Mock。

Vite 生态里我用得比较多的是vite-plugin-mock，它支持在本地开发环境里拦截请求，按 Mock 文件直接返回模拟数据，而且和真实请求的代码写法一致，后端接口开发完成后只需要关掉 Mock，前端页面代码一行不用改。

配置非常简单：

import { viteMockServe } from 'vite-plugin-mock'; export default defineConfig({ plugins: [ viteMockServe({ mockPath: 'mock', enable: true, }), ], });

Mock 文件就放在mock目录下，比如mock/user.ts：

export default [ { url: '/api/user/list', method: 'get', response: () => ({ code: 0, data: [ { id: '1', name: '张三', email: 'zhangsan@example.com' }, { id: '2', name: '李四', email: 'lisi@example.com' }, ], message: 'ok', }), }, ];

这里有个坑需要提醒：Mock 是以请求路径匹配的，如果 axios 的baseURL配置了/api，那么 Mock 的 url 也要写/api/user/list，否则匹配不上。很多同学从 Vue3 的 Mock 教程迁移过来时报错，十有八九是路径前缀对不上。另外，Mock 只用于开发环境，生产构建时一定不要开启，最好用环境变量控制enable，不要图省事直接写死true。

3. 图表与大屏：后台管理系统的高级感往往在这里

3.1 ECharts 按需引入与组件封装

后台管理系统里，图表几乎是刚需。数据看板、报表分析、销售趋势，这些页面一上 ECharts，整体质感立刻不一样。但 ECharts 全量引入的体积太大了，首屏加载会白白多出 1MB 以上的 JS。正确的做法是按需注册。

ECharts 5 以后推荐用echarts/core方式引入：

import * as echarts from 'echarts/core'; import { BarChart, LineChart, PieChart } from 'echarts/charts'; import { GridComponent, TooltipComponent, LegendComponent, DataZoomComponent, } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers'; echarts.use([ BarChart, LineChart, PieChart, GridComponent, TooltipComponent, LegendComponent, DataZoomComponent, CanvasRenderer, ]);

具体项目用了哪些图表类型，就在use里注册哪些。不要一次性全注册，那和全量引入没区别。SVG 渲染器和 Canvas 渲染器也需要选一个，后台大数据量图表用 Canvas，普通交互图表用 SVG 更轻。

React 里封装一个通用 Chart 组件，比每个页面自己init、setOption要干净得多：

interface ChartProps { option: echarts.EChartsCoreOption; height?: number; } function Chart({ option, height = 400 }: ChartProps) { const containerRef = useRef<HTMLDivElement>(null); const chartRef = useRef<echarts.EChartsType | null>(null); useEffect(() => { if (!containerRef.current) return; chartRef.current = echarts.init(containerRef.current); const observer = new ResizeObserver(() => { chartRef.current?.resize(); }); observer.observe(containerRef.current); return () => { observer.disconnect(); chartRef.current?.dispose(); }; }, []); useEffect(() => { chartRef.current?.setOption(option); }, [option]); return <div ref={containerRef} style={{ width: '100%', height }} />; }

这个组件解决了一个很常见的 UI 问题：图表容器在 Tab 切换、抽屉打开、列表展开时，宽度从 0 变成有值，图表如果不 resize 就会画得很奇怪。通过ResizeObserver监听容器尺寸变化，就能自动触发chart.resize()，不用每次切换都手动调用。

需要注意dispose必须写在清理函数里，否则组件卸载后 ECharts 实例还挂在内存中，页面频繁切换会出现卡顿甚至崩溃。这是 React 图表组件最容易忽略的性能问题。

3.2 大屏适配：vw/vh 换算比 rem 更省心

大屏项目是后台管理系统的一个常见变体，数据监控大屏、指挥调度大屏，用的还是 React + ECharts 这一套。大屏适配最烦人，不同分辨率的屏幕显示效果天差地别。

目前主流的适配方案有这么几种，我直接对比一下：

我个人的项目里用得最多的是 vw/vh 方案。设计稿一般是 1920 x 1080，开发时把设计稿里的像素值直接换算成 vw。比如设计稿上一个模块宽度是 480px，那对应480 / 1920 * 100 = 25vw。手动换算太累，我直接配postcss-px-to-viewport插件，写代码时继续用 px：

// postcss.config.js export default { plugins: { 'postcss-px-to-viewport': { viewportWidth: 1920, viewportHeight: 1080, unitPrecision: 3, viewportUnit: 'vw', fontViewportUnit: 'vw', selectorBlackList: ['.ignore-'], }, }, };

这样写width: 480px编译后会自动变成width: 25vw。注意viewportHeight只对 vh 单位生效，默认情况下宽度方向的 vw 才是主力。遇到不想被换算的样式，加一个.ignore-前缀就行。

有个坑必须提醒：postcss 插件只处理 CSS 文件里的 px，ECharts option 里的数字大小（比如fontSize: 12）是不会被自动换算的。大屏上的图表文字要想跟上缩放，需要在配置 option 时传入一个换算函数，或者在 window resize 时重新计算字号并setOption。所以大屏页面我通常把图表初始化和适配逻辑单独封装，避免在页面组件里堆一大堆重复代码。

3.3 图表的尺寸陷阱与 resize 处理

图表还有一个非常典型的坑：容器初始化时是隐藏的（比如在 Tabs 的第二个页签里），切过来再渲染，ECharts 拿到的容器宽度是 0，画出来就是一团糊。这个问题不仅在后台管理系统里常见，做 react 大屏时也容易出现。

解决办法之一是不要在容器隐藏时初始化，等 Tab 激活后再渲染图表；但这样每次切换都要重新初始化，体验一般。更好的办法是用ResizeObserver，容器从隐藏变为显示时，尺寸变化会触发回调，这时调用chart.resize()重新计算。

如果容器始终保持display: none，ResizeObserver 可能不会触发，这时候只能再补一招：在 Tab 切换后手动调用一次resize。所以我把 Chart 组件里的 chart 实例暴露出来，方便外面调用：

useImperativeHandle(ref, () => ({ resize: () => chartRef.current?.resize(), }));

另外，图表频繁 resize 会引发性能问题，尤其是数据量大、动画效果多的图表。ResizeObserver 回调里加个防抖会稳妥一些，我一般用setTimeout到 200ms 再执行 resize，屏幕拖动的时候不会密集触发。这个细节很少出现在教程里，但实际大屏项目中非常管用。

4. 多环境构建与上线优化：从 npm run dev 到部署不慌

4.1 环境变量与 vite build --mode test 到底怎么用

后台管理系统开发到后期，一定会遇到环境问题：本地开发环境用测试接口，测试环境用测试接口但日志要全开，生产环境用正式接口还要关掉日志。如果每次上线前手动改代码里的接口地址，太容易出事故。

Vite 的方案是环境变量文件加 mode。Vite 启动时默认读取.env、.env.development、.env.production等文件，文件名里的后缀就对应 mode。你可以额外定义一个测试环境的 mode，比如：

# .env.test VITE_APP_TITLE=后台管理系统-测试环境 VITE_API_BASE_URL=/api

然后在package.json里加一条命令：

{ "scripts": { "dev": "vite", "build": "vite build", "build:test": "vite build --mode test" } }

执行npm run build:test时，Vite 会加载.env.test文件，同时import.meta.env.MODE的值就是test。使用方式：

const baseURL = import.meta.env.VITE_API_BASE_URL; const isTest = import.meta.env.DEV; const isProd = import.meta.env.PROD;

这里有一个容易踩的坑：很多人会把process.env.NODE_ENV的习惯带进来，在 Vite 项目里写process.env.VITE_XXX，结果取到 undefined。Vite 项目里读环境变量要用import.meta.env，带VITE_前缀的变量会直接暴露给前端代码。没有前缀的变量不会自动暴露，要注意。

还有，vite build --mode test加载的是.env.test，但import.meta.env.DEV和import.meta.env.PROD是根据NODE_ENV判断的，build 时NODE_ENV是production，所以即使 mode 是 test，import.meta.env.PROD仍然是true。这个细节在判断是否加日志、是否开 Mock 时特别重要，不要以为 mode 是 test 就代表非生产。

4.2 拆包、Gzip 和缓存策略

项目上线后打开控制台看 Network，如果首屏最多的那个 JS 文件有 2MB 以上，说明默认打包配置没有优化。Vite 基于 Rollup，手动拆包并不复杂。

一个后台管理项目最大头通常是三块：React 全家桶、Ant Design 组件库、ECharts 图表库。这三块基本不会频繁变，可以把它们单独拆出来，让浏览器缓存得更久；业务代码频繁改，只缓存一小块就够了。

build: { rollupOptions: { output: { manualChunks: { react: ['react', 'react-dom', 'react-router-dom'], antd: ['antd', '@ant-design/icons'], echarts: ['echarts', 'echarts/core', 'echarts/charts', 'echarts/components'], }, }, }, },

打包之后，这些第三方库会形成独立的 chunk，配合上 gzip 压缩，体积能再降一大截。Vite 压缩 gzip 我用vite-plugin-compression：

import viteCompression from 'vite-plugin-compression'; plugins: [ viteCompression({ algorithm: 'gzip', ext: '.gz', threshold: 10240, }), ],

这里threshold: 10240表示只有超过 10KB 的文件才压缩，避免一堆小文件压缩后反而更占空间。如果服务端配置了 br 压缩，也可以生成.br文件，权衡优先级是 br > gzip，但浏览器兼容性更好的是 gzip，我一般两个都开，让服务端根据Accept-Encoding自己选。

静态资源缓存方面，Vite 默认会给带 hash 的静态资源设置immutable缓存，文件名一变 hash 就变，不会出现改代码不生效的问题。真正要防的是index.html被缓存，那样无论怎么重新打包，用户拿到的还是旧页面。上线时index.html要设置为no-cache，这是一个容易忽略但影响很大的细节。

4.3 上线前必须检查的五个点

我在给团队做内部培训时常说，上线前的检查不是靠感觉，而是靠清单。下面这五个点是我踩过坑之后整理出来的，分享出来供你参考。

第一，路由模式。如果用的是BrowserRouter（history 模式），部署在 Nginx 时必须配置try_files，否则用户直接访问某个子路由或者刷新子路由时会出现 404。Nginx 里只需要加一句try_files $uri $uri/ /index.html;。如果部署在子路径下，还要设置 Vite 的base和路由的basename，不然静态资源路径会全部错乱。

第二，环境变量。确认VITE_API_BASE_URL在当前构建环境里指向了正确的接口地址，尤其是打包测试环境给客户演示时，接口地址串了会很尴尬。构建后可以打开dist里的 JS 文件搜一下接口域名，确认是预期环境。

第三，sourcemap。默认情况下 Vite build 不生成 sourcemap，但如果有人改过配置，把build.sourcemap开成了 true，那打包出来的源码是会泄密的。生产构建一定要关掉，或者只在排障时临时打开。排查接口报错需要定位源码时，用错误日志里的堆栈信息对应到源码版本就足够了。

第四，console 日志。开发时到处console.log很爽，但上线后这些日志既影响性能也显得不专业。可以借助vite-plugin-remove-console之类的插件在生产构建时统一移除，注意不要在生产环境继续打印敏感信息。

第五，接口错误提示。点开一个页面，如果接口报错弹出一堆重复的 message，那用户体验很糟糕。检查响应拦截器是否对相同错误做了去重或限流处理，登录过期时是否只跳转一次登录页，别让用户点一次按钮弹八个“网络异常”。

最后分享一点个人体会

从 Vite + React + TS + Ant Design 这套技术栈做后台管理系统，最大的优势不是单个库有多强，而是组合之后开发体验非常顺滑。TypeScript 把数据流里的类型问题提前暴露在编译期，Vite 把开发启动速度拉满，Ant Design 把常用组件补齐，ECharts 把可视化兜住。技术选型不是越新越好，而是要能解决实际项目里反复出现的痛点。

我做了这么多后台项目，最大的感受是：框架本身其实不复杂，复杂的是如何把权限、请求、构建这些“工程问题”在项目初期就设计好。很多项目前期跑得飞快，后面越改越乱，往往是因为第一版只写了功能，没有留出工程化设计的位置。第四篇先把这几块硬骨头啃掉，后续加新页面、接新接口就会轻松很多。