一个后台管理系统,本地开发怎么点都正常。上线第一天,客服在订单列表点开某一单,详情页刷出来了;她把这一页的地址复制给同事,同事打开却是 404,连登录框都没看到。运维查了十分钟,发现服务器上根本没有那个路径,请求被当成了一个不存在的静态文件。

同一周还有另一条工单。销售角色登录后打开财务报表,表格已经画出上半屏的数字和客户名,停了一秒,一个「无权限访问」的提示弹出来,页面被跳回首页。用户的第一反应是「你们系统把数据泄露给我了」,第二反应是「为什么先给我看再告诉我不能看」。

这两个故障看着无关,实际上指向同一件事:URL 没被当成应用状态。前者是地址变了服务端不认识,后者是地址已经进来、页面开始渲染,才在组件里补做判断。这篇按这条线讲:路由做了什么、两种模式差在哪、嵌套路由怎么组织布局、参数怎么取、守卫放哪层、懒加载与 404 怎么处理,最后给出部署兜底配置。

路由干的三件事:拦跳转、改地址、换视图

很多人把前端路由理解成「点一下换一个页面」。这个说法漏掉了最关键的部分:页面其实没有换,换的是地址栏和当前渲染的那块视图,浏览器并没有真的去请求一个新文档。把这件事拆开,路由库在每次站内跳转时只做三步。

一次站内跳转经过的步骤
用户点击站内链接
路由拦截,阻止浏览器默认跳转
用 History API 改写地址
按新地址匹配路由表并渲染视图

第一步是拦。<a href="/orders/1024"> 本身是浏览器行为,点下去就会发请求、整页刷新。路由库在根节点上挂了点击监听,判断这个链接是不是站内的、有没有被修饰键打开,是就 preventDefault 掉,自己接管。这也是为什么有些用 window.location.href 硬跳的代码会绕过守卫和加载态:它根本没经过路由库。

第二步是改地址。浏览器的 history.pushState 可以在不发请求的情况下换掉路径,同时往历史栈里压一条记录;replaceState 则替换当前记录。这两个方法的具体行为在浏览器 API那篇里有更细的说明,路由库只是把它们包了一层。

第三步是渲染。路由表是一棵配置树,每一条把路径模式和要渲染的组件对上。地址一变,路由库重新匹配,卸载不再匹配的视图,挂载新匹配的视图。所谓「路由表是唯一事实来源」,意思就是:哪个地址对应哪个页面,只应该在这张表里写一次。如果页面里再出现 if (location.pathname === "/orders") 这种判断,规则就分裂成了两份,早晚对不上。

验收真路由只看三个动作:刷新当前页,地址还在、页面能开;按后退,能回上一页;把地址粘到新标签页,能直接进到同一位置。有一条不成立,就说明路由只在点击路径上成立。

hash 和 history:差别只在刷新时谁去求服务端

两种模式的 API 用法几乎一样,真正的差别只有一个:地址变了之后,浏览器会不会向服务端请求一个新文档。

hash 模式:井号后面的内容不发给服务端

地址形如 https://example.com/#/orders/1024。浏览器在发请求时会把井号及其后面的部分丢掉,服务端只收到根路径 /,返回同一个 index.html。前端拿到地址后自己解析 #/orders/1024,再渲染详情页。因为服务端永远只看到一个入口,刷新、收藏、分享都不会 404。

代价是地址不好看,分享出去带一长串井号,统计和 SEO 都吃亏。好处是零服务端配置,静态托管、内网、离线包都能直接跑。

它靠 hashchange 事件感知变化,兼容性极好,在完全改不了服务端配置的机器上是最省事的退路。

history 模式:地址干净,但服务端必须兜底

地址形如 https://example.com/orders/1024。点击跳转时 pushState 只改地址不发请求,应用内部一切正常。问题在「从外部进入」:刷新、收藏夹、微信里点开,浏览器都会真请求 /orders/1024,服务器上没有这个文件,只能返回 404。这就是开头那个故障。

