企业官网建设流程全解析

前端路由从原理到实战：在 easy-vibe 项目中理解 Hash 模式、History 模式与 SPA 导航

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

导读：为什么有些网站点击链接时毫无白屏闪烁，体验流畅得如同原生应用？这正是前端路由的功劳。本文以 easy-vibe 开源课程仓库中《An Introduction to Routing and Navigation》章节（docs/en/appendix/3-browser-and-frontend/routing-navigation.md）为骨架，系统讲解路由与导航的核心概念、Hash 与 History 两种路由模式的工作原理、从传统多页应用（MPA）到单页应用（SPA）再到 SSR 混合渲染的演进脉络，并结合本仓库真实的部署配置（nginx.conf、vercel.json）给出可直接落地的实战方案。读完本文，你将能够独立诊断"部署后刷新 404"这类经典问题，并能在 Hash 与 History 模式之间做出正确选型。

1. 为什么需要前端路由：从传统网站到 SPA 的体验跃迁

1.1 传统网站（MPA）与单页应用（SPA）的本质差异

回想互联网早期，每次点击链接都是一次完整的"翻页"：白屏一闪、加载图标旋转、整个页面重新渲染。在慢速网络下，用户盯着加载图标等待数秒是常态。这种体验在今天看来已经落伍，但在当时却是标准做法。

现代前端开发彻底改变了这一模式。我们借助前端路由技术让页面切换像手机 App 一样顺滑——没有白屏闪烁，没有加载图标，用户几乎感知不到"导航"的存在。这一进步并非魔法，而是前端路由系统的工作成果。

这就是前端路由要解决的核心问题：在不刷新页面的前提下，完成视图切换并同步 URL。

在 easy-vibe 仓库中，为了帮助学习者直观理解"路由匹配"的过程，配套实现了一个可交互的 Demo 组件 RouteMatchingDemo.vue：你可以在输入框中输入任意路径（如user/123），组件会实时展示它命中的路由表项、以及从路径中提取出的动态参数（如id = 123）。从源码（第 112～153 行的matchPath函数）可以看到，它完整模拟了:param动态参数提取、(.*)*兜底匹配、可选参数（?后缀）等路由匹配规则——这正是 Vue Router 内部路径匹配逻辑的简化缩影。

1.2 一个真实翻车案例：为什么要理解路由模式

你可能会想："我直接用 Vue Router 或 React Router，配几条路由就能跑，为什么还要理解底层原理？"下面这个真实故事会让你明白为什么这些知识至关重要。

::: warning 小李的部署噩梦 小李是一名初级前端开发，负责开发一个基于 Vue 的 SPA。本地开发一切正常，路由切换行云流水。但把项目部署到测试服务器后，问题出现了：当用户直接访问example.com/user/123这样的路由，或刷新详情页时，看到的是404 Not Found错误。

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

最后他请教了一位资深同事，对方一眼看出问题所在：小李使用的是 History 模式，但服务器没有配置 fallback。当用户直接访问/user/123时，服务器会尝试在文件系统中查找该路径对应的文件——但在 SPA 中，所有路由都指向同一个index.html。解决办法很简单：配置服务器将所有路由都回退到index.html，把路由解析交给前端路由接管。 :::

::: info 💡 核心启示 前端路由不是"黑魔法"。理解它的工作原理，你就能快速定位并解决部署、性能与 SEO 问题；更重要的是，它能帮你做出更明智的架构决策——何时用 Hash 模式、何时用 History 模式，以及如何避开常见的坑。 :::

2. 核心概念：路由、路由模式与导航

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

路由（Route）、路由器（Router）、路由模式（Mode）、导航（Navigation）是前端路由系统的四大支柱。当使用 Vue Router 或 React Router 时，框架替你处理了：

1. 路由映射→ 定义 URL 与组件之间的对应关系；
2. 模式选择→ 决定使用 Hash 还是 History 模式；
3. 导航控制→ 处理页面切换、浏览器前进/后退。

理解这四者的区别至关重要：路由是静态配置，路由器是动态管理者，模式是技术选型，导航是用户行为。

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

路由本质上是一份"契约"：规定访问某个 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 的本质：SPA 只有一个 HTML 页面，所有"页面切换"本质上是在这一个页面内完成组件替换。如果使用传统的<a href="/user/123">，浏览器会真的向/user/123发起请求，从而引发整页刷新甚至 404。路由器的工作就是拦截这些导航行为，通过 JavaScript 动态替换组件，实现无刷新切换。

