SSR代码规范：从入门到精通

▌ 技术引导
我见过太多人在配置SSR（服务器端渲染）时，把一大段代码直接复制粘贴，结果项目跑起来满屏报错，甚至直接崩溃。其实SSR不是简单的把前端代码跑在服务端，而是整个架构的重构，涉及到Node.js、Webpack、TypeScript、Babel等一系列工具链的深度配合。别以为装个express和next.js就能搞定，真正的SSR要处理数据预取、路由匹配、页面生命周期、hydration等环节。你甚至得在生产环境中用服务端渲染的代码去生成HTML，然后用静态资源优化工具打包成文件。最近三到四年SSR更讲究的是按需渲染、增量更新、资源加载策略，这些都是踩坑的高频点。如果你想要稳定运行的SSR项目，必须知道如何用Hydrate、SRR、Prerender这些技术点去组合，而不是盲目追求热点技术。

抛开概念，我直接告诉你怎么做：在Next.js中，使用getServerSideProps或者getStaticProps来处理数据，确保每个页面在服务端都能拿到所需数据。如果用Nuxt.js，记得配置universal模式，同时在ssr: true时设置render: { ssr: true }。你可能会遇到页面首次加载慢，这是因为服务端渲染和客户端hydration之间的同步问题，这时候要合理使用vue-server-renderer的渲染器配置，甚至结合SSG（静态生成）来优化。如果你用的是自定义SSR方案，比如基于Express和Vue，一定要用vue-server-renderer配合webpack的热更新模块。

如果你没处理好CSS和JS的加载顺序，用户可能在页面内容渲染前就看到了空白。这时候得用splitChunks和动态导入来拆分代码，同时在服务端渲染时确保需要的CSS资源已经加载。你买不起昂贵的SSR方案，那就用vite + express + ssr中间件，或者用webpack + server-side rendering plugin来构建。记得用env变量控制开发环境和生产环境渲染策略，比如prod环境要用node server.js，而dev环境用nodemon。如果项目架构复杂，建议用master branch和feature branch分离SSR的实现，避免代码污染。

还要注意，SSR不一定非要用Next.js或者Nuxt.js，比如React + Express + renderer + webpack也可以实现。但是配置起来更麻烦，尤其是hydration阶段容易出问题。如果你用的是Vue3 + Node.js，必须理解vue-server-renderer和SSR兼容性问题，比如ssr兼容性、组件生命周期、异步加载组件等。记得在build时用--modern或者--ssr参数，确保生成的代码能被服务端正确解析。如果你还在用传统SSR方式，比如用renderToString + require，那已经是2024年过时的玩法了，得换成更现代的框架和工具。

总之，SSR不只是代码的调整，而是整个应用架构的重新设计。你必须知道如何配置打包工具、如何处理页面数据、如何优化加载性能、如何避免hydration错误。如果你现在在做SSR项目，千万不能跳过这些细节，否则你的项目会被真实用户卡在加载阶段。接下来，我直接给出技术参考，不讲废话。

▌ 技术参考
一 在Next.js中开启SSR需要在pages目录下定义getServerSideProps函数，该函数返回一个包含props的对象，用于填充页面组件。构建时默认启用SSR，但如果你使用next export命令，会强制生成静态页面。在开发环境中，使用next dev时会自动启用SSR，但在生产环境，必须在next.config.js中设置webpack: { configure: { target: 'server' } }。如果项目包含第三方库，如axios，需要在pages目录中使用import as axios from 'axios'，避免客户端与服务端模块冲突。

二 如果你想在Next.js中实现SSG（静态生成），那么应该使用getStaticProps方法，并配合getStaticPaths生成静态页面。在生产构建时，next build命令会自动转换为静态资源。SSR和SSG最大的区别在于，SSR是动态生成内容，而SSG是提前预生成。对于高频访问的页面，建议用SSG；而对于需要动态数据的页面，必须用SSR。如果同时使用两者，可以在pages目录下设置SSG的页面路径，如products/[id].js，然后在getStaticPaths中定义数据源。

三 在Nuxt.js中，SSR由vue-server-renderer模块实现，需要确保nuxt.config.js中开启ssr: true选项。同时，需要在pages目录中使用asyncData或fetch方法来获取数据，否则页面无法正确渲染。如果你在使用Vue3 + Nuxt3，注意兼容性问题，比如在服务端渲染时，某些Vue2特性可能会导致问题。此外，需要在构建时使用--modern参数，否则服务端渲染的代码可能无法兼容现代浏览器。

四 在使用SSR时，经常会出现hydration错误，这通常是因为服务端渲染的HTML结构与客户端渲染的结构不一致。解决方法是确保服务端渲染的HTML结构和客户端一致，包括DOM节点、v-model、v-for等。此外，在页面组件中，要避免使用client-only组件，除非你明确知道它不会影响渲染结构。可以使用vue-server-renderer的hydration模式来检测差异，并在开发环境中输出警告信息。

