企业官网建设流程全解析

后台管理系统做到第四期，脚手架、布局、登录这些基础能力已经齐了，真正开始触碰这块硬骨头的深水区。vite + React + TypeScript + Ant Design 这套组合在技术选型上没什么争议，但选型正确不代表项目就一定顺畅。这段时间我在项目里处理了几件非常具体的事：界面在不同分辨率下怎么保持可用而不是死板地缩放、菜单权限数据从前端硬编码改成接口下发、一堆跨页面共享的状态怎么管理才不脏，以及多环境构建时的各种边界问题。这篇把这几块的做法和踩坑记录整理出来，给正在做同类项目的朋友一些参考。

1. 别再裸用vw/vh：后台系统的自适应方案要这么做

后台管理系统的视觉适配，比大多数人想象中要麻烦。很多团队的做法是在全局样式里写html { font-size: calc(100vw / 19.2) }，然后所有尺寸都用 rem，试图把设计稿从 1920 等比缩放到任意屏幕。这个方案在有设计感的大屏展示页里确实有效，但用在表格密集型的后台页面上，反而是灾难。

1.1 为什么等比缩放不适合后台系统

后台页面的核心是表格、表单和列表。这类组件的特点是：内容密度高、信息层级多、交互区域有自己的最小可点击尺寸。当你把整张页面等比缩小到 1366 宽的屏幕上时，表格列会挤成一团，按钮里的文字开始折行，弹窗里的表单标签和输入框互相碰撞。

另一个问题是字号和容器高度的比例。后台系统默认 14px 字号在 1920 下很舒服，但如果跟着视口等比缩到 1280，实际渲染可能变成 9px，用户根本看不清。实际操作中，很多团队最后会发现，与其做等比缩放，不如做分级适配：当视口宽度掉到某个阈值时，调整侧边栏宽度、表格列展示策略、内容区间距，而不是把所有元素无脑缩小。

1.2 我在项目里落地的适配方案

我这边的设计稿基准是 1920 宽，目标环境包括 1366 笔记本、1920 显示器以及 2560 的宽屏。最终采用的是一套组合策略，而不是单一单位：

• 页面级的外层间距、卡片内边距，用clamp()控制，保证在超宽屏上留白不会无限增大，在小屏上也不会贴边。
• 表格内容区的高度用 JS 动态计算，减去顶部布局和分页器占用的高度，再赋给scroll={{ y }}，让表格自己在容器内滚动，而不是撑高整页。
• 栅格布局（Row/Col）只用于真正的响应式区域，比如统计卡片、图表排列，这部分用百分比由 antd 栅格接管。

外层间距的一个示例：

.page-container { padding: clamp(12px, 1.2vw, 24px); } .table-card { border-radius: 8px; overflow: hidden; }

表格高度计算的思路是用一个自定义 Hook，而不是在每个页面里重复写：

export function useTableHeight(extraOffset = 0) { const [tableHeight, setTableHeight] = useState(400); useEffect(() => { const calc = () => { const header = document.querySelector('.ant-layout-header'); const contentTop = document.querySelector('.page-header')?.getBoundingClientRect().height || 0; const pagination = 56; const padding = 24; const headerHeight = header?.clientHeight || 64; const height = window.innerHeight - headerHeight - contentTop - pagination - padding - extraOffset; setTableHeight(Math.max(300, height)); }; calc(); window.addEventListener('resize', calc); return () => window.removeEventListener('resize', calc); }, [extraOffset]); return tableHeight; }

然后在页面里这么用：

const tableHeight = useTableHeight(); // <Table scroll={{ y: tableHeight }} ... />

这样做的效果是，无论用户浏览器窗口怎么拉伸，表格的可视行数都会撑满剩余空间，而不是在页面底部留出一大块空白。这个方案比height: calc(100vh - 64px - 56px)更稳定的原因是，它把页面内可能存在的自定义头部高度也纳入计算，避免多算或少算。

1.3 大屏页面的特殊处理