hash 模式

服务端只看到根路径,刷新永远安全,部署零配置。代价是地址带井号,分享和统计都不太好看,SEO 基本拿不到分。适合无法改服务端、或者应用只在内网跑的场景。

history 模式

地址干净、可分享、对 SEO 友好,但要求服务端把未匹配的页面路径回退到 index.html。少配这一条,刷新和外部打开就会 404。适合能改 nginx 或网关配置的项目。

从 hash 切到 history,用户收藏的旧地址会打不开。切换前要么保留一段兼容跳转,要么接受这批链接作废。

部署在子路径(比如 /admin/)时,路由 base 和打包资源前缀要一起改。只改一个,表现就是页面能开但 JS、CSS 全 404,或者资源正常但路由匹配不上。

嵌套路由是布局的骨架,不是省代码的语法

后台的列表页和详情页通常共用侧边栏、顶栏和面包屑。写成两条平级路由,每个页面都要重渲染一遍布局;改成父子路由,父级渲染布局,子级只填内容区。嵌套路由解决的就是这个结构问题。

根布局:侧边栏、顶栏、全局提示,只挂载一次
模块布局:订单模块的筛选栏、二级菜单、模块级 loading
页面:列表表格或详情内容,只关心自己的数据

以 /orders/:orderId 为例,父路由是 /orders,子路由是 :orderId。父组件负责布局,并在内容区留一个出口,React Router 里是 <Outlet />,Vue Router 里是 <router-view />。子路由匹配成功时,内容就渲染进这个出口。这样切换订单详情时,侧边栏不会重建,滚动位置、菜单展开状态、甚至一些全局的 WebSocket 连接都能保住。

拍平写的问题不会立刻暴露,而是随页面增多显现:加一个导出页就要复制一遍布局;改侧边栏宽度要改十几个文件;权限和加载态也跟着复制,规则一旦分散就很难一致。

父级布局只该管结构和公共交互,比如当前菜单、全局提示、登录态展示。把订单列表数据塞进布局,详情页会被迫等列表接口,切换时还会闪一下。

嵌套层数要克制。三层通常够用:根布局、模块布局、页面。到第四层,URL 变长,面包屑难表达,权限继承也开始绕;真需要更细的结构,优先拆组件。

路径参数和查询参数:一个指资源,一个指看法

/orders/1024 里的 1024 是路径参数,它回答「哪一个订单」。/orders?status=pending&page=2 里的 status 和 page 是查询参数,它们回答「这批订单按什么条件看、看第几页」。两者的生命周期不一样:路径参数缺了,这个页面就不成立;查询参数缺了,页面应该有一个合理的默认值。

取法上,React Router 6 用 useParams 和 useSearchParams,Vue Router 4 从 route.params 和 route.query 里拿。两边名字不同,概念一一对应。下面这段只针对 React Router 6,不要和 Vue 的写法混着抄。

// React Router 6:路径参数与查询参数分开取
const { orderId } = useParams();
const [searchParams] = useSearchParams();

const page = Number(searchParams.get("page") ?? "1");
const status = searchParams.get("status") ?? "all";

两个坑几乎每个项目都会踩。第一,取出来的值全是字符串:page 拿到的是 "2" 不是 2,直接做加法会拼成 "21",Number() 之后还要判 NaN。第二,空值和缺失值不一样:?status= 取到空字符串,?status 取到空字符串还是 null 要看具体实现,业务里最好统一归一化,不要在每个页面各写一套判断。

另外,路径参数里放中文或斜杠要手动编码,拼查询串时也要处理 &、=、#。token、手机号这类敏感信息不要放进 URL,它们会进浏览器历史、代理日志和监控系统。

守卫放在路由层,认证和细粒度权限分开

