server.ssr

  • 类型: boolean | Object
  • 默认值: false

SSR 开关以及相关设置。

Boolean 类型

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

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

Object 类型

当值类型为 Object 时,可以配置如下属性:

  • modestring = 'string',默认为使用 renderToString 渲染。配置为 stream 开启流式渲染。
  • forceCSRboolean = false,默认关闭强制 CSR 渲染。配置为 true 后,在页面访问时添加 ?csr=true 或添加请求头 x-modern-ssr-fallback 即可强制 CSR。
  • inlineScriptboolean = true,默认情况下,SSR 的数据会以内联脚本的方式注入到 HTML 中,并且直接赋值给全局变量。配置为 false 后,会下发 JSON,而不是赋值给全局变量。
  • disablePrerender: boolean = fasle, 为了兼容旧数据请求方式 - useLoader, 默认情况下 Modern.js 会对组件进行一次预渲染即有两次渲染。 开发者在保证项目中没有使用 useLoader Api 情况下, 可通过配置 disablePrerender=true来减少一次渲染。
  • unsafeHeaders: string[] = [], 为了安全考虑,Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置,对需要注入的 headers 进行配置。
  • scriptLoading: 'defer' | 'blocking' | 'module' | 'async', 配置同 html.scriptLoading,支持 ssr 注入的 script 设置为 async 加载方式。优先级为 ssr.scriptLoading > html.scriptLoading
modern.config.ts
export default defineConfig({
  server: {
    ssr: {
      forceCSR: true,
      mode: 'stream',
      inlineScript: false,
      disablePrerender: true,
      unsafeHeaders: ['User-Agent'],
      scriptLoading: 'async',
    },
  },
});

主动降级

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

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

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

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

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

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

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

  next();
};