从地址栏到 Next.js Proxy：浏览器导航与路由的完整链路

URL
↓
浏览器导航
↓
历史记录
↓
Next.js 客户端路由
↓
服务端路由与 HTTP 重定向

window.location.href = "/dashboard";

GET /dashboard
Type: document

router.push("/dashboard");

可能产生网络请求
但不是传统的整页刷新

history.pushState(null, "", "/dashboard");

console.log(window.location.href);
 
window.location.href = "/dashboard";
window.location.assign("/dashboard");

window.location.replace("/dashboard");

// 导航到新资源，替换当前历史项
location.replace("/new");
 
// 不加载新 URL，只修改当前历史项
history.replaceState(null, "", "/new");

window.location.reload();

window.location.origin; // https://example.com
window.location.pathname; // /products/123
window.location.search; // ?sort=price
window.location.hash; // #reviews

https://example.com/products/123?sort=price#reviews

origin   = https://example.com
pathname = /products/123
search   = ?sort=price
hash     = #reviews

首页 → 商品列表 → 商品详情

history.pushState(
  { page: 2 },
  "",
  "/products?page=2",
);

/products?page=1
↓ pushState
/products?page=2

history.replaceState(
  { page: 2 },
  "",
  "/products?page=2",
);

const url = new URL(window.location.href);
 
url.searchParams.delete("payment_success");
 
history.replaceState(null, "", url);

/checkout?payment_success=true
↓
/checkout

history.back(); // 后退一条
history.forward(); // 前进一条
history.go(-2); // 后退两条
history.go(1); // 前进一条
history.go(0); // 重新加载当前页面

window.addEventListener("popstate", (event) => {
  console.log("当前地址：", window.location.href);
  console.log("历史状态：", event.state);
});

history.pushState(null, "", "/a");
history.replaceState(null, "", "/b");

const url = new URL(
  "/products?page=2#reviews",
  window.location.origin,
);
 
console.log(url.pathname); // /products
console.log(url.search); // ?page=2
console.log(url.hash); // #reviews
 
url.pathname = "/articles";
url.searchParams.set("page", "3");
url.searchParams.delete("sort");

// 只替换当前地址与历史项
history.replaceState(null, "", url);
 
// 进行浏览器导航
window.location.href = url.toString();

/docs#installation

window.location.hash = "#installation";

<section id="installation">Installation</section>

window.addEventListener("hashchange", () => {
  console.log(window.location.hash);
});

https://example.com/docs#install

GET /docs

/sign-in?next=%2Ftool%23generator

import Link from "next/link";
 
<Link href="/dashboard">Dashboard</Link>

"use client";
 
import { useRouter } from "next/navigation";
 
export function LoginButton() {
  const router = useRouter();
 
  function handleSuccess() {
    router.replace("/dashboard");
  }
 
  return <button onClick={handleSuccess}>登录</button>;
}

router.push()    → 新增历史项，可以后退
router.replace() → 替换当前历史项，不新增后退节点

history.replaceState(null, "", "/dashboard");
// 浏览器不负责加载 /dashboard；Next.js 会同步 URL 读取状态
 
router.replace("/dashboard");
// 执行 Next.js 路由切换，必要时获取路由数据，并更新页面

router.refresh();

window.location.reload();

router.back();
router.forward();
router.prefetch("/dashboard");

const pathname = usePathname();
const searchParams = useSearchParams();
const params = useParams();

app/products/[id]/page.tsx

/products/123?page=2

usePathname()     → /products/123
useSearchParams() → 查询参数，可读取 page=2
useParams()       → 动态路由参数 { id: "123" }

用户点击 <Link> / 调用 router.push()
  ↓
Next.js 客户端 Router 检查预取与 Router Cache
  ↓ 缺少目标路由数据
发出 RSC / 路由请求
  ↓
Next.js 服务端处理请求
  ↓
返回 RSC Payload
  ↓
