企业官网建设流程全解析

前端路由与导航全解：以 easy-vibe 为例掌握 SPA 路由原理、Hash/History 模式与部署实战

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

导读

前端路由是单页应用（SPA）区别于传统网站的核心技术：它让页面切换不再白屏闪烁、不再整页重载，而是像原生 App 一样顺滑。本文以开源课程项目 easy-vibe（一个基于 VitePress 与 Vue 3 构建的多语言 AI 编程实战课程站）为观察对象，系统讲解前端路由的动机、核心概念、Hash 与 History 两种模式的底层原理、路由配置的最佳实践，以及部署后 404 等高频故障的排查方法。读完本文，你将能理解路由系统内部到底做了什么、何时选 Hash 何时选 History，并能独立完成带路由的 SPA 从开发到部署的全流程配置。

1. 为什么需要"前端路由"

1.1 从传统网站到单页应用：体验的质变

回想早期网页体验：点击任意链接都是一次完整页面切换——页面变白、加载条旋转、整页重新渲染。在慢速网络下，用户要对着加载画面等上数秒。这种体验如今显得过时，但在当时就是标准。

现代前端开发彻底改变了这一模型。借助前端路由技术，页面切换如移动 App 般流畅——没有白屏闪烁、没有加载条，用户几乎感知不到"跳跃"。这种提升并非魔法，而是前端路由系统的功劳。

这正是"前端路由"要解决的核心问题：切换视图并同步更新 URL——但绝不重新加载页面。

在 easy-vibe 仓库中，这种 SPA 体验有非常直观的体现：docs/index.md使用window.location.replace依据浏览器语言自动跳转到对应语言版本（如/de-de/、/zh-cn/），跳转过程不触发整页刷新，而是由前端接管；多语言切换、页面间的平滑导航都建立在 VitePress（底层即 Vue Router）的 SPA 路由之上。

1.2 一个真实的踩坑故事：为什么你必须理解两种路由模式

你可能会说："我直接用 Vue Router / React Router，配置好就能跑，为什么要理解底层原理？"下面这个真实场景会告诉你答案。

小李是刚入门的前端新人，负责开发一个基于 Vue 的单页应用。本地开发一切正常，路由跑得行云流水。可部署到测试服务器后问题出现了：用户直接访问某个路由（如example.com/user/123）或在详情页刷新页面时，会收到404 Not Found。

小李百思不得其解：本地好好的，为什么部署后就 404？他排查了很久，甚至怀疑是服务器配置的问题。

最终一位资深同事一眼看出了问题：小李用的是History 模式，但服务器没有配置回退（Fallback）。当用户直接访问/user/123时，服务器会去文件系统里找这个路径下的文件——而 SPA 的所有路由实际上都指向同一个index.html。解决办法很简单：让服务器把所有路由请求都回退到index.html，剩下的交给前端路由处理。

小李由此学到重要一课：如果不理解路由模式的工作原理以及它们对服务器配置的要求，你甚至不知道错误为什么发生，更谈不上如何修复。

核心启示：前端路由不是"黑盒"。理解了它的工作机制，遇到部署、性能、SEO 相关问题时就能快速定位根因并精准解决；更重要的是，这能帮助你在架构规划时做出更明智的决策——何时用 Hash 模式、何时用 History 模式、如何避开常见陷阱。

2. 核心概念：Route、Modus、Navigation

在深入具体实现之前，先厘清几个核心概念。为便于理解，我们用一个"图书馆"类比来说明它们之间的关系。

当你使用 Vue Router 或 React Router 时，框架替你完成了三件事：

1. 路由映射（Route Mapping）→ 定义 URL 与组件之间的对应关系
2. 模式选择（Modus-Auswahl）→ 决定使用 Hash 还是 History 模式
3. 导航控制（Navigationssteuerung）→ 管理页面切换与浏览器前进/后退

理解了这三个概念，你就知道路由系统到底在做什么、为什么有时需要特殊配置、为什么部署时会出问题。

2.1 用图书馆类比理解路由系统

这四个概念必须区分清楚：Route 是静态配置，Router 是动态管理者，Modus 是技术选型，Navigation 是用户行为。

