企业官网建设流程全解析

从早上九点坐下来到现在，我中途只起来接了三次水，剩下的时间全耗在“大事件”这个Vue3后台管理项目的第三天开发上。前两天把项目骨架和登录页搭好了，今天要处理的是这批页面里最磨人的动态表单，然后是路由权限和一堆Element Plus组件的视觉调整。这一天下来，我对Vue3的组合式API、ref和reactive的边界问题，还有全局改样式那点破事，理解比前两个月加起来都透。这篇笔记就是把今天实际踩过的坑、改过的代码、以及为什么这么写的思考完整记下来，给同样在Vue3项目里挣扎的人一个参考。

1. 第三天到底在做什么：从零散页面到可用的后台雏形

先说清楚“大事件”是啥。它就是一个内容管理后台，用来维护一系列事件新闻的展示、排序和上下架。前两天已经完成了Vite工程搭建、路由的基础配置还有登录表单的静态页面。但静态登录页只是摆设，第三天开始要让它真正工作起来：表单要能动态增删、路由要有守卫、页面进入前要校验登录状态，还得把后台最常见的Tabs标签页样式统一掉，不然一眼看过去就知道是拿组件库默认样式糊上去的。

很多新手学到第三天最容易犯的毛病是急着写业务，结果一边写一边发现前两天的代码根本没法扩展。我今天一开始也差点走这条路，先打开昨天的文件看到setup函数里堆了一百多行的变量和函数，状态分散得到处都是，连一个删除事件都要在methods里翻半天。这种代码在简单页面还行，一旦今天要加“批量审核”功能，改起来就是场灾难。

所以我早上花了四十分钟做了一次重构，把页面逻辑全部拆成组合式API的自定义hook。这里说的不是把methods挪到setup里就完了，而是把“表单数据”“分页逻辑”“列表请求”这些独立的状态抽成一个个use开头的函数。比如我建了一个useEventList，里面封装了列表数据、加载状态、页码变化和刷新函数；又建了一个useEventForm，专门管动态表单的初始数据、增删行、校验规则。页面调起来像拼积木一样：

const { list, loading, page, total, fetchList } = useEventList(apiUrl); const { formModel, addRow, removeRow, validateForm } = useEventForm();

后来发现这个做法的收益远超预期，不仅是代码短了，更重要的是状态变化能被精确追踪。比如某一行输入框的报错信息，通常组件库里是挂在每一项的rule上，如果用options API去写，this指向来回切换，人很容易晕。用hook把formModel和rules放在同一个作用域里，连响应式代理都不用反复确认，眼睛就能看出来。

这次重构也让我认真对比了Composition API和Options API的差异。如果项目只有十几个页面，而且页面之间完全没有共享逻辑，那options确实看着亲切，method、computed、watch分类清楚。但后台管理系统最典型的情况是：十几个列表页长得几乎一样，每个列表页都需要分页、搜索、状态过滤、重置表格。把这些重复逻辑拖到mixins里又会产生数据来源不明、命名冲突的危险。组合式API的解法是让每个hook显式声明自己管理哪些状态，显式返回给调用方，数据从哪来、能干什么一目了然。

今天这个决定的意义在于，后面两天的功能开发不会再被“以前写的逻辑缠住”。还有一个实际好处是调试：以前控制台里打印this.$data是一大坨信息，现在打印一个自定义hook返回的对象，里面就只有那个功能模块的东西，配合Vue Devtools的setup状态查看，定位响应式变量变化非常快。

1.1 为什么说ref和reactive不是随便用用

重构过程中最大的反应式问题出在ref和reactive的选择上。官方文档说ref用于基础类型和对象，reactive只能用于对象。但工程实践里远没有这么简单。

我第一天写的列表数据用的是reactive({ list: [], page: 1 })，然后所有组件都是props传下去，子组件里又reactive拷贝一份，结果数据不同步。后来才明白，reactive会把整个对象变成代理，如果你把reactive对象的某个字段解构出来赋值给普通变量，响应式连接就断了。我犯过的经典错误是：

const state = reactive({ list: [], count: 0 }); // 错误：count是普通值了 const { count } = state; // 正确：保持对state的引用，或者用toRefs const { count } = toRefs(state);