::: details 🔧 常见路由配置模式静态路由（最简单）：

{ 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 两个组件，分别对动态参数路由和嵌套路由的匹配过程做了可视化演示；RouteMatchingDemo.vue 的matchPath实现还特别处理了:path(.*)*通配兜底段，与 Vue Router 的/:pathMatch(.*)*语法一一对应。

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

前端路由有两种主流实现模式：Hash 模式和 History 模式。它们在 URL 格式、底层实现与兼容性上有本质差异。

::: tip 🤔 为什么会有两种模式？ 这是历史沿革与技术权衡共同作用的结果。

Hash 模式是最早的前端路由方案。它利用 URL 中#之后的部分（hash）。hash 的变化不会触发页面刷新，且兼容性极佳（连 IE8 都支持）。

History 模式是 HTML5 引入的"标准方案"。它借助 History API 的pushState与replaceState方法，让 URL 看起来"正常"（没有#），但要求服务器端配合。

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

仓库中 HashVsHistoryDemo.vue 组件对这一对比做了可视化呈现；配套的 RoutingModesDemo.vue 则模拟了两种模式下 URL 变化与页面渲染的关系。

::: tip 📊 表格逐行解读URL 示例：Hash 模式 URL 带明显的#，用户一眼就能认出是 SPA；History 模式 URL 与传统网站一致，看起来更"专业"。

实现方式：Hash 模式监听hashchange事件（hash 变化时触发）；History 模式使用 HTML5 History API，可以"假装"发生了页面导航而实际上没有刷新。

服务器配置（最常见的坑！）：Hash 模式下#之后的内容永远不会发送到服务器，所以服务器无需知道路由的存在；但 History 模式下完整路径会发给服务器——如果配置不当，就会得到 404。

SEO 友好度：搜索引擎爬虫通常不执行 JavaScript，因此 Hash 模式的 URL 可能被忽略；History 模式 URL 结构干净，更容易被收录。

部署难度：Hash 模式"开箱即用"；History 模式需要运维知识（Nginx、Apache 等）。这也是很多个人项目默认用 Hash 模式的原因。 :::

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

下面通过一个电商网站逐步从传统多页应用演进到带路由的现代 SPA 的真实案例，直观理解前端路由解决的问题。

::: tip 📖 背景：什么是 MPA、SPA、SSR？

• MPA（多页应用）：传统建站方式。每个页面是独立的 HTML 文件，导航触发整页刷新。
• SPA（单页应用）：现代前端主流方案。只有一个 HTML 入口，页面切换靠 JavaScript 动态替换组件——无刷新。
• SSR（服务端渲染）：在服务端生成完整 HTML，兼取 SPA 与 MPA 之长——首屏渲染快且 SEO 好。

简单记忆：MPA 是"每次整页重画"，SPA 是"在同一张纸上擦掉重画"，SSR 是"纸到你手里时已经画好了"。 :::

3.1 演进全景

::: tip 📊 演进逻辑解读阶段 1 → 阶段 2：从"有刷新"到"无刷新"，是质的飞跃。用户第一次体验到类 App 的流畅感，代价是 URL 里多了个不专业的#。

阶段 2 → 阶段 3：从"能用"到"好用"。History 模式让 URL 干净、贴近传统网站，代价是部署复杂度上升（需要服务器配置）。

阶段 3 → 阶段 4：从"体验好"到"体验好 + SEO 好"。SSR 解决了 SPA 的 SEO 问题并加快了首屏渲染，但显著提高了实现复杂度。

小结：前端路由的演进不只是"切换更快"，而是整个应用架构的升级——从服务端驱动到客户端驱动，再到二者混合，每一步都在 UX、开发成本、SEO 等维度之间做权衡。 :::

3.2 阶段 1：传统多页应用——每次导航都刷新

在这个阶段，每个页面都是独立的 HTML 文件，浏览器在每次导航时重新下载全部资源（HTML、CSS、JS）。这是最早期的主流建站方式，许多传统站点至今仍如此运作。假设电商网站"BuyMore"当时就是典型的 MPA 架构：

开发方式：

• 路由：服务端路由——每个页面对应服务器上的一个 HTML 文件；
• 导航：使用<a href="/products/123">，触发整页刷新；
• 状态管理：每次导航都会丢失页面状态（滚动位置、表单内容等）。

该阶段的特征：

• ✅优点：实现简单、对搜索引擎友好（SEO 好）、浏览器前进/后退开箱即用；
• ❌缺点：每次导航都刷新，体验差；服务器负载高（反复下载相同资源）。

::: details 项目结构与导航流程项目结构（典型的服务端渲染布局）：

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；
• 浏览器前进/后退都会重新加载页面；
• 无法保留复杂页面状态（筛选条件、滚动位置）。 :::

这种方案在小网站时代尚可忍受，但随着网站规模扩大、用户期望提高，这些问题开始严重影响用户留存和转化率。仓库中的 MpaRoutingDemo.vue 组件模拟了传统多页应用"每次跳转都整页刷新"的交互过程，可以与 SPA 的流畅切换形成直观对照。

3.3 阶段 2：早期 SPA——Hash 路由时代

随着传统 MPA 的问题不断累积，BuyMore 团队决定采用前端路由，升级为 SPA 架构。这是一个重要的转折点——从"服务端驱动"转向"客户端驱动"。

这个阶段也有代价：URL 中的#看起来不够专业，搜索引擎收录也有问题。

开发方式：

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

该阶段的特征：

• ✅优点：无刷新切换、体验流畅、服务器负载降低；
• ❌缺点：URL 带#、SEO 差、首屏加载较慢。

::: details 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 Workers 可支持离线访问。

新痛点：

1. URL 不美观：#让 URL 看起来像"锚点跳转"，不够专业；
2. SEO 问题：搜索引擎爬虫可能忽略 hash 之后的内容，导致无法收录；
3. 首屏加载慢：所有 JavaScript 必须一次性加载，增加首屏时间。 :::

3.4 阶段 3：现代 SPA——History 路由成为主流

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

History 路由借助 HTML5 History API 让 URL 看起来"正常"（没有#），代价是必须获得服务器的配合。

开发方式：

• 路由：History 路由，使用pushState与replaceState；
• 路由库：成熟的 Vue Router、React Router 等；
• 服务器配置：必须配置服务器将路由回退到index.html。

该阶段的特征：

• ✅优点：URL 干净、SEO 友好、体验流畅；
• ❌缺点：需要特殊的部署配置，必须服务端配合。

::: details 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 模式对比： | 对比项 | Hash 模式 | History 模式 | |--------|----------|-------------| | URL |/#/products/123|/products/123| | 服务器配置 | 不需要 |必须配置| | 直接访问 | ✅ 正常 | ❌ 需要服务器支持 | | SEO | ⚠️ 较差 | ✅ 良好 | :::

仓库实证：easy-vibe 项目本身的 History 模式部署

这一节的 Nginx 配置绝非纸上谈兵。easy-vibe 仓库根目录的 nginx.conf 就是一份真实的生产配置，其中核心一行正是文档中强调的 fallback 规则：

location / { try_files $uri $uri.html $uri/ /index.html; }

注意，该配置在文档示例的基础上做了两个实战增强：

1. 增加了$uri.html：先尝试"无扩展名路径 + .html"的文件（如/docs/index→/docs/index.html），这对静态站点中"美化过的 URL"很友好；
2. 明确了静态资源缓存策略：location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; }——对带内容 hash 的静态资源做一年长效缓存，避免每次刷新重复下载。

