NNext.js 中文网 GitHub

Script 组件

使用内置的 next/script 组件优化 Next.js 应用程序中的第三方脚本。

本 API 参考将帮助你了解如何使用 Script 组件可用的 props。有关功能和用法,请参阅优化脚本页面。

app/dashboard/page.tsx
import Script from 'next/script'

export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}
app/dashboard/page.js
import Script from 'next/script'

export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

Props#

以下是 Script 组件可用 props 的摘要:

Prop示例类型是否必需
srcsrc="http://example.com/script"String除非使用内联脚本,否则为必需
strategystrategy="lazyOnload"String-
onLoadonLoad={onLoadFunc}Function-
onReadyonReady={onReadyFunc}Function-
onErroronError={onErrorFunc}Function-

必需的 Props#

<Script /> 组件需要以下属性。

src#

一个路径字符串,用于指定外部脚本的 URL。它可以是绝对外部 URL,也可以是内部路径。除非使用内联脚本,否则 src 属性是必需的。

可选的 Props#

<Script /> 组件除了必需的属性外,还接受许多其他属性。

strategy#

脚本的加载策略。可以使用四种不同的策略:

  • beforeInteractive:在任何 Next.js 代码之前以及任何页面 hydration 发生之前加载。
  • afterInteractive:(默认)尽早加载,但在页面上发生部分 hydration 之后。
  • lazyOnload:在浏览器空闲时加载。
  • worker:(实验性)在 Web Worker 中加载。

beforeInteractive#

使用 beforeInteractive 策略加载的脚本会由服务器注入到初始 HTML 中,在任何 Next.js 模块之前下载,并按照它们放置的顺序执行。

使用此策略标记的脚本会在任何第一方代码之前预加载和获取,但它们的执行不会阻止页面 hydration 的发生。

使用 beforeInteractive 策略的脚本必须放在根布局中,例如 app/layout.tsx 或 app/[locale]/layout.tsx,它们用于加载整个站点都需要的脚本(即当应用中的任何页面在服务器端加载时,该脚本都会加载)。

beforeInteractive 脚本必须放在 Document 组件(pages/_document.js)中,用于加载整个站点都需要的脚本(即当应用中的任何页面在服务器端加载时,该脚本都会加载)。

此策略只应用于需要尽快获取的关键脚本。

app/layout.tsx
import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}
app/layout.js
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}
pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document'
import Script from 'next/script'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </Html>
  )
}

小知识:使用 beforeInteractive 的脚本始终会被注入到 HTML 文档的 head 中,无论它在组件中放置在何处。

小知识:这些脚本在每次文档加载时运行一次。客户端导航不会再次运行它们,包括仅更改根参数的导航(例如从 /en 到 /fi),因为根布局保持不变。

应使用 beforeInteractive 尽快获取的一些脚本示例包括:

  • 机器人检测器
  • Cookie 同意管理器

afterInteractive#

使用 afterInteractive 策略的脚本会在客户端注入到 HTML 中,并在页面上发生部分(或全部)hydration 后加载。这是 Script 组件的默认策略,适用于任何需要尽快加载、但不必先于任何第一方 Next.js 代码加载的脚本。

afterInteractive 脚本可以放在任何页面或布局中,并且只会在该页面(或页面组)在浏览器中打开时加载和执行。

app/page.js
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}

适合使用 afterInteractive 的一些脚本示例包括:

  • 标签管理器
  • 分析工具

lazyOnload#

使用 lazyOnload 策略的脚本会在浏览器空闲时于客户端注入到 HTML 中,并在页面上的所有资源获取完成后加载。此策略适用于不需要尽早加载的后台或低优先级脚本。

lazyOnload 脚本可以放在任何页面或布局中,并且只会在该页面(或页面组)在浏览器中打开时加载和执行。

app/page.js
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}

不需要立即加载、可以使用 lazyOnload 获取的脚本示例包括:

  • 聊天客服插件
  • 社交媒体小组件

worker#

警告: worker 策略尚未稳定,并且目前不适用于 App Router。请谨慎使用。

使用 worker 策略的脚本会被转移到 Web Worker 中,以释放主线程并确保主线程只处理关键的第一方资源。虽然此策略可用于任何脚本,但它属于高级用例,并不保证支持所有第三方脚本。

要将 worker 用作策略,必须在 next.config.js 中启用 nextScriptWorkers 标志:

next.config.js
module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

worker 脚本目前只能在 pages/ 目录中使用:

pages/home.tsx
import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}
pages/home.js
import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

onLoad#

警告: onLoad 目前不适用于 Server Components,只能在 Client Components 中使用。此外,onLoad 不能与 beforeInteractive 一起使用——请考虑改用 onReady。

某些第三方脚本要求用户在脚本加载完成后运行一次 JavaScript 代码,以实例化内容或调用函数。如果你使用 afterInteractive 或 lazyOnload 作为加载策略来加载脚本,可以使用 onLoad 属性在脚本加载后执行代码。

以下示例展示了仅在库加载完成后才执行 lodash 方法的做法。

app/page.tsx
'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}
app/page.js
'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}

onReady#

警告: onReady 目前不适用于 Server Components,只能在 Client Components 中使用。

某些第三方脚本要求用户在脚本加载完成后以及每次组件挂载时(例如在路由导航之后)运行 JavaScript 代码。你可以使用 onReady 属性在脚本首次加载的 load 事件之后,以及之后每次组件重新挂载时执行代码。

以下示例展示了如何在每次组件挂载时重新实例化 Google Maps JS 嵌入:

app/page.tsx
'use client'

import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}
app/page.js
'use client'

import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}
jsx
import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}

onError#

警告: onError 目前不适用于 Server Components,只能在 Client Components 中使用。onError 不能与 beforeInteractive 加载策略一起使用。

有时,捕获脚本加载失败的情况很有帮助。这些错误可以通过 onError 属性来处理:

app/page.tsx
'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}
app/page.js
'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}
jsx
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Script failed to load', e)
        }}
      />
    </>
  )
}

版本历史#

版本变更
v13.0.0beforeInteractive 和 afterInteractive 经过修改以支持 app。
v12.2.4新增 onReady prop。
v12.2.2允许将带有 beforeInteractive 的 next/script 放在 _document 中。
v11.0.0引入 next/script。
Next.js 中文网