而ref其实是在内部用一个RefImpl类来持有value，所有对value的读写都走getter/setter，所以解构ref不会丢失响应性。今天做动态表单时我大量用了ref来管理“当前正在编辑的行的唯一标识数组”，因为每个行的状态相对独立，用ref数组很容易配合v-for渲染，也能在computed里通过editRowIds.value快速filter。一个很直白的建议，在写业务代码时，能统一用ref就去用ref，因为大家已经习惯在模板里写editRowIds而不是editRowIds.value，Vue的模板编译器会帮忙脱壳。但要在js逻辑里修改数组，就必须想着.value，否则拿到的是一个Ref对象，做push会直接报错。

今天重构成useApi相关函数时，我也感受到了响应式底层的一个特点：reactive对嵌套对象是懒代理的，只有访问到那一层才会代理。这在性能上是好处，但调试时想看完整快照，必须用JSON.parse(JSON.stringify())，或者Vue内置的toRaw。今天我为了排查一个“明明改了数据页面没更新”的问题，就靠toRaw打印真实值才定位到是一个对象被复制后失去了代理关系。

1.2 自定义hook的输入输出设计思路

既然是项目笔记，具体hook怎么设计值得记一笔。我写useEventForm时的约束很简单：hook只负责表单状态和验证逻辑，不关心组件长什么样。它返回一个formModel对象、一个addRow方法、一个removeRow方法、一个resetForm方法，还有一个设置好rules的数组。组件里只需要这样接：

const { formModel, rules, addRow, removeRow, resetForm, validate } = useEventForm(initialRow);

其中initialRow是一个保证每一行都有相同结构的工厂函数，返回一个全新的行数据。为什么要工厂函数？因为我吃过“直接复用同一个对象导致多行数据互相覆盖”的亏。后台动态表单里最常见的场景是：点“添加”要出现新的一行，每一项都是一个包含若干输入框的对象。如果你用的是同一个对象赋值给新行，那表格里所有行其实都指向同一个内存地址，改一行等于改全部。用const createEmptyRow = () => ({ title: '', url: '', startTime: '', endTime: '' })这样每次调用返回新对象，避免引用共享。

至于validate，我是直接返回组件的formRef.value.validate()，用的Element Plus表单验证。但这里有个坑：hook自身不持有DOM实例，让组件把表单的ref对象传进来，我一开始觉得这违反了“组合式API框架无关性”，但后来想了想，hook本来就是给组件用的，接收组件实例并不是坏味道。也可以更优雅地用defineExpose或者回调函数，但说实话，后端管理系统里简单直接反而好维护。

2. 动态添加删除表单行：不只是v-for循环那么简单

今天的核心功能就是“动态添加删除form表单一行数据”。页面上有一个事件配置表格，每条事件可以有三四个字段，运营同学需要临时增加或者减少配置项。最开始我想得比较简单，表单数据是一个数组，用v-for渲染，然后添加一行就push一个空对象，删除就splice。但真正接入Element Plus的el-form之后发现问题一个接一个，最典型的是校验规则失效：新增的一行，输入框没有触发校验，老的一行删除之后，后面的校验报错还挂在页面上。

先说为什么不能简单的用数组的下标当作key。Vue的diff算法靠key来追踪节点的身份，如果我用index当key，那么删除中间一行时，后面所有行的复用关系就乱了，输入框里的值可能会没有规律地错位。我调试时遇到过点击删除第三行，结果第五行的数据被清掉了，就是因为key用了index。正确做法是为每一行生成一个唯一id，可以用crypto.randomUUID()或者一个自增计数器，然后把id作为row-key。实际业务里我建议两段式：id用于循环key，再保留一个数据库字段id用于提交给后端，两者不要混用。

然后重点说校验。Element Plus的el-form通过model和rules来做校验，rules可以是一个数组，其中每一项还可以是函数。对于动态行，model必须是包含整个数组的对象，比如：

const formModel = reactive({ list: [] });

如果你把list单独拿出来作为v-model数组，那么校验器根本找不到路径。我一开始写成v-for="item in list"，rules里也写list，结果表单组件内部会根据prop去找model.list[0]这样的值，只有用formModel.list才行。设置prop的时候也必须带索引：:prop="'list.' + index + '.eventName'"。这个点是早上的第一个坑，卡了我大概四十分钟。