同时，仓库还提供了面向 Vercel 部署的 vercel.json，其中"framework": "vitepress"、"outputDirectory": "docs/.vitepress/dist"说明了构建产物位置，而"headers"中针对/sitemap.xml、/robots.txt的Cache-Control配置则体现了对 SEO 与静态资源交付的完整考量。这两份文件共同构成了一套可对照学习的"History 模式静态站部署"实战素材。

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

History 路由成熟之后，团队开始思考更深层的问题：如何在保留 SPA 流畅体验的同时，解决 SEO 与首屏加载慢的问题？

这个阶段的核心是"同构渲染"——首屏在服务端渲染（SEO 好、加载快），后续交互由前端路由处理（体验流畅）。

开发方式：

• 框架选型：Next.js（React 生态）、Nuxt.js（Vue 生态）；
• 渲染策略：服务端渲染 + 客户端水合（hydration）；
• 路由模式：History 模式（服务器已配置好）。

该阶段的特征：

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

::: details 混合渲染是如何工作的页面加载流程：

1. 用户访问 /products/123 ↓ 2. 服务器收到请求 ↓ 3. 服务器渲染 ProductDetail 组件 → 生成完整 HTML ↓ 4. 将 HTML 返回给浏览器（包含完整内容） ↓ 5. 浏览器快速展示内容（首屏渲染快） ↓ 6. JavaScript 加载完成，执行水合（hydration） ↓ 7. 后续导航交给前端路由处理（无刷新）