权限判断写进页面组件,最典型的一版是这样:页面加载后先发请求拿数据,渲染表格,然后在 useEffect 里判断角色,不通过就跳走。问题是顺序错了。请求已经发出去,数据已经进了内存,半屏内容已经画出来,用户当然会先看到再被弹走。如果那个接口本身没做权限校验,数据甚至已经泄露了。

正确的层次是:在进入这个路由、渲染页面之前就判断完。登录态检查放最外层,叫认证;某个角色能不能进这个页面,放路由的元信息里,叫授权。两者分开写,不要在一个守卫函数里揉成一团。

认证是一个全局守卫:白名单直接放行,其余检查登录态。授权跟着路由走,路由表写清需要哪些角色,由同一个守卫读取。菜单权限和路由权限要共用一份配置,否则会出现「菜单看不到,手动输地址却能进」的漏洞。

React Router 6 的常见做法是用包装组件,在渲染子节点之前返回重定向。下面这段只写 React,Vue 的写法放在后面单独一段。

// React Router 6:认证守卫包在页面外层
function RequireAuth({ children }) {
  const user = useCurrentUser();
  if (!user) {
    return <Navigate to="/login" replace />;
  }
  return children;
}

// 路由表里直接体现层级:先认证,再渲染
<Route path="/orders/:orderId" element={
  <RequireAuth><OrderDetail /></RequireAuth>
} />

Vue Router 4 用全局前置守卫,从 to.meta 里读配置。下面这段是 Vue 的,不要和上面的 React 代码拼在一起用。

// Vue Router 4:全局守卫读 meta,页面组件里不再判断
router.beforeEach((to) => {
  if (to.meta.public) return true;
  if (!store.state.user) return { path: "/login" };

  if (to.meta.roles && !to.meta.roles.includes(store.state.role)) {
    return { path: "/403" };
  }
  return true;
});

前端守卫只是体验层,不是安全边界:用户可以改存储、改参数、直接调接口。接口仍要在服务端校验权限,前端守卫的价值是少让人看到不该看的界面。

重定向的循环是怎么写出来的

守卫的死循环有三种:登录页自己被「需要登录」拦住;跳转目标又被另一条规则拦回原处;403、404 页面不在白名单里。表现都是地址栏反复跳,最后浏览器报重定向过多。

排查时先列出所有公开路径:登录、注册、403、404、维护页。白名单覆盖这些,顺序是「先白名单,再认证,再授权」。重定向用 replace,否则历史栈会堆一串重复记录。

登录回跳参数也要校验:只允许以单个斜杠开头的站内路径,站外地址一律回首页,否则会被拿去做开放重定向。

「重定向次数过多」不是浏览器 bug,是守卫规则自相矛盾。出现时不要靠加延时或加计数器绕过,回到路由表,把每条规则的入口和出口列出来,循环点一定在某个入口上。

懒加载、加载态和 404 兜底

路由级懒加载是最划算的优化之一:首屏只下载当前页面需要的代码,其他页面在跳转时才去取。写法上就是把页面组件从静态导入改成动态导入,路由表本身不变。

// React Router 6:路由级懒加载
import { lazy } from "react";

const OrderDetail = lazy(() => import("./pages/OrderDetail"));

懒加载必须配加载态。不配的话,切换页面白屏几百毫秒,弱网能到两三秒,用户以为点没了。加载态放在布局层统一处理,骨架屏比转圈更好,能提前占位,避免内容出现时跳动。

发版后还有个坑:用户开着旧页面点新路由,请求的是旧文件名,服务器已经换成新文件,于是报加载失败。办法是捕获错误并提示刷新,同时保留上一版资源一段时间。

404 路由要单独设计:路由表最后加一条通配规则。它必须放最后,放前面会把正常页面吃掉。嵌套路由里父子都可有兜底,但要明确哪一层负责展示「页面不存在」。