删除行之后校验残留是另一个经典问题。当你删掉一行，Element Plus的表单域还在内存里保留着校验状态，尤其是行数变少之后，被删除行的prop已经无意义，但错误消息依然展示。解决方法是删除行后，调用一次formRef.value.clearValidate()把整个表单的校验清除，然后通过nextTick重新验证当前行。为什么要nextTick？因为clearValidate在DOM更新之前执行，此时新数组还没渲染，clear的不是最新状态。可以这样：

async function removeRow(index) { list.splice(index, 1); await nextTick(); formRef.value.clearValidate(); }

还有一个追加行的细节：当你想在新增行上也立即应用校验，得确保新行被渲染后再去校验，或者只需让用户输入时触发即可。我更推荐后者，因为强制校验会让用户还没输入就红一片，体验很糟。只用设置validate-on-rule-change为false，避免规则变化触发不必要的校验。

2.1 动态表单项的自定义校验如何绑定

有些行不是普通的输入框，而是一个下拉选项，并且下拉选项的选项列表根据另一行的值联动。比如事件类型选“定时推送”，就会多出一个时间字段；选“立即推送”，时间字段就不需要。这种动态联动最容易导致校验规则失效：因为被隐藏的字段可能还在DOM上，校验rule仍然生效。

我的做法是用计算属性动态生成rules数组。比如一个行数据的rules是一个函数，函数内部判断当前行上某个字段的状态，返回通过或不通过。Element Plus支持rule作为一个自定义validator：

const ruleList = computed(() => formModel.list.map((item, index) => ({ type: [{ required: item.mode === 'timer', message: '定时推送必须设置时间', trigger: 'change' }], })));

但prop是按index索引的，你并不能方便地在模板里直接给:rules="rowRules"传一个数组。我后来换了个思路：不在rules里写这种联动，而是在表单的validate方法里统一处理——写一个validateCustom函数，先遍历所有行，检查必要的关联字段，如果不符合条件，用formRef.value.validateField(prop)来单独标记错误。这个方法看着没rules那么Redux式，但扩展性很好，可以随意写if-else。对于后台项目，复杂联动用这种手动编排逻辑最清晰，至少自己三个月后回来看还能明白。

另一个容易忽略的是“添加一行后自动滚动到该行”。需求方要求新增行必须在可视区域，实现很简单，给新行加一个ref标记，比如用ref数组收集行DOM，然后nextTick里调用rowRef.value[list.length-1].scrollIntoView()。别问我为什么专门记这个，下午改了三遍才想起所有新增行的索引是动态的，不能在模板里写死。

2.2 提交数据前的清洗与格式化

动态表单提交时，最怕把空行、未填写的脏数据发给后端。我在submit方法里先做filter，把列表中所有字段都为空的行过滤掉，然后对某些时间字段做格式化。格式化要趁早，因为Element Plus的日期选择器返回的是Date对象，直接JSON.stringify会变成一串很长的UTC字符串，后端根本没法入库。我建议所有这些清洗逻辑放在一个独立的prepareSubmitData函数里，不跟UI耦合。

function prepareSubmitData() { return formModel.list .filter(row => row.eventName.trim() !== '' || row.startTime) .map(row => ({ ...row, startTime: row.startTime ? dayjs(row.startTime).format('YYYY-MM-DD HH:mm:ss') : null, })); }

这个函数我留了一个后悔的口子：原始数据从表单到提交有过一次深拷贝，避免对formModel的引用污染。用JSON.parse(JSON.stringify(model))记下脏数据，再在脏数据上做格式化，这样即使校验失败回滚后，表单里还保留着用户的时间对象，方便二次编辑。

3. 路由守卫和权限控制：让页面不再裸奔

第三天下午的任务是把整个后台的路由保护起来，不然任何没有登录的人都能直接访问管理页，这在曾经上线过的项目里就是安全事故了。之前两天我配置的路由只是简单的静态路由，没有任何守卫。这次要做的有三件事：一是判断用户是否登录，未登录跳转登录页；二是根据用户角色生成可访问的动态路由；三是按钮级别的权限控制，给不同角色显示不同操作按钮。

