Next.js：真实项目总结

▌ 技术引导 在真实项目中使用Next.js搭建前端应用，最大的收获是它能让你把动态页面和静态生成结合到极致。我见过很多项目直接使用React + Express，结果页面加载慢、SEO差、部署复杂，而Next.js只需要配置几个关键点就能解决这些问题。比如用next export导出静态页面、用getStaticProps预取数据、用next.config.js优化构建性能。你肯定不想让浏览器加载完JavaScript才显示内容，这就需要用SSG或者SSR，但怎么选得看项目需求。如果页面数据变化频繁，SSR更合适，但要处理好服务器负载。我踩过的坑包括：没有正确设置basePath导致部署后路径错乱、没有配置publicRuntimeConfig导致环境变量在客户端暴露、没有合理使用API路由导致请求被错误处理。更重要的是，要理解Next.js的页面生命周期，比如getStaticProps和getServerSideProps的区别，避免在服务端渲染时出现不必要的性能损耗。 在生产环境中，我见过很多团队因为没用好Next.js的优化策略，导致构建速度慢、包体积过大，甚至出现部署失败的情况。要解决这些问题，必须从配置入手，比如使用swc替代Babel、合理设置webpack配置、引入splitChunks优化代码分割。同时，静态导出时如果页面太多，可以考虑用next export的并行构建模式。我还遇到过缓存问题，尤其是在集成第三方服务时，没设置正确的cache-control导致数据不一致。这些都需要在技术参考中详细说明，不能再拖到后面。 Next.js的API路由功能很强，但用法容易出错。比如我在一个项目中直接写了一个getServerSideProps函数，结果因为没处理异步请求，导致页面加载空白。后来才发现，必须用async/await或者Promise处理数据获取，否则中间件不会等待。另外，有的项目在使用API路由时，没有正确设置路由文件路径，导致请求无法命中，结果只能在服务器日志里找半天。配置next.config.js时，必须确保assetPrefix正确，否则静态资源会加载错路径。还有，我在一个项目中尝试用next/image组件优化图片，结果因为没设置width和height，导致布局错乱和性能问题。这些经验都值得写进技术参考，让后来的人少走弯路。 很多团队在使用Next.js时，把所有页面都做成SSG，结果发现有些页面数据是实时的，造成缓存问题。这时候就要用SSR或者ISR，但配置起来并不简单。我之前在部署一个电商项目时，用ISR处理商品详情页，结果发现ISR的缓存策略没写对，导致页面更新后缓存没清空。后来才知道，必须用revalidate参数控制刷新时间，否则缓存机制会失效。另外，当我们需要和后端配合时，API路由可以封装成服务端逻辑，但必须避免暴露敏感数据，比如在next.config.js中配置publicRuntimeConfig来限制客户端访问。还有，我见过一些项目因为过度使用动态导入，导致代码分割混乱，最后不得不手动调整chunks的加载顺序。这些细节都必须在技术参考中体现出来，避免重复踩坑。 如果你在使用Next.js时遇到部署问题，务必要检查构建日志和服务器配置。我之前在一个海外项目中，因为没有配置正确的serverRuntimeConfig，导致某些环境变量在服务器端无法读取，结果页面报错。后来才意识到，需要在next.config.js中显式设置这些变量，否则它们不会被传递到服务器端。另外，在使用next export时，如果页面路径有动态参数，必须确保路径匹配正确，否则会生成错误的静态文件。还有，我在一个项目中因为没配置正确的tsconfig.json，导致TypeScript类型问题在构建时被忽略，最后上线才发现很多错误。这些经验都说明，Next.js虽然是一个强大的框架，但配置和用法上的细节必须明确，否则项目会出大问题。 ▌ 技术参考 一 在真实项目中使用Next.js，你需要明确区分页面类型。静态生成页面（SSG）适合内容相对稳定的页面，而服务器端渲染（SSR）适合数据频繁变化的场景。应用getStaticProps时，必须确保返回的props是静态的，否则会导致页面加载失败。比如在获取产品数据时，如果数据是动态的，应该用getServerSideProps替代，但要注意这会增加服务器负担。 二 配置next.config.js是提升性能的关键。例如，使用swc替代Babel可以大幅减少构建时间，尤其是在大型项目中。配置中可以写：module.exports = { compiler: { jsx: { // enable swc jsx support } } }，但需要确保代码中没有使用不兼容的JSX语法。此外，设置assetPrefix可以避免静态资源路径错误，尤其是在部署到子路径或者CDN时。 三 静态导出时，如果页面数量庞大，可以使用next export的并行构建模式。这需要在package.json中配置parallel: true，这样能加快导出速度。但要注意，导出后的页面必须通过HTTP服务器提供，不能直接使用Node.js运行。另外，如果页面路径中有动态参数，必须确保它们能被正确解析，否则会生成错误的HTML文件。 四 在使用next/image组件时，必须指定width和height，否则会导致布局错乱和性能问题。比如在页面中写，这样浏览器能提前加载图片并计算布局。同时，可以通过loader参数指定图片加载方式，比如loader: 'webp'来优化图片格式。不要盲目使用next/image，它只适用于静态资源，动态图片建议用第三方服务处理。 五 使用getServerSideProps时，必须确保函数是同步的，或者使用正确的异步处理方式。例如，用async/await获取数据，并在返回的props中传递结果。如果数据是通过数据库查询得来的，要确保连接池配置合理，否则会严重影响性能。此外，如果页面需要频繁更新，可以考虑使用ISR（Incremental Static Regeneration）机制，通过revalidate参数控制缓存刷新时间。 六 在分布式部署中，Next.js的API路由需要配置正确的反向代理。比如使用Nginx将请求路由到Next.js应用，需配置location /api/ { proxy_pass http://localhost:3000; }，但要注意路径匹配是否正确。如果API路由没有正确嵌套，可能会导致请求被错误处理。另外，在使用API路由时，要避免泄露敏感信息，可以通过publicRuntimeConfig设置环境变量，这样它们不会出现在客户端代码中。 七 对于SEO优化，Next.js的SSG模式是最理想的。在构建时，所有页面都会生成HTML文件，搜索引擎可以直接抓取。但要注意，如果页面内容依赖动态数据，必须确保这些数据在getStaticProps中能被正确获取。比如在获取用户信息时，可以使用API路由提供静态数据，或者是通过SSR来动态处理。同时，在页面中要正确使用标题、meta标签等SEO元素，否则即使内容生成了，也无法被搜索引擎识别。 八 在使用TypeScript时，必须配置正确的tsconfig.json文件。比如设置target为'esnext'、module为'esnext'，并确保jsx的配置符合Next.js的要求。如果配置错误，可能会导致类型问题无法识别，或者构建失败。此外，要确保TypeScript类型在SSG和SSR中都能正常使用，避免在服务端出现类型错误。 九 部署时，如果遇到静态资源加载失败的问题，要检查assetPrefix配置是否正确。它应该和部署域名或子路径一致，否则资源会加载到错误的位置。比如部署到https://www.example.com/subpath/，那么assetPrefix应该设置为/subpath/，否则图片、CSS、JS等资源会加载到根路径，导致404错误。 十 在使用next export时，如果页面太多，可以考虑使用next build命令生成静态文件，然后通过next export导出到特定目录。但要注意，导出后的页面必须独立运行，不能直接用Node.js启动。此外，如果页面有动态行为，必须确保这些行为能在静态HTML中正常运行，否则可能需要配合客户端脚本处理。 十一 当遇到页面加载缓慢的问题时，建议检查代码分割配置。可以通过next.config.js中的splitChunks设置，确保每个页面只加载必要的代码。如果某个页面引用了大量第三方库，可以考虑将其单独打包，避免影响其他页面的加载速度。另外，使用swc时，可以配置minify: true来减少最终JS文件的体积。 十二 在使用SSR时，如果出现页面渲染不一致的问题，要检查getServerSideProps是否返回了正确的props。比如在获取用户数据时，如果数据获取失败，可能会导致页面显示错误。同时，要确保在服务器端能正常访问数据库或其他后端服务，避免因为网络问题导致渲染失败。 十三 对于大型项目，建议使用Next.js的增量构建功能。这可以通过next.config.js中的experimental配置项开启，比如experimental: { incrementalCache: true }，这样每次构建只会重新生成变化的页面，从而减少构建时间。但要注意，增量构建可能会影响某些依赖关系，需要测试是否所有页面都能正确生成。 十四 在使用SSG时，如果某些页面需要实时数据，可以考虑结合ISR。比如在getStaticProps中返回一个动态的revalidate时间，这样页面会在指定时间后自动重新生成。但要注意，ISR可能会影响首次加载速度，需要在性能和数据实时性之间找到平衡。 十五 使用Next.js的API路由时，如果遇到跨域问题，可以配置next.config.js中的headers选项，比如在pages/api目录下的路由文件中添加headers: () => [{ source: '/api/', headers: [{ key: 'Access-Control-Allow-Origin', value: '' }], }], 这样就能解决大部分跨域请求问题。但要避免滥用CORS配置，否则可能引入安全风险。