脚本组件 | DevRefinery

本 API 参考将帮助你了解 Script 组件可用的 props 的使用方式。有关特性和用法，请参阅优化脚本页面。

tsx

import Script from 'next/script'

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

jsx

import Script from 'next/script'

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

Props

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

Prop	示例	类型	必需
`src`	`src="http://example.com/script"`	String	除非使用内联脚本，否则为必需
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

必需的 Prop

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

`src`

指定外部脚本 URL 的路径字符串。这可以是绝对外部 URL 或内部路径。除非使用内联脚本，否则 src 属性是必需的。

可选的 Prop

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

`strategy`

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

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

`beforeInteractive`

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

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

App Router Only

beforeInteractive 脚本必须放在根布局 (app/layout.tsx) 中，旨在加载整个站点所需的脚本（即当应用程序中的任何页面在服务器端加载时，脚本就会加载）。

Pages Router Only

beforeInteractive 脚本必须放在 Document 组件 (pages/_document.js) 中，旨在加载整个站点所需的脚本（即当应用程序中的任何页面在服务器端加载时，脚本就会加载）。

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

App Router Only

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>
  )
}

jsx

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 Router Only

jsx

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 中。

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

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

`afterInteractive`

使用 afterInteractive 策略的脚本会在客户端注入到 HTML 中，并在页面上发生部分（或全部）水合后加载。这是 Script 组件的默认策略，应在需要尽快加载但不必在任何第一方 Next.js 代码之前加载的脚本中使用。

afterInteractive 脚本可以放置在任何页面或布局中，并且仅当该页面（或一组页面）在浏览器中打开时才会加载和执行。

jsx

import Script from 'next/script'

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

某些适合 afterInteractive 的脚本示例包括：

标签管理器
分析工具

`lazyOnload`

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

lazyOnload 脚本可以放置在任何页面或布局中，并且仅当该页面（或一组页面）在浏览器中打开时才会加载和执行。

jsx

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 标志：

javascript

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

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

tsx

import Script from 'next/script'

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

jsx

import Script from 'next/script'

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

`onLoad`

警告：onLoad 尚不支持服务器组件，并且只能在客户端组件中使用。此外，onLoad 不能与 beforeInteractive 一起使用 – 请考虑改用 onReady。

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

这是一个仅在 Lodash 库加载后才执行其方法的示例。

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]))
        }}
      />
    </>
  )
}

jsx

'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 尚不支持服务器组件，并且只能在客户端组件中使用。

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

这是一个如何在组件每次挂载时重新实例化 Google Maps JS 嵌入的示例：

App Router Only

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,
          })
        }}
      />
    </>
  )
}

jsx

'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,
          })
        }}
      />
    </>
  )
}

Pages Router Only

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 尚不支持服务器组件，并且只能在客户端组件中使用。onError 不能与 beforeInteractive 加载策略一起使用。

有时，捕获脚本加载失败的情况会很有帮助。可以使用 onError 属性处理这些错误：

App Router Only

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)
        }}
      />
    </>
  )
}

jsx

'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)
        }}
      />
    </>
  )
}

Pages Router Only

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.0`	`beforeInteractive` 和 `afterInteractive` 已修改以支持 `app`。
`v12.2.4`	添加了 `onReady` prop。
`v12.2.2`	允许带有 `beforeInteractive` 的 `next/script` 放置在 `_document` 中。
`v11.0.0`	引入了 `next/script`。

本 API 参考将帮助你了解 Script 组件可用的 props 的使用方式。有关特性和用法，请参阅优化脚本页面。

tsx

import Script from 'next/script'

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

jsx

import Script from 'next/script'

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

Props

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

Prop	示例	类型	必需
`src`	`src="http://example.com/script"`	String	除非使用内联脚本，否则为必需
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

必需的 Prop

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

`src`

指定外部脚本 URL 的路径字符串。这可以是绝对外部 URL 或内部路径。除非使用内联脚本，否则 src 属性是必需的。

可选的 Prop

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

`strategy`

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

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

`beforeInteractive`

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

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

App Router Only

Pages Router Only

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

App Router Only

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>
  )
}

jsx

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 Router Only

jsx

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 中。

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

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

`afterInteractive`

afterInteractive 脚本可以放置在任何页面或布局中，并且仅当该页面（或一组页面）在浏览器中打开时才会加载和执行。

jsx

import Script from 'next/script'

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

某些适合 afterInteractive 的脚本示例包括：

标签管理器
分析工具

`lazyOnload`

lazyOnload 脚本可以放置在任何页面或布局中，并且仅当该页面（或一组页面）在浏览器中打开时才会加载和执行。

jsx

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 用作策略，必须在 next.config.js 中启用 nextScriptWorkers 标志：

javascript

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

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

tsx

import Script from 'next/script'

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

jsx

import Script from 'next/script'

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

`onLoad`

警告：onLoad 尚不支持服务器组件，并且只能在客户端组件中使用。此外，onLoad 不能与 beforeInteractive 一起使用 – 请考虑改用 onReady。

这是一个仅在 Lodash 库加载后才执行其方法的示例。

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]))
        }}
      />
    </>
  )
}

jsx

'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 尚不支持服务器组件，并且只能在客户端组件中使用。

这是一个如何在组件每次挂载时重新实例化 Google Maps JS 嵌入的示例：

App Router Only

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,
          })
        }}
      />
    </>
  )
}

jsx

'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,
          })
        }}
      />
    </>
  )
}

Pages Router Only

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 尚不支持服务器组件，并且只能在客户端组件中使用。onError 不能与 beforeInteractive 加载策略一起使用。

有时，捕获脚本加载失败的情况会很有帮助。可以使用 onError 属性处理这些错误：

App Router Only

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)
        }}
      />
    </>
  )
}

jsx

'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)
        }}
      />
    </>
  )
}

Pages Router Only

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.0`	`beforeInteractive` 和 `afterInteractive` 已修改以支持 `app`。
`v12.2.4`	添加了 `onReady` prop。
`v12.2.2`	允许带有 `beforeInteractive` 的 `next/script` 放置在 `_document` 中。
`v11.0.0`	引入了 `next/script`。

文档导航

Props

必需的 Prop

src

可选的 Prop

strategy

beforeInteractive

afterInteractive

lazyOnload

worker

onLoad

onReady

onError

版本历史

Props

必需的 Prop

src

可选的 Prop

strategy

beforeInteractive

afterInteractive

lazyOnload

worker

onLoad

onReady

onError

版本历史

`src`

`strategy`

`beforeInteractive`

`afterInteractive`

`lazyOnload`

`worker`

`onLoad`

`onReady`

`onError`

`src`

`strategy`

`beforeInteractive`

`afterInteractive`

`lazyOnload`

`worker`

`onLoad`

`onReady`

`onError`