跳到内容
API 参考组件Script

Script

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

app/dashboard/page.tsx
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"字符串除非使用内联脚本，否则为必需
strategystrategy="lazyOnload"字符串-
onLoadonLoad={onLoadFunc}函数-
onReadyonReady={onReadyFunc}函数-
onErroronError={onErrorFunc}函数-

必需的 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 之前执行。

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

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

此策略应仅用于需要在页面任何部分变为交互式之前获取的关键脚本。

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

须知：带有 beforeInteractive 的脚本将始终注入到 HTML 文档的 head 中，无论它放置在组件中的哪个位置。

以下是一些应尽快使用 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" />
    </>
  )
}

onLoad

警告： onLoad 尚不适用于服务器组件，并且只能在客户端组件中使用。此外，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]))
        }}
      />
    </>
  )
}

onReady

警告： onReady 尚不适用于服务器组件，并且只能在客户端组件中使用。

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

这是一个关于如何在每次组件挂载时重新实例化 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,
          })
        }}
      />
    </>
  )
}

onError

警告： onError 尚不适用于服务器组件，并且只能在客户端组件中使用。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)
        }}
      />
    </>
  )
}

Version History

版本变更
v13.0.0beforeInteractive 和 afterInteractive 已修改为支持 app。
v12.2.4添加了 onReady 属性。
v12.2.2允许将带有 beforeInteractive 的 next/script 放置在 _document 中。
v11.0.0引入了 next/script。