还要区分两种不存在:地址写错显示全站 404;地址对但订单被删,显示「订单不存在」的空态,并给返回列表的入口。把后者也做成全站 404,用户会以为系统坏了。

完整场景走查:订单详情页从能跑到能上线

需求:订单详情页地址是 /orders/:orderId;登录后能看;只有运营和财务两个角色能看,其他角色进 403;从列表点进来、刷新、分享链接打开都要正常;加载时有骨架;订单不存在时显示空态;没有匹配的地址显示 404。

第一版通常这么写,本地跑起来毫无问题:

function OrderDetail() {
  const { orderId } = useParams();
  const [order, setOrder] = useState(null);

  useEffect(() => {
    fetch("/api/orders/" + orderId)
      .then((r) => r.json())
      .then(setOrder);
  }, [orderId]);

  if (!canView(user.role)) return <Navigate to="/403" />;
  return <OrderCard order={order} />;
}

这段代码有五个问题。第一,canView 在渲染末尾,而 useEffect 挂载后就执行,无权限用户的请求已经发出去、数据也回来了。第二,user 从全局直接读,每个页面都重复判断。第三,order 初始是 null,OrderCard 读 order.no 会在首帧报错。第四,没处理接口 404。第五,线上没配 fallback,刷新还是 404。

改法按层次来。先把守卫提到路由层:认证守最外面,角色守卫套在里面,页面组件只负责拿数据和渲染。再给路由加兜底和懒加载,加载态放在布局里统一处理。

// React Router 6:守卫只出现在路由表里
const routes = [
  {
    path: "/orders/:orderId",
    element: (
      <RequireAuth>
        <RequireRole roles={["ops", "finance"]}>
          <OrderDetail />
        </RequireRole>
      </RequireAuth>
    )
  },
  { path: "*", element: <NotFound /> }
];

页面里只保留三种状态:加载中显示骨架,出错显示可重试提示,成功才渲染内容。接口返回 404 时渲染「订单不存在」,不要跳全站 404,让用户知道自己没进错地方。

然后处理部署。nginx 把未匹配的页面路径回退到 index.html,但要排除接口和资源目录,否则接口 404 会变成一段 HTML,缺失的 JS 被回成 HTML,浏览器报 MIME 类型错误,看着像构建坏了。

最后是分享场景。从列表点进详情用普通跳转,后退能回到列表;守卫拦截造成的跳转用 replace,别把「无权限」和「登录页」也塞进历史。进入方式、权限、数据状态、刷新、分享都各自有着落,这条链路才算闭合。

部署兜底与故障对照

兜底配置就一句话:真实文件存在就返回文件,不存在就返回入口 HTML,接口和资源目录例外。下面这份可以直接照着改。

server {
  listen 80;
  root /var/www/order-admin;

  # 接口照常转发,不要被下面的 fallback 吃掉
  location /api/ {
    proxy_pass http://127.0.0.1:8080;
  }

  # 静态资源找不到就返回 404,不要回入口 HTML
  location /assets/ {
    try_files $uri =404;
  }

  # 其余路径交给前端路由处理
  location / {
    try_files $uri $uri/ /index.html;
  }
}

try_files 的顺序是:先找同名文件,再找同名目录,都没有就返回 /index.html。如果应用部署在子路径,root、资源前缀、路由 base 三处要一起改,只改一处就会出现「页面能进但样式丢了」。

现象真实原因第一步查什么
点进详情正常,刷新或分享出去打开是 404服务端没有把页面路径回退到入口 HTML用 curl 直接请求该地址,看返回的是页面还是 404
有权限的角色也被跳到 403路由里配的角色名和用户身上的角色值大小写、单复数不一致把路由 meta 和用户 role 原样打印出来对比
登录后一直停在登录页,地址栏反复跳登录页自己被认证守卫拦住,形成重定向循环看守卫白名单里有没有登录页、403 和 404
详情页拿到的 id 是 undefined路由定义用的是 :id,取值时写成了 orderId对照 path 字符串和取参的键名
切走再回来,同一份数据被请求两次页面里自己发请求,同时 loader 也发了一次;或依赖数组写错看 Network 面板的请求次数和触发时机
线上白屏,控制台提示加载 chunk 失败发版后旧文件被清掉,旧页面还在请求旧文件名看失败请求的 URL 是否带旧版本号

