上周五下午,老板又站到我身后盯屏幕,看我一个个打开页面文件、复制路径、粘贴到路由配置文件里。十几条路由搞完,他叹了口气:“能不能别手动复制路由了?这玩意不是能自动的吗?”我嘴上说“能能能”,心里想的是:确实能,但我为什么没早做。
后来我花了两天时间,写了个自动扫描脚本,专门干这件事——扫一遍页面目录,路由配置自动生成。从那以后,新增页面再也不用碰路由文件,团队里几个同事也没再因为漏配路由提过“页面404了”的bug。这篇文章就把完整思路和实现拆开讲清楚,包含选型对比、核心代码、踩坑记录和后续扩展,适合被手动维护路由折磨过的前端、全栈同学参考。
1. 手动维护路由的痛,只有被线上事故打过的人才懂
1.1 一次漏配路由引发的“页面失踪”事故
事情得从更早的一次线上事故说起。当时项目里有个活动页,是运营那边催着上线的,开发同学加完页面文件、配好菜单入口,但忘了在路由配置文件里注册对应路径。结果上线后用户点菜单,页面直接白屏,控制台报错说匹配不到路由。排查了半天,最后发现只是 router/index.js 里少了一行 component: () => import(...)。
这种问题听起来特别低级,但在一个几十号人维护的中大型前端项目里,一点都不稀奇。页面文件散落在各个业务目录里,路由配置集中在另一个地方,两者之间靠人肉同步。文件一多、改动一频繁,漏配、错配、路径写错就是迟早的事。
还有更隐蔽的:A同事和B同事同一天各自加了页面,都改了路由文件,合代码的时候冲突了。Git合并冲突解决不好,就可能把另一个人刚加的路由覆盖掉。这种问题在code review里很难发现,因为路由文件动辄几百上千行,没人会逐行比对。
手动复制路由的另一个痛点是路由和实际文件结构容易出现“漂移”。页面文件改名了,路由没跟着改;目录调整了,路由还是老路径。时间一长,路由配置里残留一堆已经不存在页面的死条目,你也不知道哪些能删、哪些还在用。项目越大,维护成本越高,最后没人敢轻易动路由文件。
1.2 为什么“复制粘贴路由表”这个习惯特别危险
做前端的应该都有体会:路由配置看起来结构简单,无非是路径、组件、子路由、meta这几个字段,但一旦项目规模上来,它就会悄悄变得复杂。
最简单的场景是这样:
javascript复制{
path: '/user/list',
name: 'UserList',
component: () => import('@/views/user/List.vue'),
meta: { title: '用户列表', icon: 'user' }
}
这段配置本身不复杂,但如果有100个页面、50个嵌套路由、十几个需要配置 beforeEnter 守卫或 props 的路由呢?复制粘贴出错的地方就多了:
- 路径和组件实际位置不一致,拷过来的路径少了层级;
name重复,导致路由跳转时push({ name: 'xxx' })跳到错误的页面;- 嵌套路由层级错误,父组件里的
<router-view>渲染不出来; meta字段漏配,菜单、面包屑、权限判断全部出问题。
更重要的是,手动维护路由把精力浪费在了机械劳动上。路由配置本质上是从文件系统到URL的一种映射,这种映射完全可以通过约定自动生成。人该做的是关注业务逻辑,而不是每天给路径字符串做搬运工。
所以我当时的判断是:这个问题值得花时间根治,而不是每次遇到漏配再去补。写一个扫描脚本,用约定代替配置,把“人肉同步”变成“机器生成”,一劳永逸。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 选型思考:运行时扫描还是构建时生成?
2.1 备选方案对比:require.context、import.meta.glob、独立脚本
确定了要自动化,接下来就是选型。我调研了市面上常见的几种做法,各有优劣,这里直接对比给你看。
| 方案 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
require.context |
Webpack运行时批量导入 | 改动小,实时生效 | 只适配Webpack,Vite不适用;路由不直观 |
import.meta.glob |
Vite内置动态导入 | 代码简洁,支持懒加载 | 路由信息不够显式,复杂场景难处理 |
| 独立扫描脚本 | 构建前运行Node脚本生成路由文件 | 生成结果真实可读,支持复杂逻辑 | 需要维护脚本本身 |
require.context 是Webpack时代比较流行的做法,大家应该都见过这段代码:
javascript复制const modules = require.context('@/views', true, /\.vue$/)
它能自动把 views 目录下的所有 .vue 文件批量导入,然后遍历生成路由。好处是简单、延迟加载,坏处是项目换到Vite就不能用了,而且生成逻辑不够直观——你无法直接看到最终的路由表长什么样,调试起来比较费劲。
import.meta.glob 是Vite环境下的替代方案,写法更现代:
javascript复制const modules = import.meta.glob('@/views/**/*.vue')
这个方案的优点是构建工具原生支持、性能好,但它同样有“隐式路由”的问题:路由的路径、meta等信息都写在组件的 defineOptions 或注释里,代码不运行起来,你很难一眼看出整个路由结构。
我最后选的是独立扫描脚本方案。核心原因是这个项目里路由不只是“文件路径映射”这么简单——消息页面需要动态参数、权限页面需要配置meta、部分目录需要嵌套布局。这些逻辑用 require.context 或 import.meta.glob 写起来要么很别扭,要么让路由表完全变成黑盒。独立脚本可以做到扫描文件系统后,生成一份明明白白、可读可改的路由配置文件,既有自动化的便利,又保留了手动调整的兜底手段。
2.2 约定式路由方案的取舍逻辑
说到“路由自动生成”,很多人的第一反应是想到Nuxt.js或Next.js那种约定式路由:页面文件放 pages 目录里,文件路径自动对应URL路径,完全不用写路由配置。
我这个脚本的思路本质上也是约定式路由,但我故意没有直接上Nuxt,原因很简单:存量项目改造不是从零开始。公司这个项目已经是Vue3 + Vue Router的组合,路由表里还有一些特殊的字段和守卫逻辑,全部改成框架级的约定式路由,工作量不仅在于迁移页