传统 SPA 与 SSR 首屏对比： | 对比项 | 传统 SPA | SSR | |--------|---------|-----| | 首屏内容 | 白屏 → 加载 JS → 渲染 | 立即显示内容 | | SEO | 爬虫可能看不到内容 | 爬虫能看到完整 HTML | | 首屏时间 | 较慢（需要加载 JS） | 更快（HTML 已含内容） | | 后续交互 | 流畅（前端路由） | 流畅（前端路由） | :::

4. 深入原理：路由到底是如何工作的

前面看了真实案例，现在深入前端路由的底层工作原理，理解 Hash 与 History 模式的真正区别。仓库中的 RouterArchitectureDemo.vue 与 SpaNavigationDemo.vue 分别从"路由系统架构"与"SPA 导航过程"两个视角给出了可视化示意。

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 } }

::: tip 💡 Hash 模式的优点

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

4.2 History 模式的工作原理

History 模式利用 HTML5 History API，它提供pushState、replaceState等方法，可以在不刷新页面的情况下修改 URL。

核心 API：

// 添加一条新的历史记录 history.pushState(state, title, url) // 示例：history.pushState({id: 123}, 'User Detail', '/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 Detail', '/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() } }

::: warning ⚠️ History 模式的陷阱 History 模式最大的问题是：当用户直接访问 URL 或刷新页面时，浏览器会向服务器发起请求。

如果服务器没有正确配置，就会返回 404。解决办法是配置服务器将路由全部回退到index.html，让前端路由接管后续解析。这正是 easy-vibe 仓库 nginx.conf 中try_files $uri $uri.html $uri/ /index.html;一行存在的意义。 :::

5. 路由配置实战指南

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

5.1 基础路由配置

::: details 完整的 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

:::

配置要点解读：

• createWebHistory(import.meta.env.BASE_URL)：传入 Vite 构建时的base路径，可保证子路径部署时路由前缀正确；
• props: true：让路由参数自动以 props 形式注入组件，组件内部不需要再写$route.params，更利于组件复用与单元测试；
• scrollBehavior：统一管理切换路由后的滚动位置，见 6.3 节。

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') } ]

::: tip 💡 懒加载是如何工作的 当你使用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') } } } ]

::: tip 💡 路由守卫的常见用途

• 鉴权：检查用户是否有权访问页面；
• 页面标题：动态设置document.title；
• 数据预取：进入页面之前先拉取数据；
• 进度条：页面切换过程中展示加载进度；
• 统计：追踪页面浏览。 :::

仓库中的 RouteGuardsDemo.vue 组件对"前置守卫拦截 + 重定向"的过程做了交互式演示，可以直观看到requiresAuth元信息与next('/login')重定向的配合效果。

6. 常见问题与解决方案

6.1 部署后刷新出现 404

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

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

解决方案：配置服务器 fallback。

# 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 中try_files $uri $uri.html $uri/ /index.html;正是同一思路的工程化实践——除了回退index.html，还额外兼容了$uri.html这类"无扩展名 URL 映射到同名 HTML 文件"的场景，适合文档站点的目录型路由。

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) } } }

要点：immediate: true保证组件首次创建时立即执行一次取数逻辑，同时监听后续同一组件内参数变化（例如从/user/1导航到/user/2），避免"组件复用但数据不更新"的经典 bug。

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. 总结

用一张表回顾前端路由的核心概念：

::: info 结语 前端路由是现代单页应用的核心技术之一。从早期的 Hash 模式到如今主流的 History 模式，路由技术不断演进，为用户带来了更流畅的浏览体验。

理解路由的原理与模式，你就能快速定位并解决部署、性能与 SEO 问题；更重要的是，它能帮你做出更明智的架构决策——何时用 Hash 模式、何时用 History 模式、如何规避常见坑。

进一步探索：本文的理论分析均可对照 easy-vibe 仓库中的真实资源继续深挖——

• 章节全文：docs/en/appendix/3-browser-and-frontend/routing-navigation.md；
• 交互式 Demo 组件（路由匹配、Hash vs History 对比、路由架构、路由守卫等）：docs/.vitepress/theme/components/appendix/frontend-routing/；
• 真实部署配置：nginx.conf 与 vercel.json；
• 项目构建工具链（VitePress + Vue 3）：package.json。 :::

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