最后一条常被误判成网络问题,实际是部署与缓存策略没对齐:HTML 不该长缓存,JS 和 CSS 长缓存并带内容哈希,旧资源再保留一段时间。

边界与代价:路由不是越全越好

难的不是用路由库,是决定「什么该进 URL」。这条线划不好,页面能跑,用起来别扭。

  • 只有两三个页面、没有嵌套和权限,别上路由库。原生 history 加简单路径匹配就够,少一层依赖。
  • 筛选要有选择地进 URL。分页、状态、排序这类「刷新后还该在」的条件值得写进查询参数;输入草稿、弹窗开关、滚动位置不该进。每次输入都 push,用户按后退要按二十次才回上一页,输入即筛选应当用 replace。
  • 嵌套超过三层,路由表难读,面包屑也难表达;此时该拆模块,不是加层级。
  • 守卫数量会随页面增长。每个页面自带一套判断,规则一定分散。把认证、角色、菜单三份判断收敛到一张权限表,比多写几个守卫函数有用。
  • 懒加载切得太碎,请求数会变成新的瓶颈;切得太粗,首屏包又回到原点。按页面切是默认值,除非有明确数据支撑,不要按组件切。
  • hash 模式在需要 SEO 的公开站点上基本不能用;history 模式在无法改服务端的环境里也不能用。选型不是喜好问题,是部署条件问题。

一句话的判断:URL 里只放「换台设备打开也应该看到同样内容」的状态。放不进去的,说明它属于本地交互,应该留在组件里。

今天就能验证的练习,和小结

  1. 建两个页面 /a 和 /b,用 history 模式,构建后直接用浏览器打开 /b。先看它 404,再加一条 try_files 规则,确认刷新能进。把两次的 curl 返回贴在一起对比。
  2. 把详情路由写成 /orders/:id,在页面里打印 typeof id,确认是字符串;再传一个中文参数,看地址栏是否被编码,不编码时页面会不会挂。
  3. 故意让登录页也要求登录,观察重定向循环的表现;然后把登录页、403、404 加进白名单,确认循环消失。这个过程比背规则有用。
  4. 给一个页面加懒加载和骨架屏,把网络限到 Slow 3G,记录切换时的白屏时长;去掉加载态再对比一次。
  5. 在一个列表页连续点五次筛选,按后退键,数要按几次才回上一页;把筛选跳转改成 replace 再试。
路由做三件事:拦住站内跳转、改写地址、按地址渲染视图。路由表应是地址与页面的对应关系。
hash 模式不依赖服务端,history 模式必须配 fallback;刷新 404 先查部署,不要先查组件。
嵌套路由描述的是布局层级;路径参数指资源,查询参数指看法,取出来先归一化再使用。
认证和授权都放在路由层,页面组件不重复判断;前端守卫不是安全边界,接口仍要服务端校验。
懒加载要配加载态和失败处理,404 要区分「地址错」和「资源没了」。

路由把应用切成一个个视图之后,新问题马上出现:每个视图都有自己的模板和样式,一个叫 .title 的类可能在列表页、详情页、弹窗里各定义过一次,加载顺序一变,样式就串了。下一篇样式方案顺着这个问题讲:CSS Modules 怎么把类名变成局部变量,原子化拿什么换一致,运行时 CSS 什么时候值得它的开销。路由决定「哪个组件出现」,样式决定「它长什么样」,两件事在同一个页面上碰头,接着看更顺。想补基础的,可以回头看浏览器 API里 History 那一节,以及链接与媒体里关于链接行为的说明。