---
title: ssr
---

# server.ssr

- **类型：** `boolean` | `Object`
- **默认值：** `false`

SSR 开关以及相关设置。

### Boolean 类型

当值类型为 `boolean` 时，表示是否开启 SSR 部署模式，默认 `false` 不开启。

```ts title="modern.config.ts"
export default defineConfig({
  server: {
    ssr: true,
  },
});
```

### Object 类型

当值类型为 `Object` 时，可以配置如下属性：

| 属性              | 类型                                                               | 默认值                                   | 描述                                                                     |
| ---------------- | ------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
| mode             | `string`                                  | `string`          | 默认为使用 `renderToString` 渲染。配置为 `stream` 开启流式渲染       |
| forceCSR         | `boolean`                                 | `false`           | 默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR |
| disablePrerender | `boolean`                                 | `fasle`           | 为了兼容旧数据请求方式 - `useLoader`, 默认情况下 Modern.js 会对组件进行一次预渲染即有两次渲染 |
| unsafeHeaders    | `string[]`                                | `[]`              | 为了安全考虑，Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置，对需要注入的 headers 进行配置       |
| scriptLoading    | `defer \| blocking \| module \| async`    | `defer`           | 配置同 [html.scriptLoading](/configure/app/html/script-loading)，支持 ssr 注入的 script 设置为 async 加载方式。优先级为 `ssr.scriptLoading` > `html.scriptLoading`  |
| loaderFailureMode| `clientRender \| errorBoundary`           | `errorBoundary` | 当 [data loader](/guides/basic-features/data/data-fetch.html#data-loader推荐) 中出错时，默认会渲染路由 [`Error`](/guides/basic-features/routes.html#错误处理) 组件，配置为 `'clientRender'` 时，有一个 data loader 抛错，就降级到客户端渲染，可以与 [Client Loader](/guides/basic-features/data/data-fetch.html#client-loader) 配合使用 |


```ts title="modern.config.ts"
export default defineConfig({
  server: {
    ssr: {
      forceCSR: true,
      mode: 'stream',
      disablePrerender: true,
      unsafeHeaders: ['User-Agent'],
      scriptLoading: 'async',
    },
  },
});
```

### 主动降级

在生产环境，有时需要将 SSR 项目主动降级到 CSR，例如：

1. SSR 出现故障，需要降级到 CSR，保证产品可用性。

2. SSR 正常数据获取时页面渲染正常，但出错降级后渲染失败，需要进行调试。

3. SSR 服务压力过大，需要部分流量直接降级为 CSR，避免服务宕机。

在项目中配置 `server.ssr.forceCSR` 为 `true` 后，我们可以通过请求的查询字符串，或是请求头来控制这一行为。

例如在自定义 Web Server 的中间件中，检测到流量大于某一阈值时，主动降级：

```ts title="server/index.ts"
export const middleware = (ctx, next) => {
  const { req, res } = ctx;
  if (condition) {
    req.headers['x-modern-ssr-fallback'] = '1';
  }

  next();
};
```