客户端合并结果并更新页面
  ↓
浏览器历史与地址栏同步

浏览器整页导航 / Next.js RSC 请求 / 其他 HTTP 请求
  ↓
HTTP 请求进入 Next.js
  ↓
next.config.ts 的 headers
  ↓
next.config.ts 的 redirects
  ↓
proxy.ts（原 middleware.ts）
  ↓
next.config.ts 的 rewrites 与文件系统路由匹配
  ↓
Page / Server Component / Route Handler
  ↓
返回 HTML、RSC Payload、JSON 或重定向响应
  ↓
浏览器或 Next.js Router 处理响应

1. next.config.ts headers
2. next.config.ts redirects
3. Proxy
4. beforeFiles rewrites
5. 文件系统路由（public、_next/static、pages、app 等）
6. afterFiles rewrites
7. 动态路由
8. fallback rewrites

// proxy.ts（Next.js 16+）
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function proxy(request: NextRequest) {
  if (!request.cookies.has("token")) {
    return NextResponse.redirect(
      new URL("/sign-in", request.url),
    );
  }
 
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

请求 /dashboard
  ↓
Proxy 检查 Cookie
  ↓ 没有 token
返回重定向响应，Location: /sign-in
  ↓
客户端导航到 /sign-in

<Link> / router.push()
  ↓
需要新的 RSC / 路由数据
  ↓
发出请求
  ↓ 路径命中 matcher
proxy.ts 执行
  ↓
服务端路由与渲染

history.replaceState(null, "", "/dashboard");

import { redirect } from "next/navigation";
 
export default async function Page() {
  const user = await getCurrentUser();
 
  if (!user) {
    redirect("/sign-in");
  }
 
  return <Dashboard />;
}

import { permanentRedirect } from "next/navigation";
 
permanentRedirect("/new-path");

import { notFound } from "next/navigation";
 
if (!product) {
  notFound();
}

export default {
  async redirects() {
    return [
      {
        source: "/download-extension",
        destination: "/download",
        permanent: true,
      },
    ];
  },
};

GET /download-extension
  ↓
308 Location: /download
  ↓
客户端再次请求 /download

history.replaceState(null, "", "/download");

export default {
  async rewrites() {
    return [
      {
        source: "/api/images/:path*",
        destination: "https://image-service.example/:path*",
      },
    ];
  },
};

/api/images/avatar.png

https://image-service.example/avatar.png

/api/images/avatar.png

redirect
  → 返回 3xx 和 Location
  → 客户端知道目标地址
  → 客户端再发起目标请求
  → 地址栏通常变化
 
rewrite
  → Next.js 内部改写请求目标
  → 客户端不知道内部目标
  → 地址栏保持原地址

<Link href="/products">Products</Link>

router.push("/result");

router.replace("/dashboard");

const params = new URLSearchParams(searchParams.toString());
params.set("sort", "price");
window.history.pushState(null, "", `?${params.toString()}`);

history.replaceState(null, "", "/products");

router.refresh();

location.reload();

location.href = "https://example.com";

location
负责浏览器级资源导航和重新加载
 
history
负责会话历史与地址栏，本身不加载目标 URL
 
Next.js Router
负责客户端路由切换、RSC 数据获取和 React 更新
 
Proxy（原 Middleware）
位于 HTTP 请求入口，在服务端路由匹配与渲染之前拦截请求
 
redirect / 307 / 308
告诉客户端目标地址，由客户端继续导航
 
rewrite
Next.js 内部更换请求目标，浏览器地址不变

1. 地址是谁改的：location、history 还是 Next Router？
2. 有没有产生真实请求：document、RSC、fetch 还是没有请求？
3. 请求进入 Next.js 后，是否命中 redirects、Proxy 或 rewrite？
4. 最终返回的是 HTML、RSC Payload、普通响应还是 3xx？
5. 浏览器历史是新增、替换，还是完全不变？