Next.js SSR配置 | 路由配置

▌ 技术引导
在2024-2026年期间，Next.js SSR配置和路由管理成为了构建高性能前端应用的关键技术点。实际开发中，很多团队因为对SSR与静态生成的边界不清，导致页面加载慢、SEO优化差、服务端渲染不稳定等问题。我直接告诉你几个能落地的配置技巧：使用`getServerSideProps`和`getStaticProps`时，必须明确区分页面类型，避免在SSR页面中使用`dynamic`的`import`，否则会触发预加载失败。路由层面，`pages`目录下的文件结构必须严格遵循，否则`next.config.js`会自动忽略，导致404。另外，`next export`这种做法虽然能生成静态页面，但不适合动态内容，容易在上线后出现数据不一致。如果你在使用`app`目录结构，记得用`route`文件而非`page`文件，因为`page`已经过时。这些操作细节直接影响部署效率和用户体验，值得你记住。

▌ 技术参考

一
Next.js的SSR配置和路由结构是构建现代应用的核心，2024年之后，随着框架版本迭代，尤其是`app`目录的引入，很多开发者误以为`pages`目录已被淘汰。实际上，`pages`目录依然存在，但建议优先使用`app`目录。两者的核心区别在于，`app`目录的路由是基于`route`文件，而`pages`是基于文件名。因此，在配置SSR时，务必判断清楚页面是否需要服务端渲染，避免不必要的资源消耗。2025年之后，`getServerSideProps`依然可用，但推荐使用`useServerComponent`和`useServerSideProps`来封装逻辑。例如：在`app/page.tsx`中使用`useServerSideProps`，可以将数据获取逻辑抽离，减少组件复杂度。

二
Next.js的SSR配置主要依赖于`next.config.js`中的`ssr`和`reactStrictMode`等选项，以及`getServerSideProps`函数。2024年10月发布的版本中，`next.config.js`的`ssr`属性已被弃用，取而代之的是通过`next.config.js`中引入`next-sitemap`等插件来控制爬虫行为。配置`getServerSideProps`时，务必使用`export default`而不是`export async function`，否则会报错。此外，在2025年11月之后，若使用`app`目录，`route`文件必须导出一个对象，其中包含`params`和`layout`字段，若未定义，Next.js会自动忽略。例如：`route.ts`中导出`{ params: { id: string }, layout: React.ReactNode }`，这是确保页面正确渲染的必要条件。

三
在实际项目中，SSR配置最容易出问题的场景是动态加载数据。我见过很多开发者在`getServerSideProps`中使用`fetch`获取数据，但未处理`error`或超时异常，导致页面空白或崩溃。正确的做法是使用`try/catch`包裹异步请求，并将错误返回给客户端。例如：
```ts
export default async function getServerSideProps() {
try {
const res = await fetch('http://api.example.com/data');
const data = await res.json();
return { props: { data } };
} catch (err) {
console.error(err);
return { props: { error: 'Failed to fetch data' } };
}
}
```
另外，也不建议在`getServerSideProps`中直接调用外部API，而是应该使用`next.js`的`data fetching`机制，如`useRouter`或`getStaticProps`，这样可以避免服务器压力过大。

四
Next.js的路由配置必须匹配`pages`或`app`目录结构。在`pages`目录下，每个文件对应一个路由，例如`pages/about.tsx`对应`/about`。而在`app`目录下，路由是基于`route`文件，例如`app/about/page.tsx`对应`/about`。2025年6月之后，`app`目录的路由支持嵌套和通配符，例如`app/users/[id]/page.tsx`可以匹配`/users/123`，同时支持`app/users/[...id]/page.tsx`来处理多级动态路由。在配置时，必须使用`next.config.js`中的`experimental`属性来启用`app`目录的SSR模式，否则会默认使用静态生成。配置项为：`experimental: { appDir: true }`，这样可以确保页面在服务器端正确渲染。

五
在使用`getStaticProps`时，若页面需要动态参数，比如`/users/[id]`，必须将参数传递给`getStaticProps`的`params`对象。例如，在`getStaticProps`中，`params`是通过`generateStaticParams`函数获取，而非直接传递。这很容易被误用，尤其在2025年之前版本中，很多开发者直接在`getStaticProps`中传`params`，导致页面无法正确生成。正确的做法是使用`generateStaticParams`来定义所有可能的参数，例如：
```ts
export async function generateStaticParams() {
const res = await fetch('http://api.example.com/users');
const users = await res.json();
return users.map(user => ({ id: user.id }));
}
```
这样不仅确保了静态生成的正确性，还可以在构建时预加载所有数据，减少请求延迟。

六
在Next.js中，`getStaticPaths`和`getStaticProps`是生成静态页面的基础，但2025年之后，`getStaticPaths`已经被`generateStaticParams`取代。因此，如果你还在使用`getStaticPaths`，建议立即更新为`generateStaticParams`。这可以避免在构建时因为参数缺失导致页面跳过。此外，在使用`generateStaticParams`时，若数据来自数据库，必须确保在构建时可用，否则会导致静态生成失败。例如，在Vercel或Netlify上，构建时会运行`generateStaticParams`，若其依赖外部API且未配置代理，就会出现错误。因此，建议在构建时使用本地数据库或缓存数据，避免依赖外部服务。

