server.ssr

类型： boolean | Object
默认值： false

SSR 开关以及相关设置。

Boolean 类型

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

modern.config.ts

export default defineConfig({
  server: {
    ssr: true,
  },
});

Object 类型

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

属性	类型	默认值	描述
mode	`string`	`stream`	默认为使用流式渲染。配置为 `string` 使用 `renderToString` 渲染
forceCSR	`boolean`	`false`	默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR
unsafeHeaders	`string[]`	`[]`	为了安全考虑，Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置，对需要注入的 headers 进行配置
loaderFailureMode	`clientRender \| errorBoundary`	`errorBoundary`	当 data loader 中出错时，默认会渲染路由 `Error` 组件，配置为 `'clientRender'` 时，有一个 data loader 抛错，就降级到客户端渲染，可以与 Client Loader 配合使用

modern.config.ts

export default defineConfig({
  server: {
    ssr: {
      forceCSR: true,
      mode: 'stream',
      unsafeHeaders: ['User-Agent'],
      scriptLoading: 'async',
    },
  },
});

主动降级

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

SSR 出现故障，需要降级到 CSR，保证产品可用性。
SSR 正常数据获取时页面渲染正常，但出错降级后渲染失败，需要进行调试。
SSR 服务压力过大，需要部分流量直接降级为 CSR，避免服务宕机。

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

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

server/modern.server.ts

import {
  defineServerConfig,
  type MiddlewareHandler,
} from '@modern-js/server-runtime';

export const handler: MiddlewareHandler = async (c, next) => {
  if (condition) {
    c.set('forceCSR', '1');
  }
  await next();
};

export default defineServerConfig({
  middlewares: [
    {
      name: 'request-middleware',
      handler,
    },
  ],
});

#server.ssr

#Boolean 类型

#Object 类型

#主动降级

server.ssr

Boolean 类型

Object 类型

主动降级