路由守卫主要用router.beforeEach，在跳转前读取Pinia里的token和userInfo。这里有个细节：如果token存在且要去登录页，应该直接跳回首页；如果token不存在但目标路由需要认证，则重定向到登录页并带上redirect参数。代码不复杂：

router.beforeEach((to, from, next) => { const store = useUserStore(); if (!store.token) { if (to.meta.public) { next(); } else { next({ path: '/login', query: { redirect: to.fullPath } }); } } else { if (to.path === '/login') { next('/'); } else { next(); } } });

但真正的权限框架应该在初始化时就把角色允许的路由动态添加进去。今天我用router.addRoute实现了这个逻辑，把角色与路由映射表放在一个常量文件里。比如普通编辑能访问列表页和详情页，管理员还能访问审核页。登录成功后，根据角色遍历这张表，将对应页面动态挂载到router上。

有一个很重要但容易踩坑的点：动态添加路由后，如果用户刷新页面，所有动态路由都会因为内存清空而丢失。所以必须在应用启动时、路由初始化前，先读取本地持久化存储里的角色信息，再动态addRoute。我采用的是router.isReady().then(() => {})里做初始化，保证首次导航前路由已经注册完毕。另外，addRoute是异步的吗？官方API声明是同步注册，但如果你在判断to.matched时发现一个路由没有匹配到，通常就是还没注册完。建议不要依赖addRoute之后的立即next()，而用next({ ...to, replace: true })让它重新走一遍动态路由查找。

3.1 按钮权限的两种实现思路

按钮权限我采用了指令方式。因为后台管理里相同按钮在不同角色下可见性不一样，用v-permission="'auditBtn'"这种自定义指令包裹按钮最直接。指令内部读当前用户角色列表，如果不包含权限点，就直接el.parentNode?.removeChild(el)。这样做的好处是模板干净，缺点是权限变化后不会动态更新，必须重新渲染组件。另一种方式是封装一个<AuthButton>组件，内部用v-if判断，适合有tooltip和二次确认的需求。两种都可以，看团队习惯。

我这里的场景比较简单，所以用了指令。但需要注意，权限指令必须挂载在按钮的挂载阶段，如果按钮是异步渲染出来的，指令可能没执行到，稳妥做法是在指令里同时检查角色，并在updated钩子再移除一次。不过实际项目中更推荐直接v-if，因为权限逻辑往往伴随着禁用、提示文案一起出现，写死在模板里反而更容易trace。

3.2 动态路由带来的菜单映射问题

加上动态路由后，菜单变得不老实了。侧边栏菜单是根据路由表配置的，但动态路由是之后才注册的，如果菜单组件已经初始化完成，就不会包含动态部分。解决方法是把菜单数据做成一个computed，它从路由表里过滤出带有meta.title的记录，然后组合出一棵菜单树。因为computed会响应式更新，一旦addRoute后，路由表变化，菜单也会自动重新渲染。我试过用watch去监控router.options.routes，但路由表不是响应式对象，所以watch根本不会触发。还是老老实实从router.getRoutes()去计算，并且配合一个菜单刷新标志位，addRoute完成后把标志位取反。

今天在这里我犯了一个逻辑错误：原本我在登录页直接把用户信息存到了localStorage，但刷新后Pinia里的角色是空的，动态路由重新注册时没有权限数据，导致所有动态路由都加不进去。后来改成启动时先从localStorage读取用户角色，再初始化Pinia，再注册路由，这个顺序彻底解决。

4. Tabs标签页样式魔改：全局覆写Element Plus的三板斧

后台系统里标签页是高频组件，但Element Plus自带的tabs样式太素，标题栏背景、下划线颜色都跟项目主题不搭。第三天下午的最后两小时就是在干这件事。先说结论：改组件库样式不要直接去node_modules里改源码，也不要用!important满屏飞。正确路径是找到组件的样式变量，用CSS变量覆盖；如果变量没有暴露，再写全局样式并用深度选择器。

Element Plus的Tabs组件本身暴露了一些CSS变量，比如--el-tabs-header-height、--el-color-primary。但我们要改的是导航栏的背景色、活动标签的字体颜色和边框，这些常用变量还没覆盖到所有场景。所以我的方案是给tabs外层加一个自定义class，然后用:deep()修改内部样式。比如：

