Next.js getServerSideProps 源码实现深度解析

作者：北岛时间：2026-10-25 21:24:08浏览：202

本文深入解析 Next.js 中 getServerSideProps 的源码实现。从 SSR 渲染入口 doRender 开始，追踪 renderToHTML 如何标记并执行 getServerSideProps。详细剖析 context 参数构建、notFound/redirect 校验、Promise 异步处理及 props 合并逻辑。同时探讨动态加载场景下，客户端通过 fetchNextData 请求 JSON 数据，服务端识别路径后复用 SSR 逻辑并抽离返回 props 的完整闭环。

SSR 处理

按照惯例，前文已介绍过 getServerSideProps 的基本用法，本文将趁热打铁，深入剖析 getServerSideProps 对应的底层源码，重点探究 next.js getServerSideProps 的具体实现机制，并挖掘官方文档未明确提及的内部细节。

分析首先从 SSR 场景下涉及的 getServerSideProps 处理逻辑入手。源码排查的步骤在前文已有概述，此处不再赘述。当进入 SSR 阶段时，next.js 框架会调用 doRender 方法执行渲染流程。该过程会递归调用 renderHTML，经过一系列条件判断与方法调用后，最终进入 packages/next/server/render.tsx 文件中的 renderToHTML 函数进行核心处理。

// const SERVER_PROPS_ID = "__N_SSP";
if (getServerSideProps) {
    props[SERVER_PROPS_ID] = true;
}

在 next.js 框架内部，props 对象中的 SERVER_PROPS_ID 属性会被显式设置为 true，以此作为后续流程的标识标记。

try {
    data = await getServerSideProps({
        req: req as IncomingMessage & {
            cookies: NextApiRequestCookies;
        },
        res: resOrProxy,
        query,
        resolvedUrl: renderOpts.resolvedUrl as string,
        ...(pageIsDynamic ? { params: params as ParsedUrlQuery } : undefined),
        ...(previewData !== false ? { preview: true, previewData: previewData } : undefined),
        locales: renderOpts.locales,
        locale: renderOpts.locale,
        defaultLocale: renderOpts.defaultLocale
    });
    canAccessRes = false;
} catch (serverSidePropsError: any) {
    if (isError(serverSidePropsError) && serverSidePropsError.code === 'ENOENT') {
        delete serverSidePropsError.code;
    }
    throw serverSidePropsError;
}
if (data == null) {
    throw new Error(GSSP_NO_RETURNED_VALUE);
}
if ((data as any).props instanceof Promise) {
    deferredContent = true;
}
const invalidKeys = Object.keys(data).filter(key => key !== 'props' && key !== 'redirect' && key !== 'notFound');
if (invalidKeys.length) {
    throw new Error(invalidKeysMsg('getServerSideProps', invalidKeys));
}

需要注意的是，这里的 getServerSideProps 函数是从外层上下文传入的。由于相关代码篇幅较长，此处省略展示，其核心逻辑是通过 packages/next/server/load-components 模块中的 loadComponents 方法，从 getServerSideProps 中获取路由文件定义的函数，并在 require 模块加载完成后从页面模块中提取。不过，这里存在一个值得探讨的问题：在 node 环境中，框架是如何安全地 require 页面代码而避免报错的？毕竟页面组件中常包含依赖浏览器环境的代码。推测框架可能实施了类似 runtime shim 的隔离或模拟操作。此处暂留疑问，待后续深入研究。联想到所有页面均已启用 SSR，初始化阶段的代码处理必然已涵盖此类兼容性问题。

从上述代码逻辑可以看出，在 SSR 阶段，系统会直接调用 getServerSideProps 函数，并传入 context 作为参数。此时 context 的具体内容结构也清晰可见。随后，next.js 框架会对返回值进行严格校验，检查其是否为空，或是否包含非法参数等异常情况。

接着，系统会回查 notFound 和 redirect 这两个特定参数，并根据其存在与否进行相应的特殊业务处理。

