Next.js SSR配置 | 全网最全 部署方案

▌ 技术引导
Next.js SSR配置的核心在于平衡性能与开发效率。我见过太多项目因为SSR配置不当，导致页面加载慢得像蜗牛，甚至出现SEO优化失败。关键点在于数据预取、服务器端渲染策略、中间件逻辑和环境变量管理。实际部署时，千万别把SSR和SSG混在一起，服务器端渲染需要额外的配置项、缓存机制和错误处理，否则你可能在生产环境遇到大量404和错误日志。我配置过多个SSR项目，发现动态路由、静态导出、API路由这三个模块最容易出事。一个常见的误区是直接使用`getServerSideProps`，但这样会牺牲性能，尤其在高频访问场景下。轻量级部署建议用Node.js + Vercel，而中大型项目需要考虑自建服务器和负载均衡。实践经验告诉我，SSR的正确配置要结合项目规模、数据类型和用户行为来动态调整，不能一概而论。

▌ 技术参考

一
Next.js SSR配置落地的第一步是明确数据来源。我见过很多项目在前端直接请求后端API，结果因为没有代理导致跨域问题。正确做法是使用`next.config.js`配置`headers`，添加`Content-Security-Policy`和`X-Content-Type-Options`，确保安全和跨域兼容。在服务器端，`getServerSideProps`函数需要返回一个`props`对象，你必须在`next.config.js`中开启`serverSideRendering: true`，否则会提示找不到SSR入口。另外，记得在`pages/_app.js`中用`useRouter`做路由埋点，这样能精确控制哪些页面需要SSR，哪些可以SSG。如果你用的是`next export`，那SSR配置基本无效，必须用`next build`和`next start`生成生产环境服务。

二
部署SSR时，环境变量管理是关键。我之前用的是`.env`文件，但发现有些变量在构建时无法被正确读取，后来改用`next.config.js`中`env`对象注入，这样就能确保服务端和客户端都能访问。例如，在`next.config.js`中写`env: { API_URL: 'https://api.example.com' }`，在`getServerSideProps`函数中用`process.env.API_URL`调用。另一个常见问题是在`next.config.js`里开启`distDir`，否则静态资源会错乱。我配置过几个项目，发现`distDir`设置成`out`后，预编译和热更新都会变得稳定。此外，如果你用的是自建服务器，记得在`server.js`中用`next`实例监听`distDir`目录，否则会报错找不到入口文件。

三
SSR和SSG混用容易出坑。我之前在动态页面里用了`getStaticProps`，结果用户刷新时页面数据消失，因为SSG只在构建时预取数据。正确做法是区分页面类型，静态页面用`getStaticProps`，动态页面用`getServerSideProps`。如果必须同时使用，可以结合`getStaticPaths`和`getServerSideProps`，用`fallback: true`的方式动态加载数据。但是要小心性能，如果页面数据是实时的，`fallback: true`会导致额外请求，增加延迟。我见过一个电商项目因为这样配置，首屏加载时间从1秒飙到3秒，用户体验一落千丈。更深的坑在于SSR逻辑不能和客户端逻辑冲突，比如`useEffect`和`getServerSideProps`同时处理数据，容易出现状态不一致。

四
Next.js SSR的性能优化要从缓存和路由预加载入手。我尝试过用`next/headers`做请求头缓存，但发现对动态数据无效，后来改用`cache-control: public, max-age=3600`，让浏览器端缓存静态数据。在服务器端，使用`express`缓存中间件，比如`express-cache`，能明显提升重复请求的响应速度。我还配置过`next.config.js`中的`webpack`规则，把`node_modules`排除在SSR之外，减少打包时间。但需要注意，某些第三方库可能会触发不必要的重新渲染，比如`moment`或`lodash`。我用`next.config.js`里的`externals`排除这些库，结果打包时间缩短了40%。

五
在部署时，如果你用的是Vercel，那`next.config.js`中的`output: 'standalone'`是个好东西。它能将SSR服务打包成独立的静态文件，减少服务器配置复杂度。但不是所有项目都适合，比如需要动态数据库查询的项目，必须用`next export`以外的方式部署。我之前部署过一个需要实时连接MQTT服务的SSR项目，用的是`next start`命令，但发现Vercel不支持自定义Node.js环境，只能用`next export`加`serverless`配置，结果因为MQTT连接问题频繁出错。后来换成自建服务器，用`pm2`做进程管理，搭配`nginx`反向代理，稳定性好了很多。另外，别忘了在`next.config.js`中设置`reactStrictMode: true`，这样能避免一些未定义行为，比如多次渲染。

六
SSR配置的另一个关键是中间件逻辑。我之前在`pages/api`目录下写了多个中间件，结果因为中间件顺序错误，导致数据加载失败。正确顺序应该是先处理认证，再处理路由，最后才调用业务逻辑。中间件必须用`next-connect`或`express`封装，否则会触发异常。另外，中间件文件名不能是`index.js`，否则会被当作API路由优先处理。我在开发过程中，遇到过中间件无法正确读取`req.cookies`的问题，后来发现是`next.config.js`里没有配置`trailingSlash: false`，导致请求路径携带斜杠。解决方法是直接在中间件里用`req.originalUrl`获取原始路径，绕过这个限制。