.app-tabs { --el-tabs-header-height: 44px; } .app-tabs :deep(.el-tabs__header) { background: #f5f7fa; border-radius: 4px; padding: 0 12px; margin-bottom: 12px; } .app-tabs :deep(.el-tabs__item) { font-size: 13px; color: #606266; border-radius: 4px; transition: all 0.2s; } .app-tabs :deep(.el-tabs__item.is-active) { background: #ffffff; color: #1a73e8; box-shadow: 0 1px 4px rgba(0, 21, 41, 0.08); }

这个方案的好处是作用域锁定在这个页面的tabs上，不会污染其他页面。如果你想把所有Tabs都统一，可以直接在全局样式中写，不带class。但后台多页面风格一致时，全局统一更方便。我自己的经验是：像这种管理后台，样式统一优先，全局覆盖省心很多，但一定要写在reset样式之后、业务样式之前。

还有一个常见的需求是修改标签页的下划线颜色和位置。Element Plus的Tabs默认下划线是一段绝对定位的div，而不是border。用CSS变量不好改，要直接定位到.el-tabs__active-bar。记住下划线是绝对定位的，会跟随标签切换动画。改颜色直接用background-color就行：

.app-tabs :deep(.el-tabs__active-bar) { background-color: #ff6a00; }

但如果你想换一种交互，比如不用下划线而是用整块背景色高亮当前标签，那就需要关掉内置下划线，然后给is-active加背景。这时下划线还是会占用定位空间，最好设置display: none。我实际测试后发现，直接隐藏下划线会留出几像素的偏移，需要微调.el-tabs__item的高度和padding。建议用一个div包裹tabs后设置height: 44px; overflow: hidden来兜底。

样式调试过程中最容易遇到的就是scoped样式失效。Vue的scoped会为模板元素加><router-view v-slot="{ Component }"> <keep-alive :include="cachedViews"> <component :is="Component" /> </keep-alive> </router-view>

需要注意，只有组件name和数组里匹配的组件才会被缓存。我之前用默认导出的setup语法，组件name是文件名，系统无法识别，必须额外用defineOptions({ name: 'EventList' })指定名字。今天我把所有主要页面都加上的名字，然后维护一个useTagsView的hook去管理哪些页面需要缓存、哪些关闭标签后要清除缓存。实际上很多教程里会把这一块做成“tagsView”，但我今天只做了最简单的一层，缓存列表页状态是真的香。

5. 从JSX看Vue3的取舍：项目里该不该用

因为热词里提到vue3使用jsx，我也借机把jsx在项目内的可用场景测试了一遍。其实Vue3的jsx跟React很像，但Vue的模板功能太强了，装饰器和tsx在指令、样式作用域上有很多不顺手的地方。比如在tsx里不能直接用v-model，得自己写value和onUpdate:modelValue，用起来比模板啰嗦。但某些场景下，比如写一个动态渲染的列配置，用tsx比模板更灵活，因为可以直接用JavaScript的map和条件判断。

今天在动态表格里，我尝试用tsx渲染操作列，通过一个render函数返回按钮组，代码确实比模板简洁，但调试断点时不能再看到嵌套的元素标签，让我不太习惯。后来还是回到模板。我的建议是，如果不是组件库二次开发或者特别复杂的动态渲染，不建议大范围引入tsx。Vue生态里模板仍然是主流，热更新、开发体验都比tsx顺滑。如果你确实喜欢jsx的灵活性，可以局部使用，比如给el-table的column加自定义render，但要注意在Vue3里render函数接收的是FunctionalComponent，需要用h函数创建元素节点。

render: ({ row }) => <el-button type="danger" onClick={() => removeRow(row)}>删除</el-button>

这样写确实比模板少几行，但响应式数据的读取方式变成row对象，跟模板里的自动解包不一样，容易踩坑。所以整体决策是：第三天先不引入tsx，保持项目模板统一，降低维护成本。

6. 今日Bug复盘与排查技巧实录

每做一天项目，最后都要把今天跳过的坑整理一遍，不然过几天全忘了。以下是按实际出现顺序记录的Bug，排名不分先后，全是真实体验。

第一个问题发生在早上重构后，列表页突然不刷新了，报错信息是“Invalid value for state variable 'list'”。打印处理才发现，我在useEventList里用的是ref([])，但在setup里返回时写成了list: list.value，这就直接把value传给响应式状态，再赋值时已经不是ref的引用了。修复很简单，返回时保证list还是一个ref，不要在setup中间解包。记住：模板里用list没错，但逻辑层传值时要传整个Ref。

第二个问题是动态表单删除行时，偶尔出现“Cannot read properties of undefined (reading 'validate')”，这是因为删除后我调用的formRef.value.clearValidate()，但此时表单的model已经更新而DOM还在旧状态，导致某些字段的prop对应不到。后来改成在删除后await nextTick()再clearValidate，就稳定了。第三个问题是Tabs样式只在第一次打开页面时生效，切换其他路由再回来样式丢失。排查了很久，最后发现是KeepAlive缓存了组件，而给tabs加的class是在组件的根元素上，缓存组件不会重新创建根元素，但样式是通过外部CSS加载的，按理不会丢。最终的问题是路由切换时，同一个外层容器类名和别的页面冲突了。将tabs包裹类名改为更独特的event-tabs-container后解决。

我还踩了一个关于watch的坑。我想监听动态表单的长度变化来自动计算“已配置事件数量”，用watch(() => formModel.list.length, val => { count.value = val })，结果每次删除一行都触发，但新增一行时不触发。原因是在v-for渲染下，新增行实际是push了一个对象，数组length变了，watch确实应该触发才对。打印发现，formModel.list不是普通的数组，而是一个响应式代理数组，length变化在代理对象里也被代理了，理应触发。后来问题定位到设置初始值时，我在useEventForm里直接赋值了formModel.list = [createEmptyRow()]，这导致formModel的list属性从reactive的数组换成了一个普通数组，响应式连接彻底断了。正确的做法是formModel.list.splice(0, 1, createEmptyRow())或者用formModel.list.push(...)。这个教训让我意识到reactive对象的属性不能随意替换，因为对象的代理机制只对最初给定的值生效。

今天最后一个技术挑战是“如何把组合式函数的返回值安全地暴露给模板”。我在useEventList里返回了一个refresh函数，页面销毁前不会清理，结果在路由离开后再次进入，refresh还在调用旧的列表接口导致报错。正确的做法是在onUnmounted里清理定时器或取消请求。接口请求我用的是Axios，可以用AbortController来取消。我把取消逻辑也塞进了hook里，从外部传入一个signal，这样页面销毁时自动abort。

最后记录一个很重要的排查技巧：在响应式数据大量嵌套时，别指望打印整个对象能看到原始值。我推荐用watch配合{ deep: true }打印具体的变更字段，或者用toRaw查看非代理对象。今天大部分时间都是靠这两招定位问题的。还有，对于表单校验问题，最有效的是在Element Plus的form组件上加上validate-on-rule-change属性为false，减少不必要的校验触发，再配合validateField指定字段进行单独调试。

7. 收个尾：第三天什么才是关键收获

如果硬要提炼今天最值的一句话，我会说是“状态管理的第一原则是保持引用稳定”。无论是ref还是reactive，本质上都在教我们一件事：不要让响应式对象被普通对象替换，不要轻易解构响应式字段。后台系统的复杂度全在状态上，动态表单的增删、路由的动态注册、组件的缓存，都是围绕状态的生命周期展开的。今天所有踩过的坑，到最后都能归纳到“数据是不是同一份引用”这个问题上。

还有一个实际建议是，给每天的项目笔记留一个“明天必做”清单。我今天在收工前写了一行：“明天上午优先处理列表页批量操作和状态筛选联动，别等需求的刀子落下再补。”这个习惯帮我把复杂功能拆成可以消化的小任务，也防止第二天早晨不知道从哪动手。做项目就是这样，第三天的感觉跟前两天完全不同，两天前还在学API，今天已经可以在真实业务里权衡方案了。如果你也在跟进一个Vue3后台项目，不用怕遇到问题，把每个问题的前因后果记下来，那才是项目笔记最有价值的地方。