单页大屏（比如数据可视化看板）和普通后台页面是两套逻辑。大屏页面从设计阶段就假定宽高比固定，所以它适合用 vw/vh 配合 flex/grid 做整体布局。这一块建议从项目里拆出去，单独用display: flex+flexBasis: 某个比例来做各区块的划分，而不是在全局 CSS 里动字号。

另外提一个隐蔽的坑：如果项目里同时用了 antd 的ConfigProvider主题定制和全局 rem 方案，Modal.confirm、message、notification这些挂载在 body 下的组件会脱离你的布局容器，字号样式和页面不一致。排查这种问题耗时很长，最好一开始就把适配方案分层：全局组件走主题变量，页面布局走独立适配。

2. 动态路由与菜单权限，前后端怎么把信息对准

后台管理系统的权限模块，做到后面基本上都会从"前端写死路由表"演进到"接口返回菜单权限，前端动态生成路由"。这个演进本身不复杂，真正复杂的是前后端两边的数据结构约定。

2.1 接口菜单数据的结构设计

我在项目里和后端约定的菜单数据结构长这样：

interface MenuItem { id: number; parentId: number | null; name: string; // 菜单显示名 path: string; // 路由地址 component: string; // 组件路径，相对 src/pages icon?: string; sort: number; children?: MenuItem[]; buttons?: string[]; // 该页面下允许使用的按钮权限码 }

关键点是component字段存的是组件文件的路径字符串，而不是组件本身。前端拿到这个字符串后，需要用动态导入机制把它映射成真正的 React 组件。这里首选import.meta.glob，它可以一次性收集所有页面组件，并按需加载，避免首屏打包整个 pages 目录。

2.2 把菜单数据转换成路由对象

先收集所有页面组件：

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

然后写一个转换函数，把接口的数组转成 React Router 的RouteObject[]：

import { lazy } from 'react'; import type { RouteObject } from 'react-router-dom'; function toComponent(componentPath: string) { if (!componentPath) return null; const fullPath = `/src/pages/${componentPath}.tsx`; const loader = modules[fullPath]; if (!loader) { console.warn(`[route] 未找到组件: ${fullPath}`); return null; } return lazy(() => loader() as Promise<{ default: React.ComponentType<any> }>); } export function transformRoutes(menuTree: MenuItem[]): RouteObject[] { return menuTree.map((menu) => { const element = toComponent(menu.component); return { path: menu.path, element: element ? <SafeComponent>{createElement(element)}</SafeComponent> : <Outlet />, children: menu.children?.length ? transformRoutes(menu.children) : undefined, }; }); }

这里有个重要的细节：如果某个component字段为空，说明这个菜单是嵌套的目录节点，不能给它绑定组件。我额外包了一个SafeComponent来做路由懒加载的兜底——因为React.lazy要求必须有Suspense包裹，否则组件未加载完成时会直接白屏报错。实际项目里我是把所有动态路由包在一个<Suspense fallback={<PageLoading />}>里，这个设计能避免一大批"路由点击后白屏"的线上问题。

function SafeComponent({ children }: { children: React.ReactNode }) { const [error, setError] = useState(false); if (error) return <Result status="500" title="页面加载失败" />; return <>{children}</>; }

2.3 刷新白屏的完整排查链路

动态路由做出来后，开发时一切正常，部署到测试环境就出现一个问题：用户按 F5 刷新页面，直接白屏。当时排查链路是这样的：

1. 先看控制台，发现请求用户信息接口后没有继续请求任何菜单接口。这说明路由表是空的，React Router 用通配符匹配到了 404，但页面没有渲染任何内容。
2. 继续看代码，发现根组件挂载时直接渲染了<RouterProvider>，而路由对象是在请求完用户信息后才生成的。刷新时，用户信息是异步的，路由表在首帧渲染时还没生成，于是匹配不上。
3. 解法是在全局的状态里加一个routeReady标志位。用户信息、菜单接口这两个 Promise 全部 resolve 之后，才把动态路由注入并渲染 Router。同时把基础路由（login、403、404、根路径重定向）放在一个静态路由表里，动态路由作为 child 拼进去。

核心伪代码：

// main.tsx async function bootstrap() { // 先请求用户信息、菜单 const [user, menus] = await Promise.all([ fetchUserInfo(), fetchUserMenus(), ]); store.setUser(user); const dynamicRoutes = transformRoutes(menus.data); const router = createRouter(staticRoutes, dynamicRoutes); root.render(<RouterProvider router={router} />); } bootstrap();

这套方案处理后，刷新时用户会先看到全局的 loading 页，等路由表 ready 再进入对应页面。虽然白屏时间变成了 loading 页面，但避免了路由失配，体验上是可以接受的。

2.4 按钮权限码的同步方案

菜单权限只解决了"能看到哪些页面"的问题，页面里的按钮（新增、编辑、删除）是另一套权限粒度，通常叫按钮权限码。这部分不需要走后端验权，前端在渲染时判断：

const { permissions } = useUserStore(); function can(code: string) { return permissions.includes(code); } // 使用 {can('system:user:create') && <Button type="primary">新增用户</Button>}

这里最需要注意的是权限码的全局唯一性。如果两个菜单下面出现相同的按钮操作，权限码会互相干扰。建议约定权限码格式为模块:页面:操作，比如system:user:create、order:audit:export，并和后端在接口文档里同步这个约定，避免出现中划线、大小写混用这类问题。

3. 状态管理不一定要上全家桶：zustand 在这类项目里的取舍

后台项目的状态管理，一直存在两极分化。老一些的项目喜欢上完整的状态库全家桶，新手项目则到处用 Context 传值。这两种方案在真实开发里都有各自的痛苦。我这边的建议是：后台管理项目用 zustand 这类轻量方案刚刚好。

3.1 后台系统到底哪些状态需要全局共享

以我目前这个后台项目为例，真正需要跨页面共享的状态其实不多：

除了这些，其他状态都应该留在组件内部。很多项目状态混乱的根源，是把"某个页面里要用的状态"错误提升成了"全局状态"，导致父子组件通信都被迫走全局 store，代码难以维护。

3.2 zustand 相比 Context 的优势在哪

如果用 React Context 管理用户信息，会有一个典型问题：当用户信息更新时，所有消费这个 Context 的组件都会重新渲染。即便你用useMemo包了 value，只要 Context value 变化，子组件依然整体刷新。这在组件树很深的列表页里会造成明显的卡顿。

zustand 的核心优势是细粒度的订阅机制。你用它提供的 Hook 取数据时，可以选择只订阅 store 的某个字段，只有这个字段变化了，组件才重新渲染。以用户信息为例：

import { create } from 'zustand'; import { persist } from 'zustand/middleware'; interface UserState { token: string; userInfo: UserInfo | null; permissions: string[]; setToken: (token: string) => void; setUserInfo: (info: UserInfo) => void; setPermissions: (codes: string[]) => void; logout: () => void; } export const useUserStore = create<UserState>()( persist( (set) => ({ token: '', userInfo: null, permissions: [], setToken: (token) => set({ token }), setUserInfo: (userInfo) => set({ userInfo }), setPermissions: (permissions) => set({ permissions }), logout: () => set({ token: '', userInfo: null, permissions: [] }), }), { name: 'admin-user-storage', } ) );

组件里取数据时，推荐用选择器模式：

const token = useUserStore((state) => state.token); const userInfo = useUserStore((state) => state.userInfo);

这两个写法分别订阅不同字段，token 变化不会连带 userInfo 更新。如果用一个对象整体存这两个字段，任何一边更新都会引起两边的组件刷新——这也是我在项目里要避免的坑。persist中间件可以自动把 store 同步到localStorage，刷新时初始化数据，不用手动写序列化逻辑。

3.3 一个真实的优化案例

项目里的侧边栏折叠按钮，最初是用 Context 实现的。点击一次折叠，布局组件、侧边栏、头部、面包屑、内容区全部重新渲染。在页面比较复杂时，折叠动画会掉帧。换成 zustand 之后：

interface LayoutState { collapsed: boolean; toggleCollapsed: () => void; } export const useLayoutStore = create<LayoutState>((set) => ({ collapsed: false, toggleCollapsed: () => set((state) => ({ collapsed: !state.collapsed })), }));

只有真正读取collapsed的组件（侧边栏、内容区 margin 控制）会刷新，其他组件完全不受影响。这个例子很典型，它能说明一个问题：选状态管理方案时，重点不是功能多不多、有没有社区热度，而是谁订阅了、谁会被触发重渲染。

3.4 踩过的坑：持久化和鉴权失效的冲突

把 token 持久化到localStorage之后，会遇到一个实际问题：接口返回 401 时，前端需要清除 store 并跳转登录页。如果 store 里的logout只是set一下状态，persist中间件会把"清空后的状态"再次写入 localStorage，这个行为是符合预期的，所以不用担心。反而是要注意清除时机：一定要先调logout()清理状态，再跳转，不能反着来，否则刷新后 token 又会被持久化数据覆盖回来。

4. 多环境构建配置：build --mode test 之后，还能做什么

热搜词里出现vite build --mode test，说明很多人已经踩到了多环境配置的问题。Vite 的多环境机制本身不复杂，但它和 Webpack 的DefinePlugin、cross-env那套思路不太一样，用错位置会导致环境变量全是undefined。

4.1 Vite 环境变量的加载机制

Vite 会读取项目根目录下的.env文件，并根据当前mode加载对应的文件：

注意，模式名叫什么，就要加载.env.{模式名}文件。npm run build默认走production，npm run dev默认走development。自定义模式必须显式传入--mode。比如测试环境：

{ "scripts": { "build:test": "vite build --mode test", "build:prod": "vite build --mode production" } }

.env.test示例：

# 只有以 VITE_ 开头的变量才会暴露给前端代码 VITE_APP_TITLE=测试环境 VITE_API_BASE_URL=https://api-test.example.com

前端代码里通过import.meta.env.VITE_API_BASE_URL读取。没有VITE_前缀的变量会被 Vite 忽略，不会暴露到客户端代码里，这个设计是为了防止误把敏感密钥打到前端包里。

4.2 类型定义：让 TS 识别你的自定义 env 变量

直接用import.meta.env.VITE_APP_TITLE时，TypeScript 会报类型不存在，因为 Vite 默认只声明了BASE_URL、MODE、DEV、PROD这些内置字段。需要在src/vite-env.d.ts里补充：

/// <reference types="vite/client" /> interface ImportMetaEnv { readonly VITE_APP_TITLE: string; readonly VITE_API_BASE_URL: string; readonly VITE_APP_ENV: 'dev' | 'test' | 'prod'; } interface ImportMeta { readonly env: ImportMetaEnv; }

这一段不做的话，项目里为了消除类型报错只能到处写as string，时间久了会产生一批"看起来能跑但没有任何类型保障"的代码，接口地址写错时根本不会被 TS 发现。

4.3 一个高频坑：为什么接口请求路径变成 "undefined/api/xxx"

有一次测试环境反馈所有接口 404，打开控制台发现请求地址是undefined/api/user/list。排查过程是这样的：

1. 先确认vite build --mode test是否真的加载了.env.test——在构建日志里没有看到对应的变量输出。
2. 再检查代码里怎么取的地址，发现用的是import.meta.env.VITE_API_BASE_URL，拼到 axios 的 baseURL 上。
3. 最后发现.env.test文件里的变量名写成了VITE_API_BASE_URL = xxx，等号两边带了空格。Vite 的 env 解析对空格敏感，值会被带上空格或者直接解析失败。
4. 修掉空格后，重新构建，接口正常。

这个问题的本质是环境变量在构建时被静态替换，没有运行时兜底。所以建议统一在src/config/index.ts里做一次出口：

export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api';

这样如果某个环境漏配了变量，至少会回退到一个默认值，而不是直接拼出undefined。另外还要留意 Nginx 的反向代理：如果前端用相对路径/api，构建出来直接扔给静态服务器即可；如果用完整域名，要检查跨域配置，否则浏览器 CORS 会拦住请求。

4.4 构建产物体积优化：按需加载不能只靠嘴

后台项目随着页面增多，首屏包体积会快速膨胀。我在这个项目里做的优化主要有四个动作：

1. 路由懒加载。上面动态路由里用到的import.meta.glob和React.lazy已经保证了路由级的代码分割。每个页面单独成一个 chunk，首屏只加载当前路由需要的代码。
2. antd 组件的按需加载。新版 antd（v5）天然支持 Tree Shaking，只要按import { Button } from 'antd'这种方式引入就行。但如果用import { message } from 'antd'，要注意它的静态方法在 React 18 StrictMode 下会有警告，建议改成App.useApp()的 API 形态。
3. 手动分包。把体积较大且不常变的依赖（如 echarts、pdf 预览类库）单独拆成一个 chunk，避免业务代码改动导致这些大库的缓存失效。

// vite.config.ts build: { rollupOptions: { output: { manualChunks: { echarts: ['echarts'], antd: ['antd'], }, }, }, }

4. 图表组件的动态导入。如果只在少数页面用到图表，不要在顶层统一import * as echarts，改成在组件内部按需引用或使用echarts/core的按需注册方式，可以把图表相关 chunk 的体积打下来不少。

优化完之后，首屏的请求数和总传输体积都有明显下降。但我的经验是，"体积优化"这件事要在项目中期做，不要一上来就做。早期业务变动大，过早的代码分割反而会增加维护成本，等页面结构稳定后再统一处理才是收益最大的时间点。

5. 后台管理项目里值得固化的几项开发习惯

这一篇最后分享几个我在这个项目里慢慢固化下来的开发习惯，不见得多高级，但对项目长期可维护性帮助很大。

第一是页面数据请求的 loading 态一定要在页面顶层处理。很多新人的习惯是const [loading, setLoading] = useState(false)塞在组件里，每个页面写一遍。更好的做法是做一个usePageData之类的封装 Hook，把 loading、error、data 的获取统一进去，页面的主要逻辑就只剩下"拿到数据后的渲染"。这个模式对后台系统密集型的表单列表页尤其友好，代码量能减少三分之一左右。

第二是所有列表页的筛选条件尽量映射到 URL query 上。后台用户的诉求往往是"把这个筛选结果发给别人看"，如果筛选条件只存在 state 里，刷新就丢。映射到 URL query 后，刷新保留、可分享链接、前进后退都能保持状态。这个改造早期做很简单，后期做很痛苦。

第三是定期审视代码里的全局状态。每加一个全局 store 字段，都应该问自己：这个字段真的需要跨页面共享吗？如果只是父子组件通信，就放在本地 state；如果刷新后不要求保留，也不考虑性能问题，可以先用 Context，出现明显的重渲染性能问题时再迁移到 zustand。后台项目最怕的不是"状态管得不好"，而是"没必要的状态被全局化"，这个问题在需求迭代几个版本后尤其明显。

第四是把环境配置和业务逻辑彻底分开。环境变量只在配置模块里读取一次，业务组件不要到处写import.meta.env。这样以后上线新的环境的成本，就从"全局搜索替换"变成"加一个 .env 文件"。我见过项目上线三个月后需要新增一套预发布环境，结果代码里有二十多处直接读 env，改起来相当闹心。

回到这个系列本身的方向。后台管理系统经过几轮迭代，真正决定上限的已经不再是框架本身，而是一系列细小的策略：适配策略、路由组织方式、状态管理边界、构建配置规范。vite、React、TypeScript、Ant Design 这套技术栈本身很成熟，网上能查到的官方文档也都写得很完整，但这些"藏在文档背面"的细节，往往才是项目能不能长期维护的真正分水岭。希望这篇的内容能帮你少走几趟弯路，下一篇我会继续从这个项目里挑更有实战价值的模块拆开讲。