七
部署SSR时，我见过太多项目因为没有正确配置`serverComponents`导致页面崩溃。`serverComponents`是Next.js 13.4新增的特性，但它需要`next.config.js`中开启`experimental: { serverComponents: true }`，否则会提示找不到文件。同时，`serverComponents`不能和`getServerSideProps`同时使用，否则会出现数据冲突。我在一个金融项目中，因为错误地混合使用这两个特性，导致页面数据错误，用户看到的是旧数据。后来改用纯`serverSideProps`，并用`data: props`传递数据，问题才解决。同时，`serverComponents`的生命周期和客户端组件不同，必须用`use`和`onLoad`来处理数据加载，避免空值错误。

八
SSR的数据预取策略需要结合`swr`或`react-query`来优化。我用过`swr`在服务端预取数据，发现它能自动处理缓存和数据刷新，尤其适合实时数据场景。配置方式是在`pages/_app.js`里用`useSWR`，然后在`getServerSideProps`中用`SWRConfig`设置`fetcher`函数，这样就能统一管理数据请求。但要注意，`swr`在SSR下会触发额外请求，可能导致性能问题。我曾在一个用户量大的项目中，因为`swr`的预取机制导致服务器负载暴涨，后来改用`axios`手动处理，反而更可控。同时，`react-query`在服务端也有类似问题，必须用`queryClient`在服务端初始化，否则会报错。

九
SSR的错误处理不能忽视。我之前在一个SSR项目里，因为数据库连接失败，导致整个页面崩溃，用户看到的是白屏。后来在`getServerSideProps`函数里加了`try...catch`，并在`next.config.js`中配置`dangerousAutoplay: 'off'`，避免浏览器自动播放视频造成资源占用。还发现`nextjs`在SSR下对JS错误的处理不如客户端，必须用`window.onerror`手动捕获。另外，`next.config.js`中开启`reactStrictMode: true`后，一些未定义行为会被提前暴露，比如无效的`useEffect`。我见过一个项目因为忘记关闭严格模式，导致组件多次渲染，性能下降严重。

十
部署SSR时，静态资源的路径配置是容易出错的地方。我之前在`next.config.js`里用了`basePath: '/app'`，结果静态文件会拼接出`/app/static/`路径，导致404。正确的做法是用`next.config.js`里的`assetPrefix`来设置静态资源的公共路径，这样浏览器就能正确加载CSS和JS文件。还发现，如果用`next export`生成静态文件，`assetPrefix`会失效，必须用`next build`和`next start`。另外，`next.config.js`里的`images`配置必须和CDN服务对齐，否则图片加载会很慢。我曾用过阿里云OSS和腾讯云COS，发现`next.config.js`中的`domains`和`path`必须写全，否则图片无法加载。

十一
SSR的路由配置要避免“动态+静态”混用。我用过`getStaticProps`和`getServerSideProps`同时处理页面，结果用户刷新时出现不一致数据。正确做法是用`getStaticPaths`处理动态路由，并在`getStaticProps`中预取数据，这样就能保证静态生成和SSR的平衡。如果数据需要实时更新，可以考虑用`fallback: true`，但要小心`fallback: true`会触发额外请求。我之前在部署一个论坛项目时，因为`fallback: true`导致用户频繁刷新时请求量暴涨，后来改用`revalidate`机制，设置`revalidate: 60`，让服务端每60秒刷新一次，减少请求压力。同时，`getStaticProps`的`revalidate`参数必须和`next.config.js`里的`reactStrictMode: false`配合使用，否则会触发不必要的重新渲染。

十二
SSR和SSG混用时，`next.config.js`里的`generateStaticParams`是关键。我之前在一个电商项目里，错误地用了`getStaticProps`生成商品页面，结果用户搜索时会触发重复生成，浪费资源。后来改用`generateStaticParams`预生成所有可能的路由，用`next export`导出静态文件，这样既能保证SEO，又能减少SSR的负载。但要注意，`generateStaticParams`只能用于`getStaticPaths`支持的页面，不能和`getServerSideProps`混用。我在部署过程中，发现`next.config.js`里的`routes`配置必须和`generateStaticParams`的输出路径一致，否则会报错找不到文件。

十三
部署SSR时，缓存策略是性能优化的核心。我尝试过用`Redis`做缓存，发现服务端渲染的页面数据可以缓存30天，但必须用`next.config.js`里的`cache`配置项设置缓存时间。另外，`next.config.js`里的`webpack`规则必须排除第三方库的代码，比如`axios`或`graphql`，这样能减少打包体积。我在一个高频访问的项目中，因为`webpack`打包了所有依赖，导致每次部署都慢到离谱。后来用`externals`排除这些库，结果打包速度提升了50%。但要注意，`externals`的使用需要额外配置`package.json`里的`browser`字段，避免某些依赖在客户端运行时出错。

