企业官网建设流程全解析

Next.js源码如何处理一次页面请求：从构建到渲染的完整指南

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js

当你运行next dev，页面在浏览器加载完成时，Next.js源码在背后已经完成了一整套工作：确定 URL 对应哪个文件、判断是服务端渲染还是直接返回缓存结果、把 React 组件的数据流式输出成 HTML。Next.js 是 React 官方框架，提供服务端渲染、静态生成与文件式路由，本文按一次页面请求的生命周期讲清它的运转方式。

运行 next build 时发生了什么

构建阶段要解决的问题是：Next.js 的路由由文件结构隐式决定，框架必须先知道"项目里有哪些路由"才能编译它们。

承担这件事的是packages/next/src/build/index.ts中的build函数。它先调用 packages/next/src/build/route-discovery.ts 里的collectPagesFiles遍历pages和app目录，把目录结构收集成路由条目；再根据每个页面的导出（比如revalidate、dynamic）判定渲染模式，写入.next目录下的 routes manifest；最后用 webpack 或 Turbopack 把每条路由编译成独立 bundle。

对你的可感知结果：构建产物.next/routes-manifest.json记录了每条路由是静态还是动态；页面文件放错位置（比如文件名不符合约定）时构建会直接报错。

请求进来时到底落在哪个文件上

服务启动后由 packages/next/src/server/next-server.ts 承接流量：

// 简化：核心继承关系 class NextNodeServer extends BaseServer { // 继承 BaseServer 的请求管道 // 覆写 findPageComponents 等具体实现 }

真正的管道在 packages/next/src/server/base-server.ts 的handleRequest方法里：解析 URL、读取 Accept 请求头（浏览器要的是 HTML 还是 RSC 数据流），然后匹配路由模块。路由匹配是"一条路由一个匹配器"：route-matches/目录下有app-page-route-match.ts、pages-route-match.ts等，精确路由优先于动态路由；匹配成功后交给route-modules/中对应的模块执行渲染。

服务端如何决定渲染方式

路由匹配到页面文件后，管道调用findPageComponents（实现在 next-server.ts）拿到组件，随后查增量缓存：如果构建时已静态渲染过这条路由，直接取缓存输出，不再执行组件代码。未命中则进入实际渲染，App Router 的入口是 packages/next/src/server/app-render/app-render.tsx，它分别产出服务端组件的 RSC 数据流和客户端组件的 HTML，最后合并成响应流写回。

你可以直接控制这一节的行为：在页面里导出revalidate会改变该路由是静态还是按需渲染；使用cookies()、headers()这类动态 API 会强制该路由走服务端渲染，构建时的告警就是在提示这件事。

缓存：一个贯穿构建与请求阶段的机制

增量缓存是 Next.js 里最典型的横切能力，代码在 packages/next/src/server/lib/incremental-cache/。它在两个阶段各出现一次：构建时，静态页面的渲染结果被写进.next/cache（file-system-cache.ts负责落盘）；请求时，服务端优先从这里取数据，命中就跳过整个渲染管道。

ISR 是在此之上的策略而非另一套系统：缓存条目带过期时间，过期后进入"先返回旧内容、后台重新渲染并回写"的状态。revalidate导出和next.config.js里的配置都只是给这套机制设参数。理解这一点后，你会明白为什么生产环境加revalidate后，首次构建慢的页面在请求期几乎零成本。

开发模式下，为什么只有改动页面被刷新

next start和next dev启动的是同一个NextNodeServer，区别在 dev 模式套了一层 packages/next/src/server/dev/next-dev-server.ts，并在同一管道里插入热更新逻辑。

两个关键机制：一是按需编译，on-demand-entry-handler.ts保证只编译浏览器实际请求过的路由，而不是启动时编译全部；二是热更新，bundler 的 watcher 监听文件变化后重新产出对应模块，通过 WebSocket 通知浏览器局部替换 HTML 和 JS。hot-reloader-turbopack.ts、hot-reloader-webpack.ts是两条打包器各自的实现。可感知的结果就是：改一个页面文件，只有那个页面重载，构建时间不会随项目规模增长。

继续深入的话，先看这三个文件

如果你想跟着本文继续读源码，建议的顺序是：先读packages/next/src/server/base-server.ts的handleRequest与run方法，把请求管道走一遍；再读packages/next/src/build/index.ts，看构建如何把目录变成路由产物；最后看packages/next/src/server/app-render/app-render.tsx，理解 App Router 里 RSC 数据流和 HTML 是如何拼成最终响应的。这三处看完，本文提到的缓存、路由匹配、渲染模式都能在源码里对上号。

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js