服务端渲染 API

renderToString()

• 导出自 vue/server-renderer

• 类型

  function renderToString(
    input: App | VNode,
    context?: SSRContext
  ): Promise<string>

• 示例

  import { createSSRApp } from 'vue'
  import { renderToString } from 'vue/server-renderer'
  const app = createSSRApp({
    data: () => ({ msg: 'hello' }),
    template: `<div>{{ msg }}</div>`
  })
  ;(async () => {
    const html = await renderToString(app)
    console.log(html)
  })()

  处理 Teleport

  如果渲染的应用包含 Teleport，那么 teleport 的内容将不会作为渲染字符串的一部分。在大多数情况下，最佳方案是在挂载时条件式地渲染 Teleport。

  如果你需要激活 teleport 内容，服务端渲染上下文对象将它们暴露在了 teleports property 下：

  const ctx = {}
  const html = await renderToString(app, ctx)
  console.log(ctx.teleports) // { '#teleported': 'teleported content' }

• 相关内容： 指南 - 服务端渲染 (SSR)

renderToNodeStream()

Node.js Readable stream 形式的渲染输入。

• 导出自 vue/server-renderer

• 类型

  function renderToNodeStream(
    input: App | VNode,
    context?: SSRContext
  ): Readable

• 示例

  // 在一个 Node.js http 处理函数内
  renderToNodeStream(app).pipe(res)

  :::tip 备注 vue/server-renderer 的 ESM 构建不支持此方法，因为它是与 Node.js 环境分离的。请换为使用 pipeToNodeWritable。 :::

pipeToNodeWritable()

渲染和传输到现有的 Node.js Writable stream 实例。

• 导出自 vue/server-renderer

• 类型

  function pipeToNodeWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: Writable
  ): void

• 示例

  // 在一个 Node.js http 处理函数内
  pipeToNodeWritable(app, {}, res)

renderToWebStream()

Web ReadableStream 形式的渲染输入。

• 导出自 vue/server-renderer

• 类型

  function renderToWebStream(
    input: App | VNode,
    context?: SSRContext
  ): ReadableStream

• 示例

  // 在一个支持 ReadableStream 的环境下
  return new Response(renderToWebStream(app))

  :::tip 备注 在不能全局暴露 ReadableStream 构造函数的环境下，请换为使用 pipeToWebWritable()。 :::

pipeToWebWritable()

渲染和传输到现有的 Web WritableStream 实例。

• 导出自 vue/server-renderer

• 类型

  function pipeToWebWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: WritableStream
  ): void

• 示例

  通常与 TransformStream 结合使用：

  // 诸如 CloudFlare worker 这样的环境中，TransformStream 是可用的。
  // 在 Node.js 中，TransformStream 需要从 'stream/web' 显示导入。
  const { readable, writable } = new TransformStream()
  pipeToWebWritable(app, {}, writable)
  return new Response(readable)

renderToSimpleStream()

在流模式中使用一个简单的可读接口进行渲染输入。

• 导出自 vue/server-renderer

• 类型

  function renderToSimpleStream(
    input: App | VNode,
    context: SSRContext,
    options: SimpleReadable
  ): SimpleReadable
  interface SimpleReadable {
    push(content: string | null): void
    destroy(err: any): void
  }

• 示例

  let res = ''
  renderToSimpleStream(
    app,
    {},
    {
      push(chunk) {
        if (chunk === null) {
          // done
          console(`render complete: ${res}`)
        } else {
          res += chunk
        }
      },
      destroy(err) {
        // error encountered
      }
    }
  )

useSSRContext()

一个运行时 API，用于获取已传递给 renderToString() 或其他服务端渲染 API 的上下文对象。

• 类型

  function useSSRContext<T = Record<string, any>>(): T | undefined

• 示例

  得到的上下文能够作为附加信息用于渲染最终的 HTML (例如 head 中的元数据)。

  <script setup>
  import { useSSRContext } from 'vue'
  // 确保只在服务端渲染时调用
  // https://vitejs.dev/guide/ssr.html#conditional-logic
  if (import.meta.env.SSR) {
    const ctx = useSSRContext()
    // ...附加 property 给上下文
  }
  </script>