if ('notFound' in data && data.notFound) {
    if (pathname === '/404') {
        throw new Error(`The /404 page can not return notFound in "getStaticProps", please remove it to continue!`);
    }
    (renderOpts as any).isNotFound = true;
    return null;
}
if ('redirect' in data && typeof data.redirect === 'object') {
    checkRedirectValues(data.redirect as Redirect, req, 'getServerSideProps');
    (data as any).props = {
        __N_REDIRECT: data.redirect.destination,
        __N_REDIRECT_STATUS: getRedirectStatus(data.redirect)
    };
    if (typeof data.redirect.basePath !== 'undefined') {
        (data as any).props.__N_REDIRECT_BASE_PATH = data.redirect.basePath;
    }
    (renderOpts as any).isRedirect = true;
}

此外，从上述代码片段中还可以发现一个有趣的特性：props 的值类型允许为 Promise，即支持异步返回：

if ((data as any).props instanceof Promise) {
    deferredContent = true;
}

当 Promise 被返回时，next.js 框架会在异常处理逻辑执行完毕后，获取该 Promise 的值：

if (deferredContent) {
    (data as any).props = await(data as any).props;
}

最后，next.js 框架会将获取到的 props 数据合并放入顶层的 props 对象中：

props.pageProps = Object.assign({}, props.pageProps, (data as any).props);
(renderOpts as any).pageData = props;

在 SSR 渲染阶段，我们在页面源码中看到的、用于 hydrate 初始化的 __NEXT_DATA__ 脚本里的 props 数据，正是上述处理后的 props。我们可以再次查看其中的具体数据结构：

<script id="__NEXT_DATA__" type="application/json">
    {
        "props": {
            "pageProps": {
                "feature": {
                    "name": "xxxx",
                    "desc": "xxxx",
                    "tags": ["xxx"],
                    "id": "account-manage"
                }
            },
            "__N_SSP": true
        },
        "page": "/feature/[fid]",
        "query": { "fid": "account-manage" },
        "buildId": "development",
        "isFallback": false,
        "gssp": true,
        "scriptLoader": []
    }
</script>

从输出结果可见，pageProps 和 __N_SSP 标识均成功注入到了页面数据中。

动态加载处理

在解析完 SSR 场景下，next.js 如何处理 getServerSideProps 的逻辑后，我们进一步考察当页面采用动态加载策略时的处理机制。

通过分析跳转时发起的网络请求调用栈，我们可以轻松定位到：当页面处于动态加载状态时，next.js 框架会通过 packages/next/shared/lib/router.ts 模块中的 getRouteInfo 方法获取目标页面信息，随后利用 routeInfo 返回的 __N_SSP 属性来判断是否需要发起数据获取请求：

const shouldFetchData = routeInfo.__N_SSG || routeInfo.__N_SSP;
if (shouldFetchData) {
    const { json, cacheKey: _cacheKey } = data?.json
        ? data
        : await fetchNextData({
              dataHref: this.pageLoader.getDataHref({
                  href: formatWithValidation({ pathname, query }),
                  asPath: resolvedAs,
                  locale
              }),
              isServerRender: this.isSsr,
              parseJSON: true,
              inflightCache: this.sdc,
              persistCache: !isPreview,
              isPrefetch: false,
              unstable_skipClientCache
          });
    return {
        cacheKey: _cacheKey,
        props: json || {}
    };
}

确认需要获取数据后，系统会通过 fetchNextData 方法执行请求。而我们在前文提到的 _next/data/development/{url}.json?{query} 这段 URL 格式，正是由 formatWithValidation 方法格式化生成的。

请求发送至服务端后的处理逻辑较为复杂，涉及多层嵌套，此处不再逐一列举代码。简要概括如下：next.js 框架会通过 /_next/data/ 路径前缀匹配请求，判断其是否为数据请求。如果是，则同样执行 SSR 相关的处理代码。这可以理解为复用了上述 SSR 初始化时的核心逻辑，区别在于最后框架会根据数据请求的标识，将 props 数据单独抽离，并封装在响应中返回给客户端。