七
SSR配置对性能影响极大。在2024-2026年期间，很多团队因未正确配置`next.config.js`中`swc`的优化选项，导致服务端渲染速度变慢。例如，`swc`的`minify`和`jsc`配置可以显著提升代码体积和执行效率。你可以通过`next.config.js`中的`swcMinify`和`jsc`字段来配置，例如：
```js
module.exports = {
swcMinify: true,
jsc: {
parser: {
syntax: 'typescript',
tsConfigPath: './tsconfig.json',
},
target: 'es2020',
transform: {
react: {
runtime: 'automatic',
},
},
},
}
```
这些优化可以减少内存占用和渲染时间，尤其是在高并发场景下。

八
在处理SSR页面时，必须确保组件不依赖客户端API。例如，如果你在`getServerSideProps`中获取数据，但在组件中使用`window`对象，会导致错误。2025年之后，Next.js对这类错误的检测更加严格，甚至会直接报错。因此，建议在组件中使用`useRouter`或`useSearchParams`，而不是直接访问`window`。此外，在使用`next/image`时，必须配置`loader`和`unoptimized`参数，否则在SSR时会产生不必要的请求，影响性能。例如：`loader: 'default'`和`unoptimized: true`可以避免图片资源被错误处理。

九
Next.js的路由配置中，动态路由的使用场景非常广泛。但很多开发者在配置`[id].tsx`时忽略了`params`的类型定义，导致类型错误。在2025年之后，TypeScript对这类问题的提示更加明确，建议在`pages`或`app`目录中使用`params`类型注解。例如，在`pages/users/[id].tsx`中，你可以这样定义参数：
```ts
export default function UsersPage({ params }: { params: { id: string } }) {
// 使用params.id获取数据
}
```
这可以避免在构建时因参数类型不匹配导致错误。此外，`app`目录下动态路由必须通过`generateStaticParams`生成所有可能的路径，否则会报错“no paths generated”。

十
在2024年7月之后，Next.js增加了对`app`目录的SSR支持，但很多开发者对`useServerComponent`和`useServerSideProps`的使用方式存在误解。例如，`useServerSideProps`只能在`page`组件中使用，不能在`layout`或`template`中调用。2025年12月之后，若你尝试在`layout`中调用`useServerSideProps`，Next.js会直接报错。因此，在`app`目录中，数据获取应该放在`page`组件中，而不是`layout`。此外，`useServerComponent`用于标记组件是否需要在服务端渲染，但它的使用需要配合`next.config.js`中的`experimental`配置，确保框架正确识别。

十一
Next.js的SSR配置中，缓存策略非常关键。2025年之后，`getServerSideProps`默认不启用缓存，每次请求都会重新获取数据。这在高并发场景下严重影响性能。因此，建议在`getServerSideProps`中使用`cache`机制，例如通过`next/cache`模块，或使用`SWR`、`React Query`等客户端缓存库。例如，使用`SWR`来缓存数据，可以显著减少服务端压力。此外，在`next.config.js`中配置`cache`策略，比如`webpack`的`cache`选项，可以提升构建速度。但要注意，缓存策略必须根据业务场景调整，例如新闻类页面可以设置较短的缓存时间，而用户详情页面则建议禁用缓存。

十二
Next.js的路由配置中，`next.config.js`的`basePath`和`trailingSlash`参数对部署影响很大。例如，若你将`basePath`设置为`/myapp`，那么所有路由都会自动加上`/myapp`，但这也意味着你必须确保所有链接都正确使用`basePath`。此外，`trailingSlash`用于控制URL是否包含斜杠，例如`/about`或`/about/`。2025年之后，若你启用了`trailingSlash: 'always'`，但未在`next.config.js`中配置，会导致页面生成失败。因此，在部署前务必检查`basePath`和`trailingSlash`的配置，确保它们与实际部署环境一致。

十三
使用`next.config.js`时，若想在SSR页面中启用`swc`优化，必须配置`swcMinify`和`swcReactRemoveProperties`选项。例如，在`swcReactRemoveProperties`中，你可以选择是否移除`React`的props，从而减少最终代码体积。2024年12月之后，`swc`的性能优化成为重点，尤其是在服务端渲染时，`swc`的`minify`和`transform`配置可以显著减少内存占用和渲染时间。例如：
```js
module.exports = {
swcMinify: true,
swcReactRemoveProperties: true,
}
```
这些配置可以提升整体应用的运行效率，尤其是在高并发或长页面场景下。

十四
在`app`目录结构下，`route`文件的配置必须与`page`文件一一对应，否则Next.js会自动忽略路由。例如，在`app/users/[id]/page.tsx`中，必须有一个对应的`route.ts`文件，否则页面无法正确加载。此外，`route.ts`中定义的`params`必须与`page.tsx`中使用的参数一致，否则会导致404错误。例如：
```ts
export async function generateStaticParams() {
return [{ id: '1' }, { id: '2' }];
}
```
这是确保页面路径生成正确的重要步骤，尤其在2025年之后，Next.js对这类错误的检测更为严格。

十五
Next.js的SSR配置和路由管理在多环境部署时容易出问题。例如，在使用`next export`生成静态页面时，若页面依赖`getServerSideProps`，会导致生成失败。因此，建议在生产环境使用`next build`和`next export`时，确保页面不包含动态数据获取逻辑。此外，在使用`app`目录时，若未正确配置`next.config.js`中的`appDir`，会导致服务器无法识别路由文件，从而引发404错误。因此，部署前必须仔细检查配置项，例如：
```js
module.exports = {
experimental: {
appDir: true,
},
}
```
这个配置确保`app`目录的SSR功能被正确启用，否则页面无法正确加载。