NNext.js 中文网 GitHub

connection

connection 函数的 API 参考。

connection() 函数让你可以表明渲染应等待传入的用户请求后再继续。

当一个组件不使用诸如 cookies 或 headers 之类的请求时 API,但仍需要为每个请求生成不同的输出(例如 Math.random() 或 new Date())时,该函数非常有用。

app/page.tsx
import { connection } from 'next/server'

export default async function Page() {
  await connection() // 预渲染在此停止
  // 以下代码仅在请求时运行
  const rand = Math.random()
  return <span>{rand}</span>
}
app/page.js
import { connection } from 'next/server'

export default async function Page() {
  await connection() // 预渲染在此停止
  // 以下代码仅在请求时运行
  const rand = Math.random()
  return <span>{rand}</span>
}

示例#

同步数据库驱动#

来自 better-sqlite3 等同步数据库驱动的查询会在预渲染期间完成。如果你尚未使用请求时 API,请在查询之前调用 connection(),以将其排除在预渲染之外:

app/lib/data.ts
import { connection } from 'next/server'
import Database from 'better-sqlite3'

const db = new Database('app.db')

export async function getVisitorCount() {
  await connection()
  return db.prepare('SELECT value FROM counters WHERE name = ?').get('visitors')
}
app/lib/data.js
import { connection } from 'next/server'
import Database from 'better-sqlite3'

const db = new Database('app.db')

export async function getVisitorCount() {
  await connection()
  return db.prepare('SELECT value FROM counters WHERE name = ?').get('visitors')
}

现在,任何调用 getVisitorCount() 的组件都会连同其输出的其余部分一起被排除在预渲染之外。

参考#

类型#

jsx
function connection(): Promise<void>

参数#

  • 该函数不接受任何参数。

返回值#

  • 该函数返回一个 void Promise。它不供消费使用。

小知识#

  • connection 取代了 unstable_noStore,以更好地契合 Next.js 的未来方向。
  • 仅当需要动态渲染且未使用常见的请求时 API 时,才需要该函数。
  • 使用 Cache Components 时,请将调用 connection() 的组件放在 <Suspense> 边界内,可以直接放置,也可以通过诸如 loading.js 文件之类的祖先放置。最近边界的 fallback 会被预渲染到静态 shell 中,而 connection() 之后的代码会在请求时运行。如果没有边界,到该路由的导航会被阻塞而非即时。
  • 使用 Cache Components 时,更推荐用 io() 将内容排除在静态 shell 之外。它的工作方式相同,而且也可以在 "use cache" 作用域内调用,此时它会立即解析。仅在渲染应等待真实用户请求时才使用 connection()。

版本历史#

版本变更
v15.0.0connection 稳定版发布。
v15.0.0-RC引入 connection。
Next.js 中文网