五 如果你使用自定义SSR方案，比如React + Express，那么必须配置webpack的服务器端渲染插件。在服务端，使用ReactDOMServer.renderToString渲染页面，并将结果返回给客户端。需要注意的是，服务端渲染的页面需要和客户端的页面结构一致，否则hydration会出错。此外，要确保所有组件在服务端可用，比如使用React.lazy时，必须保证在服务端也能正确加载。

六 在SSR项目中，CSS加载策略至关重要。如果直接使用全局CSS，服务端可能无法正确解析，导致样式缺失。解决方案是使用CSS-in-JS库，如emotion或styled-components，或者在webpack中配置splitChunks将CSS抽离为独立文件。另外，使用Vue的CSS modules或者scoped CSS时，必须确保在服务端也能正常加载，避免样式不一致问题。如果使用第三方CSS框架，如Tailwind CSS，建议在服务端使用purgeCSS来减少体积，并确保生成的HTML中包含正确的样式标签。

七 对于性能优化，SSR项目必须合理使用预取、预加载和动态导入。比如，在Next.js中使用next/image组件，自动处理图片的加载策略。如果某些页面数据量大，建议使用getServerSideProps异步加载，而不是直接在组件中请求。同时，可以结合SSG和SSR的优点，在某些页面使用SSG生成静态内容，而在其他页面使用SSR获取实时数据。这样能兼顾加载速度和功能需求。

八 如果你的SSR项目运行在Docker容器中，必须注意Node.js环境的配置。比如，在Dockerfile中使用ARG参数来区分开发和生产环境，然后在构建时动态选择配置。同时，确保在容器内部安装所有依赖项，并配置正确的端口和工作目录。如果遇到构建失败，可能是因为某些模块在服务端不可用，这时候需要在package.json中添加"server"字段，并在构建时指定环境。

九 在SSR项目中，数据预取是一个关键环节。在Next.js中，可以使用getServerSideProps函数进行数据预取，确保服务端在渲染页面时已经获取到所需数据。同时，可以使用next/link组件的href属性进行预加载，提高首屏加载速度。如果使用Nuxt.js，可以通过asyncData函数获取数据，并利用Nuxt的预加载机制优化用户体验。对于复杂的查询，建议使用缓存策略，避免重复请求。

十 构建SSR项目时，要特别注意构建工具的版本兼容性。比如，在使用Webpack 5时，某些依赖可能需要特定的配置，否则可能无法正确打包。常见的问题包括模块解析错误、打包体积过大、构建速度慢。解决方案是使用Webpack的splitChunks配置，将公共代码抽离为独立文件，并使用tree-shaking减少无用代码。同时，可以使用webpack-dev-server进行热更新，提高开发效率。

十一 在SSR项目中，路由匹配是一个不可忽视的问题。在Next.js中，pages目录下的文件自动成为路由，但如果你使用自定义路由，必须确保服务端能正确解析。比如，在Express中使用app.get('/page')来匹配页面，但要注意路径一致性。如果使用动态路由，比如products/[id].js，那么服务端必须通过params获取id，并传入getServerSideProps。对于Vue项目，可以使用vue-router的createRouter函数，并在服务端使用vue-server-renderer的createRenderer进行渲染。

十二 当使用SSR时，可能会遇到某些模块在服务端不可用的问题。例如，某些浏览器API或Node.js模块可能无法在服务端运行。解决方法是使用env变量控制模块的加载，比如在getServerSideProps中使用process.env.NODE_ENV判断是否为服务端。此外，在代码中使用if (typeof window === 'undefined')来避免在服务端执行客户端专属代码。如果使用第三方库，如axios，记得在服务端使用import as axios from 'axios'，避免模块冲突。

十三 在SSR项目中，数据获取方式直接影响性能。在Next.js中，getServerSideProps支持异步操作，可以使用await来处理API请求。为了避免阻塞渲染，建议将数据获取放在异步函数中，并使用Promise.all来并行处理多个请求。对于Vue项目，可以在asyncData中使用async函数获取数据，但要注意不要在服务端执行耗时操作，否则会影响渲染时间。如果数据量过大，可以考虑使用缓存策略或分页技术。

十四 如果你的SSR项目部署在云服务器上，需要注意资源消耗问题。SSR相比SSG需要更高的CPU和内存，尤其是在处理大量请求时。这时候，建议使用负载均衡、CDN加速、缓存策略等手段优化性能。另外，如果使用Node.js，可以考虑使用pm2或cluster模块来管理进程，提高服务器稳定性。对于高并发场景，可以考虑使用Nginx反向代理，将静态资源和SSR请求分开处理。

十五 在SSR项目中，终极大坑是无法正确处理客户端和服务器端的差异。比如，某些组件可能在客户端使用了window对象，但在服务端渲染时会报错。解决方法是显式判断环境，或者使用条件渲染的方式避免这类错误。此外，如果使用React Hooks，要确保在服务端渲染时不会触发无效的副作用。一旦出现hydration错误，用户会看到页面闪烁或内容错位，这时候必须排查组件结构是否一致，并确保在渲染前的所有数据已经加载完毕。