前言
在现代前端开发中，路由系统是单页应用（SPA）不可或缺的核心模块。对于 Vue 生态，Vue Router 虽然功能强大，但在实际项目中，手动维护路由表、处理嵌套路由、参数路由、布局切换等问题，依然让开发者头疼。随着项目规模扩大，路由配置的复杂度和维护成本也随之上升。
ElegantRouter 正是为了解决这些痛点而生。它以"文件即路由"为核心理念，自动根据文件系统结构生成类型安全、可扩展的 Vue 路由配置，让开发者专注于页面和业务本身，大幅提升开发效率和项目可维护性。
仓库
github： github.com/soybeanjs/e…
觉着项目不错，欢迎 star🌟
快速体验
创建已配置路由插件的模版项目
- 使用
pnpm create soybean创建Vue3模版项目
pnpm create soybean
- 输入项目名称(如: vue-template)
- 选择 Vue3, 回车
- 进入项目，安装依赖
pnpm i
- 通过
er命令初始化生成路由数据
pnpm er -g
- 启动项目
pnpm dev
可以通过 VueDevtools 查看当前项目的路由，以及切换路由
更新路由数据
pnpm er -u
例如更新完路由的布局后，可以查看路由数据进行验证，或者直接更新当前路由的布局，页面实时变化
设计理念
1. 约定优于配置
ElegantRouter 倡导"约定优于配置"，只需按照约定的文件命名和目录结构组织页面，插件即可自动推导出路由表，无需手动维护繁琐的配置文件。
2. 白盒设计，数据透明
与部分黑盒自动路由方案不同，ElegantRouter 生成的路由数据完全透明，开发者可以随时查看、调试、扩展，便于集成到各种业务场景。
3. 类型安全与开发体验
自动生成类型声明文件，配合 IDE 智能提示，极大提升开发体验，减少低级错误。
核心功能详解
1. 文件系统驱动的自动路由生成
ElegantRouter 会扫描配置的页面目录（如 src/views），将每个页面文件自动映射为路由节点。支持多级目录、嵌套、分组、参数等多种场景。
示例：
src/views/
home/index.vue // /home
user/profile.vue // /user/profile
list/[id].vue // /list/:id
list/[[id]].vue // /list/:id? (可选参数)
list/detail_[id]_[userId].vue // /list/detail/:id/:userId
(admin)/dashboard.vue // /dashboard (分组，不影响路径)
2. 参数路由与可选参数解析
[id].vue→/:id（必选参数）[[id]].vue→/:id?（可选参数）detail_[id]_[userId].vue→/detail/:id/:userId（多参数）- 支持下划线、连字符等多种命名风格
3. 复用路由（Reuse Routes）
除了基于页面文件自动生成路由外，ElegantRouter 支持通过 reuseRoutes 配置复用已有页面组件，适用于多入口、路由别名、动态路由等场景。
配置示例：
reuseRoutes: [
'/reuse1',
'/reuse2/:id',
'/reuse3/:id?',
'/reuse4/:id?/:name?'
],
defaultReuseRouteComponent: 'Wip'
生成路由示例：
{
name: 'Reuse2Id',
path: '/reuse2/:id',
layout: 'base',
component: 'Wip',
meta: { title: 'Reuse2Id' }
}
4. 智能布局管理
- 支持多布局自动分组，按 layout 字段自动归类
- 页面可指定布局，未指定时使用默认布局
- 生成的路由结构自动嵌套，便于实现多级布局、权限控制等高级场景
配置示例：
layouts: {
base: 'src/layouts/base/index.vue',
blank: 'src/layouts/blank/index.vue'
}
5. 类型安全与工具函数
- 自动生成类型声明文件（如
elegant-router.d.ts），提升类型安全 - 提供路由名称、路径映射等工具函数，便于类型安全地进行路由跳转、导航
- 支持自定义 meta、懒加载、路由守卫等高级特性
6. 内置路由与 404 支持
- 自动生成根路由
/和 404 路由/:pathMatch(.*)* - 可通过配置自定义重定向和 404 组件
工作原理
- 文件扫描：启动时扫描页面目录，监听文件变化，实时更新路由表。
- 路径与参数解析：将文件路径、文件名中的参数部分解析为标准路由格式。
- 节点生成：为每个页面文件生成路由节点，自动补全 name、component、layout、meta 等字段。
- 冲突检测：自动检测路由冲突，优先保留第一个，输出警告。
- 类型声明与工具生成：生成类型声明文件和路由工具函数，提升开发体验。
命令行工具
ElegantRouter 提供了丰富的 CLI 工具，支持路由的自动生成、添加、复用、删除、恢复、备份等操作。
| Command | Shorthand | Description |
|---|---|---|
er generate | er -g | Generate route configuration files |
er add | er -a | Add a new route file |
er reuse | er -p | Add a reused route file |
er delete | er -d | Delete an existing route file |
er recovery | er -r | Recover a deleted route file |
er update | er -u | Update route configuration |
er backup | er -b | Manage route backups |
er --help | er -h | Show help information |
er --version | er -v | Show version information |
常用命令说明：
er generate：根据当前文件结构生成路由配置er add：交互式添加新页面路由er reuse：交互式添加复用路由er delete：删除路由文件er recovery：恢复已删除路由er update：更新路由配置er backup：管理路由备份
最佳实践
1. 文件组织
- 按业务模块或功能模块组织页面目录，提升可维护性
- 页面组件建议使用
index.vue或有明确含义的文件名
2. 路由参数处理
- 必选参数用
[param]，可选参数用[[param]] - 参数命名应具备业务含义，避免无意义简写
- 复杂参数组合可用多参数语法
detail_[id]_[userId]
3. 布局管理
- 合理配置
layouts，确保每个页面有合适的布局 - 利用
layout字段自动分组，避免嵌套过深
4. 性能优化
- 按需配置懒加载，提升首屏加载速度
- 大型应用可按功能模块拆分路由
- 合理使用
dynamicImport控制组件导入方式
5. 类型安全与工具函数
- 充分利用自动生成的类型和工具函数，减少路由相关低级错误
- 配合 IDE 类型提示，提升开发体验
与传统手动路由方案对比
| 维度 | 传统手动路由 | ElegantRouter 自动路由 |
|---|---|---|
| 路由维护 | 手动维护，易出错 | 自动生成，结构直观 |
| 嵌套路由 | 需手动配置 children | 自动分组，布局自动嵌套 |
| 参数路由 | 需手动写 path、props | 文件名即参数，自动解析 |
| 类型安全 | 需手动维护类型 | 自动生成类型声明 |
| 复用路由 | 需手动 alias 或 copy | reuseRoutes 配置一行搞定 |
| 变更响应 | 需手动同步 | 文件变更自动热更新 |
| 适用场景 | 小型项目 | 中大型项目/团队协作 |
适用场景与扩展性
- 中大型 Vue 项目：页面多、结构复杂、多人协作时，自动路由极大提升效率。
- 多布局/多入口项目：支持多 layout、复用路由，灵活应对复杂业务。
- 需要类型安全的团队：自动类型声明，减少线上 bug。
- 希望路由与页面结构强关联的项目。
ElegantRouter 还支持自定义路由生成规则、meta 信息、懒加载策略等，满足各种高级需求。
总结
ElegantRouter 以"文件即路由"为核心理念，极大地简化了 Vue 项目的路由管理。它不仅提升了开发效率，还让路由结构更加直观、可维护。无论是中小型项目还是大型企业级应用，ElegantRouter 都能为你的 Vue 路由管理带来全新体验。
如果你正在为路由配置头疼，不妨试试 ElegantRouter，让你的路由管理优雅起来！
如需更详细的 API 说明和进阶用法，欢迎查阅 官方文档 或阅读项目内的 README 文件。