十四
SSR的路由预加载策略要结合`next/router`来处理。我之前在`pages/_app.js`里用`useRouter`监听路由变化，结果发现部分页面在加载时会卡顿。后来改用`next/router`的`prefetch`函数，预加载用户可能访问的页面，比如`/products`和`/categories`。但要小心，`prefetch`在SSR下不会触发服务端渲染，除非用户主动点击链接。我在一个社交平台项目中，因为误用了`prefetch`导致部分页面数据丢失，后来改用`next.config.js`里的`router`配置，强制某些页面在进入时触发SSR。另外，`next.config.js`里的`unstable_noStore: true`能禁用不必要的缓存，避免数据延迟。

十五
SSR的服务器配置要根据项目规模调整。我见过很多小项目直接用`next export`生成静态文件，结果忽略了动态内容的处理。正确的做法是用`next build`和`next start`生成SSR服务，并在`next.config.js`里配置`serverRuntimeConfig`，这样能在服务端访问私有配置。同时，`next.config.js`里的`output: 'standalone'`能简化部署，避免`distDir`路径问题。但不是所有项目都适合，比如需要实时数据库连接的项目必须用`next start`，否则无法处理动态内容。我在部署过程中，发现`next export`生成的静态文件如果包含SSR逻辑，会因为缺少服务端依赖导致404。必须确保`next export`只用于静态页面，SSR页面需要单独部署。

十六
SSR的部署流程必须明确区分开发环境和生产环境。我之前在开发时用`next dev`，生产环境用`next build`和`next start`，结果发现`next dev`不会生成`distDir`目录，导致生产部署时找不到入口文件。正确的做法是在`next.config.js`里配置`distDir: 'out'`，并在`package.json`中设置`start`脚本为`next start -p 3000`。同时，`next.config.js`里的`compiler: { react: { refresh: true } }`能提高热更新速度，但会占用更多内存。我在一个团队项目中，因为没有正确配置`next.config.js`里的`distDir`，导致部署失败，花了好几个小时调试。后来发现是`next build`没生成到`out`目录，手动调整后才解决。

十七
SSR和SSG的混合部署需要谨慎处理缓存策略。我之前在`next.config.js`里开启动态页面的`revalidate`，结果发现静态页面会频繁触发SSR，降低性能。后来改用`next.config.js`里的`generateStaticParams`预生成所有可能的页面路径，并在`pages/_app.js`里用`useRouter`监听路由变化，动态加载数据。但要小心，`next.config.js`里的`generateStaticParams`只适用于`getStaticPaths`支持的页面，不能和`getServerSideProps`混用。我在一个内容平台项目中，因为错误地使用了`getServerSideProps`生成静态页面，导致数据不一致，用户看到的内容和数据库不一致，后来改用`getStaticProps`配合`revalidate`，问题才解决。

十八
SSR的数据加载要结合`next/headers`和`next/config`来优化。我之前在`getServerSideProps`中用`req.headers`获取用户信息，结果发现某些请求头会被代理服务器过滤，导致数据丢失。后来改用`next.config.js`里的`headers`配置，增加`X-User-ID`和`X-Auth-Token`，确保服务端能正确获取用户身份。另外，`next.config.js`里的`webpack`规则需要排除`node_modules`，这样能减少服务端打包时间。我在部署过程中，发现`webpack`如果打包了`node_modules`，会导致内存占用过高，严重时会触发OOM。后来用`externals`排除这些依赖，性能提升明显。

十九
SSR的部署方案要结合中间件和服务器配置。我之前在`next.config.js`里写了一个中间件，用来处理JWT认证，结果发现它在SSR下无法正确读取`req.cookies`，后来改用`next-connect`做中间件，确保数据正确传递。同时，`next.config.js`里的`serverRuntimeConfig`能存储私有配置，比如数据库URL和API密钥，避免暴露在客户端。我还用过`pm2`做进程管理，确保服务端能稳定运行，特别是涉及到高频请求的场景。`pm2`的`--no-daemon`参数能避免进程被系统自动重启，适合生产环境。但要注意，`pm2`不支持`next export`，只能用于SSR部署。

二十
SSR的配置需要结合`next.config.js`和`server.js`来做到灵活可控。我之前在`server.js`中用`express`监听请求，并通过`next`实例处理路由，结果发现某些静态资源无法加载，后来在`next.config.js`里配置`assetPrefix`，确保静态资源路径正确。同时，`next.config.js`里的`experimental: { serverComponents: true }`能启用服务器组件，但必须和`getServerSideProps`配合使用，否则会报错找不到文件。我在部署过程中，发现`serverComponents`的生命周期和客户端不同，必须用`use`和`onLoad`来处理数据加载，避免空值错误。此外，`next.config.js`里的`distDir`设置必须和`server.js`中`next`实例的`distDir`一致，否则会触发路径错误。