2.2 Route：URL 与组件之间的映射契约

Route 本质上是一份"契约"，规定访问某个 URL 时展示什么内容。在 Vue Router 中，典型的路由配置如下：

const routes = [ { path: '/', // URL 路径 component: Home // 对应的组件 }, { path: '/user/:id', // 带参数的动态路由 component: UserDetail, children: [ // 嵌套路由 { path: 'profile', component: UserProfile }, { path: 'posts', component: UserPosts } ] } ]

你可能会问：为什么不用<a>标签，非要搞路由？

答案在于单页应用的本质：SPA 只有一个 HTML 页面，所有页面切换实质是同一页面内的组件替换。如果使用传统<a href="/user/123">，浏览器会真的向服务器请求/user/123这个路径，从而触发页面重载甚至 404。路由的职责正是拦截这些跳转动作，用 JavaScript 动态替换组件，实现无刷新切换。

常见路由配置模式：

静态路由（最简单）：

{ path: '/home', component: Home } { path: '/about', component: About }

动态路由（带参数）：

{ path: '/user/:id', component: UserDetail } // 可匹配 /user/123、/user/abc 等 // 组件内通过 route.params.id 读取参数

嵌套路由（父子关系）：

{ path: '/user/:id', component: UserLayout, // 父组件 children: [ { path: 'profile', component: UserProfile }, // 实际路径 /user/:id/profile { path: 'posts', component: UserPosts } // 实际路径 /user/:id/posts ] }

通配符路由（404 页面）：

{ path: '/:pathMatch(.*)*', component: NotFound } // 匹配所有未定义的路由

仓库佐证：easy-vibe 的交互式教学组件中专门实现了DynamicRoutesDemo.vue（动态路由演示）与NestedRoutesDemo.vue（嵌套路由演示），完整清单见 docs/.vitepress/theme/components/appendix/frontend-routing/index.js，与本文讲解的路由模式一一对应，可直接对照学习。

2.3 路由模式：Hash 与 History 的本质区别

前端路由有两种常见实现模式：Hash 模式与 History 模式，它们在 URL 形态、底层实现、兼容性上差异显著。

为什么需要两种模式？这是历史演进与技术权衡的结果。

• Hash 模式是前端路由最早的实现，利用 URL 的 hash 部分（#之后的内容）。hash 变化不会触发页面重载，且兼容性极佳（甚至支持 IE8）。
• History 模式是 HTML5 以来的"标准方案"，利用 History API 的pushState和replaceState方法，让 URL 看起来"更正常"（没有#），但要求服务端配合配置。

打个比方：Hash 模式就像"在房门上贴便利贴"（不改变房间结构），History 模式就像"给房间重新编号"（需要同步更新门牌系统）。

逐行解读这张表：

• URL 示例：Hash 模式的 URL 有明显的#，用户一眼能看出这是 SPA；History 模式则与传统网站无异，显得"更专业"。
• 实现方式：Hash 模式监听hashchange事件（hash 变化时触发）；History 模式利用 HTML5 History API，"伪装"出一次页面跳转而无需真正重载。
• 服务器配置：这是最常见的坑！Hash 模式中#之后的部分不会发送给服务器，服务器无需知道路由信息；History 模式则会发送完整路径给服务器——服务器配置不对就会 404。
• SEO 友好度：搜索引擎爬虫通常不执行 JavaScript，Hash 模式的 URL 可能被忽略；History 模式的 URL 结构清晰，更易被索引。
• 部署成本：Hash 模式"开箱即用"，History 模式需要运维知识（Nginx、Apache 等）。因此许多个人项目默认采用 Hash 模式。

仓库佐证：easy-vibe 为演示两种模式的差异专门构建了HashVsHistoryDemo.vue组件，以浏览器地址栏模拟 + 特性徽章（兼容性 IE8+、无需服务器配置、SEO 较差等）直观对比，与上文表格结论一致。

3. 演进路径：从传统网站到现代路由

下面以一个电商网站"BuyMore"为例，看它如何从传统多页应用逐步演进到现代 SPA 路由。这个案例能直观展示前端路由解决了什么问题。

前置知识：MPA、SPA 与 SSR

• MPA（Multi-Page Application）多页应用：传统 Web 开发方式。每个页面都是独立 HTML 文件，页面切换整页重载。
• SPA（Single-Page Application）单页应用：当今前端主流。只有一个 HTML 入口，页面切换通过 JavaScript 动态替换组件完成，无需重载。
• SSR（Server-Side Rendering）服务端渲染：在服务器端生成完整 HTML，兼顾 SPA 与 MPA 的优点：首屏快、SEO 好。

一句话概括：MPA 像"每次翻页重新画"，SPA 像"在同一张纸上擦了重画"，SSR 像"提前把纸画好再递给你"。

3.1 演进全貌

逐阶段解读：

• 阶段一 → 阶段二：从"带刷新"到"无刷新"，这是质变。用户首次体验到类似 App 的流畅感，但代价是 URL 中的#显得不专业。
• 阶段二 → 阶段三：从"能用"到"好用"。History 模式让 URL 干净如传统网站，但代价是部署复杂度上升（需要服务器配置）。
• 阶段三 → 阶段四：从"体验好"到"体验好 + SEO 好"。SSR 解决了 SPA 的 SEO 问题，首屏也更快，但实现复杂度显著增加。

总结：前端路由的演进不仅是"切换更快"，更是整个应用架构的升级——从服务器主导、到前端主导、再到两者结合。每一步都在用户体验、开发成本、SEO 等维度之间权衡。

3.2 阶段一：传统多页应用——每次都是重载

为什么叫"传统多页应用"？因为这个阶段每个页面都是独立 HTML 文件，浏览器每次切换都要重新下载全部资源（HTML、CSS、JS）。这是最早的 Web 开发方式，许多传统网站至今仍是这样。

开发方式：

• 路由实现：服务端路由，每页对应服务器上的一个 HTML 文件
• 页面切换：使用<a href="/products/123">，触发完整页面重载
• 状态管理：每次切换都会丢失之前的页面状态（滚动位置、表单内容等）

该阶段特征：

• ✅优点：实现简单、对搜索引擎友好（SEO 好）、浏览器导航开箱即用
• ❌缺点：每次切换都重载、用户体验差、服务器负载高（相同资源被反复加载）

项目结构与页面访问流程（典型的服务端渲染结构）：

server/ ├── views/ # HTML 模板 │ ├── index.html # 首页模板 │ ├── products.html # 商品列表模板 │ └── product.html # 商品详情模板 ├── public/ # 静态资源 │ ├── css/ │ ├── js/ │ └── images/ └── server.js # 服务器入口

页面切换流程：

1. 用户点击链接 <a href="/products/123"> ↓ 2. 浏览器向服务器发送 GET 请求 ↓ 3. 服务器渲染 product.html，填充数据 ↓ 4. 返回完整 HTML 页面 ↓ 5. 浏览器解析 HTML，加载 CSS/JS，渲染页面 ↓ 6. 用户看到页面（这个过程通常耗时 1-3 秒）

用户的痛点：

• 点击链接后白屏、等待时间长
• 每次切换都要重新加载相同的 CSS/JS 文件
• 浏览器前进/后退整页重载
• 复杂页面状态（筛选条件、滚动位置）无法保留

仓库佐证：easy-vibe 用MpaRoutingDemo.vue组件复现了这一过程——每次"导航"都会模拟整页重载的白屏闪烁，让学习者直观感受传统 MPA 的体验短板。

3.3 阶段二：早期单页应用——Hash 路由时代

当传统多页应用的问题无法忽视时，"BuyMore"团队决定引入前端路由，转型 SPA 架构。这是重要转折点——从"服务器主导"转向"前端主导"。

但这个阶段也有代价：URL 中的#显得不专业，搜索引擎索引也成问题。

开发方式：

• 路由实现：Hash 路由，利用 URL 的#部分
• 页面切换：JavaScript 拦截链接点击，动态替换组件
• 状态管理：页面状态保留在客户端，无需重载

该阶段特征：

• ✅优点：无刷新切换、体验流畅、服务器负载降低
• ❌缺点：URL 带#、对 SEO 不友好、首次加载较慢

Hash 路由核心实现：

项目结构（早期 SPA 的典型结构）：

project/ ├── index.html # 唯一的 HTML 入口文件 ├── css/ │ └── app.css # 所有样式合并到一个文件 ├── js/ │ ├── router.js # 简易路由实现 │ ├── views/ # 页面组件 │ │ ├── Home.js │ │ ├── ProductList.js │ │ └── ProductDetail.js │ └── app.js # 应用入口 └── server.js # 简单静态文件服务器

Hash 路由核心代码：

// router.js - 简化版 Hash 路由实现 class HashRouter { constructor(routes) { this.routes = routes this.currentPath = null // 监听 hash 变化 window.addEventListener('hashchange', () => { this.matchRoute() }) // 初始化 this.matchRoute() } matchRoute() { // 获取当前 hash（去掉 #） const hash = window.location.hash.slice(1) || '/' const route = this.routes.find(r => r.path === hash) if (route) { this.render(route.component) } else { this.render(NotFoundComponent) } } render(component) { const app = document.getElementById('app') app.innerHTML = component.template() component.mount?.(app) } navigate(path) { window.location.hash = path } } // 使用 const router = new HashRouter([ { path: '/', component: Home }, { path: '/products', component: ProductList }, { path: '/products/:id', component: ProductDetail } ]) // 导航 router.navigate('/products/123')

URL 形态：

• 首页：https://example.com/#/
• 商品列表：https://example.com/#/products
• 商品详情：https://example.com/#/products/123

带来的改进：

1. 用户体验更好：页面无刷新切换，流畅自然
2. 服务器负载降低：HTML/CSS/JS 只加载一次，之后仅传输数据
3. 状态得以保留：切换时滚动位置、表单内容不再丢失
4. 支持离线：配合 Service Worker 可实现离线访问

新的痛点：

1. URL 不美观：#让 URL 像"锚点跳转"，不专业
2. SEO 问题：搜索引擎爬虫可能忽略 hash 之后的内容，页面无法被索引
3. 首次加载慢：全部 JavaScript 需一次性加载，首屏时间（Time-to-First-Paint）长

3.4 阶段三：现代单页应用——History 路由成为主流

Hash 路由的痛点（URL 不美观、SEO 差）困扰开发者多年。随着 HTML5 普及、浏览器兼容性改善，History 路由逐渐成为主流。

History 路由利用 HTML5 History API 让 URL "看起来正常"（无#），但需要服务端配合配置。

开发方式：

• 路由实现：History 路由，使用pushState和replaceState
• 路由库：成熟的 Vue Router、React Router 等
• 服务器配置：服务器需配置所有路由回退到index.html

该阶段特征：

• ✅优点：URL 美观、SEO 友好、体验流畅
• ❌缺点：部署需要特殊配置，服务器必须配合

History 路由实现与部署配置：

项目结构（现代 SPA 的典型结构）：

project/ ├── public/ │ └── index.html # 唯一的 HTML 入口 ├── src/ │ ├── router/ │ │ └── index.js # 路由配置 │ ├── views/ # 页面组件 │ │ ├── Home.vue │ │ ├── ProductList.vue │ │ └── ProductDetail.vue │ ├── App.vue │ └── main.js ├── package.json └── vite.config.js # 构建配置

Vue Router 配置示例：

// src/router/index.js import { createRouter, createWebHistory } from 'vue-router' const router = createRouter({ history: createWebHistory(), // History 模式 routes: [ { path: '/', component: () => import('@/views/Home.vue') }, { path: '/products', component: () => import('@/views/ProductList.vue') }, { path: '/products/:id', component: () => import('@/views/ProductDetail.vue') }, { path: '/:pathMatch(.*)*', component: () => import('@/views/NotFound.vue') } ] }) export default router

URL 形态：

• 首页：https://example.com/
• 商品列表：https://example.com/products
• 商品详情：https://example.com/products/123

关键：Nginx 配置（部署时必须配置）：

server { listen 80; server_name example.com; root /var/www/app; index index.html; # 关键配置：所有路由都回退到 index.html location / { try_files $uri $uri/ /index.html; } }

为什么需要这个配置？

场景：用户直接访问 https://example.com/products/123 ❌ 没有配置时： 1. 浏览器向服务器请求 /products/123 2. Nginx 在文件系统里寻找 /products/123 3. 文件不存在，返回 404 ✅ 有 try_files 配置时： 1. 浏览器向服务器请求 /products/123 2. Nginx 尝试找文件 → 不存在 3. 按 try_files 规则回退到 /index.html 4. 浏览器加载 index.html 5. Vue Router 接管，解析 /products/123 6. 渲染 ProductDetail 组件 7. 页面正常显示！

与 Hash 模式的对比：

仓库佐证：easy-vibe 仓库根目录的 nginx.conf 就是 History 模式部署的真实范例——location / { try_files $uri $uri.html $uri/ /index.html; }在标准写法基础上额外支持了$uri.html（适配无扩展名 markdown 页面）与静态资源缓存（/assets/下expires 1y+Cache-Control: public, immutable）。另外 docs/DEPLOYMENT.md 与 docs/.vitepress/config.mjs 展示了 VitePress 在 Vercel（base 为/）与 GitHub Pages（base 为/easy-vibe/）之间自动适配 base 路径的逻辑，这正是"路由与部署环境强相关"的又一实例。

3.5 阶段四：混合渲染——SPA + SSR 的终极方案

当 History 路由成熟后，团队开始思考更深层的问题：如何既保留 SPA 的流畅体验，又解决 SEO 与首屏问题？

这一阶段的核心是"同构渲染"（isomorphic rendering）——首次渲染在服务端完成（SEO 好、加载快），后续交互交给前端路由（体验流畅）。

开发方式：

• 框架选择：Next.js（React 系）、Nuxt.js（Vue 系）
• 渲染策略：服务端渲染 + 客户端水合（Hydration）
• 路由模式：History 模式（服务端已配置好）

该阶段特征：

• ✅优点：首屏快、SEO 好、后续交互流畅
• ❌缺点：实现复杂度高、需要服务器运行环境

混合渲染的工作方式：

页面加载流程：

1. 用户访问 /products/123 ↓ 2. 服务器接收请求 ↓ 3. 服务器渲染 ProductDetail 组件 → 生成完整 HTML ↓ 4. HTML 返回浏览器（内容完整） ↓ 5. 浏览器快速展示内容（首屏快） ↓ 6. JavaScript 加载完成，执行"水合"（Hydration） ↓ 7. 后续页面切换由前端路由接管（无刷新）

传统 SPA vs SSR 首屏对比：

4. 深入原理：路由到底是怎么工作的

看完实战案例，再深入路由的工作机制，理解 Hash 与 History 模式的本质差异。

4.1 Hash 模式的工作原理

Hash 模式的核心是利用 URL 的hash部分（#之后的内容）。Hash 有两个重要特性：

1. Hash 变化不会触发页面重载
2. Hash 变化会被记录在浏览器历史中

这意味着我们可以不刷新页面就改变 URL，同时浏览器的前进/后退按钮仍能正常工作。

工作流程：

用户点击链接 <a href="#/user/123"> ↓ 浏览器更新 URL（不重载页面） https://example.com/#/user/123 ↓ 触发 hashchange 事件 ↓ 路由监听器捕获事件 ↓ 解析 hash 值 → /user/123 ↓ 与路由配置匹配 → 找到 UserDetail 组件 ↓ 在页面中渲染组件

核心代码实现：

class HashRouter { constructor(routes) { this.routes = routes // 监听 hash 变化 window.addEventListener('hashchange', () => { this.loadRoute() }) // 初始加载 this.loadRoute() } loadRoute() { // 获取当前 hash，去掉开头的 # const hash = window.location.hash.slice(1) || '/' const route = this.matchRoute(hash) if (route) { this.render(route.component) } } matchRoute(path) { return this.routes.find(r => r.path === path) } render(component) { document.getElementById('app').innerHTML = component.template() } push(path) { window.location.hash = path } }

Hash 模式的优势：

• 兼容性好：支持 IE8+，几乎覆盖所有浏览器
• 部署简单：无需服务器配置，开箱即用
• 实现简单：只需监听hashchange事件

4.2 History 模式的工作原理

History 模式利用 HTML5 History API 的pushState和replaceState方法，它们可以在不重载页面的前提下修改 URL。

核心 API：

// 新增一条历史记录 history.pushState(state, title, url) // 示例：history.pushState({id: 123}, '用户详情', '/user/123') // 替换当前历史记录 history.replaceState(state, title, url) // 监听历史变化（浏览器前进/后退按钮） window.addEventListener('popstate', (event) => { // event.state 包含 pushState 时传入的 state })

工作流程：

用户点击链接 <a href="/user/123"> ↓ JavaScript 拦截点击事件 event.preventDefault() ↓ 调用 history.pushState history.pushState({id: 123}, '用户详情', '/user/123') ↓ URL 更新（不重载页面） https://example.com/user/123 ↓ 匹配路由并渲染组件 ↓ 用户点击浏览器后退按钮 ↓ 触发 popstate 事件 ↓ 路由监听器捕获事件 ↓ 根据新 URL 渲染对应组件

核心代码实现：

class HistoryRouter { constructor(routes) { this.routes = routes // 拦截所有链接点击 document.addEventListener('click', (e) => { const link = e.target.closest('a') if (link && link.getAttribute('href').startsWith('/')) { e.preventDefault() this.push(link.getAttribute('href')) } }) // 监听浏览器前进/后退导航 window.addEventListener('popstate', () => { this.loadRoute() }) // 初始加载 this.loadRoute() } loadRoute() { const path = window.location.pathname const route = this.matchRoute(path) if (route) { this.render(route.component) } } push(path) { history.pushState({}, '', path) this.loadRoute() } render(component) { document.getElementById('app').innerHTML = component.template() } }

⚠️History 模式的陷阱

History 模式最大的问题：用户直接访问某个 URL 或刷新页面时，浏览器会向服务器发送请求。

如果服务器没有正确配置，就会返回 404。解决方案是配置服务器将所有路由请求回退到index.html，把后续处理交给前端路由。

5. 路由配置实战指南

理论讲够了，下面是在真实项目中常用的路由配置模式与最佳实践。

5.1 基础路由配置

完整 Vue Router 配置示例：

// src/router/index.js import { createRouter, createWebHistory } from 'vue-router' import Home from '@/views/Home.vue' import NotFound from '@/views/NotFound.vue' const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: '/', name: 'Home', component: Home }, { path: '/user/:id', name: 'UserDetail', component: () => import('@/views/UserDetail.vue'), props: true // 将路由参数作为 props 传入 }, { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFound } ], scrollBehavior(to, from, savedPosition) { // 滚动行为：返回时保留位置，否则回到顶部 if (savedPosition) { return savedPosition } else { return { top: 0 } } } }) export default router

5.2 路由懒加载：优化首屏性能

路由懒加载指组件在访问到对应路由时才加载，而不是一次性加载所有组件。这能显著减少首屏时间。

// ❌ 一次性加载所有组件（首屏慢） import Home from '@/views/Home.vue' import About from '@/views/About.vue' import User from '@/views/User.vue' const routes = [ { path: '/', component: Home }, { path: '/about', component: About }, { path: '/user', component: User } ] // ✅ 懒加载（首屏快） const routes = [ { path: '/', component: () => import('@/views/Home.vue') }, { path: '/about', component: () => import('@/views/About.vue') }, { path: '/user', component: () => import('@/views/User.vue') } ]

懒加载的原理：使用import('@/views/Home.vue')时，Webpack/Vite 会把该组件打包成独立文件。只有用户真正访问该路由时，才下载对应文件。打个比方：懒加载就像"按菜单点菜"，而不是把全部菜品一次性端上桌，从而缩短首屏时间、提升用户体验。

5.3 路由守卫：权限控制与导航拦截

路由守卫可以在路由切换前后执行逻辑。常见用途包括权限校验、页面标题设置、数据预取等。

// 全局前置守卫 router.beforeEach(async (to, from, next) => { // 设置页面标题 document.title = to.meta.title || 'My App' // 权限校验 if (to.meta.requiresAuth) { const isAuthenticated = await checkAuth() if (!isAuthenticated) { next('/login') return } } next() }) // 全局后置钩子 router.afterEach((to, from) => { // 页面访问统计 analytics.trackPageView(to.path) }) // 路由级守卫 const routes = [ { path: '/admin', component: Admin, meta: { requiresAuth: true, roles: ['admin'] }, beforeEnter: (to, from, next) => { // 该路由专属逻辑 if (hasPermission()) { next() } else { next('/403') } } } ]

路由守卫的常见应用场景：

• 权限校验：检查用户是否有权访问某页面
• 页面标题：动态设置document.title
• 数据预取：进入页面之前获取数据
• 进度条：页面切换时显示加载进度
• 访问统计：记录页面访问数据

仓库佐证：easy-vibe 的交互组件库中RouteGuardsDemo.vue演示了守卫拦截导航的过程；整个 easy-vibe 站点本身也大量运用了 VitePress 的导航与跳转能力，例如 docs/index.md 中基于浏览器语言（navigator.language）用window.location.replace做语言跳转，本质上就是一次"程序化导航 + 守卫逻辑"的组合。

6. 常见问题与解决方案

6.1 部署后刷新出现 404

问题：本地运行一切正常，但部署到服务器后，直接访问某条路由或刷新页面时出现 404。

原因：History 模式下，服务器把 URL 当作文件路径去查找，但 SPA 的所有路由实际都指向index.html。

解决：配置服务器回退。

# Nginx 配置 location / { try_files $uri $uri/ /index.html; }

# Apache 配置（.htaccess） <IfModule mod_rewrite.c> RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L] </IfModule>

仓库佐证：easy-vibe 的 nginx.conf 与 vercel.json 正是两种部署形态的对照——Nginx 部署通过try_files回退保证 History 路由直链可访问；Vercel 部署则依赖其平台对 SPA 回退的内置支持，同时通过 headers 配置安全响应头。若你在 Vercel 上遇到路由 404，可参考 docs/DEPLOYMENT.md 的排障清单，优先检查VERCEL=1环境变量是否设置、base 路径是否与部署平台匹配。

6.2 路由参数丢失

问题：刷新页面后，$route.params中的路由参数丢失。

原因：路由参数只在路由切换过程中存在，刷新后需要从 URL 重新解析。

解决：

// ❌ 错误做法：只在 created 中获取一次参数 created() { const userId = this.$route.params.id this.fetchUser(userId) } // ✅ 正确做法：监听路由变化 watch: { '$route.params.id': { immediate: true, handler(newId) { this.fetchUser(newId) } } }

6.3 页面切换时滚动位置异常

问题：页面切换后滚动位置没有重置，或返回时没有保留之前的位置。

解决：配置路由的scrollBehavior。

const router = createRouter({ scrollBehavior(to, from, savedPosition) { // 返回时保留滚动位置 if (savedPosition) { return savedPosition } // 跳转到锚点 if (to.hash) { return { el: to.hash } } // 否则回到顶部 return { top: 0 } } })

7. 总结

用一张表汇总前端路由的核心概念：

前端路由是单页应用的核心技术之一。从早期的 Hash 模式到如今的 History 模式，路由技术持续演进，只为给用户带来更流畅的浏览体验。理解路由的原理与模式，你在遇到部署、性能、SEO 问题时就能快速定位根因并精准解决；更重要的是，这能帮助你在架构规划时做出更明智的选择——何时用 Hash、何时用 History，以及如何避开常见陷阱。

如果你在自己的项目中遇到路由问题，现在你应该知道从哪里入手、如何定位、如何解决了。本文所涉及的路由模式对比、部署回退与懒加载等实践，均可在 easy-vibe 仓库的 nginx.conf、vercel.json、docs/DEPLOYMENT.md 以及 docs/.vitepress/theme/components/appendix/frontend-routing/ 交互组件中找到可对照的真实案例，建议动手实验加深理解。

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe