Script 组件
使用内置的 next/script 组件优化 Next.js 应用程序中的第三方脚本。
本 API 参考将帮助你了解如何使用 Script 组件可用的 props。有关功能和用法,请参阅优化脚本页面。
import Script from 'next/script'
export default function Dashboard() {
return (
<>
<Script src="https://example.com/script.js" />
</>
)
}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 | - |
必需的 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)中,用于加载整个站点都需要的脚本(即当应用中的任何页面在服务器端加载时,该脚本都会加载)。
此策略只应用于需要尽快获取的关键脚本。
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>
)
}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>
)
}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 脚本可以放在任何页面或布局中,并且只会在该页面(或页面组)在浏览器中打开时加载和执行。
import Script from 'next/script'
export default function Page() {
return (
<>
<Script src="https://example.com/script.js" strategy="afterInteractive" />
</>
)
}适合使用 afterInteractive 的一些脚本示例包括:
- 标签管理器
- 分析工具
lazyOnload#
使用 lazyOnload 策略的脚本会在浏览器空闲时于客户端注入到 HTML 中,并在页面上的所有资源获取完成后加载。此策略适用于不需要尽早加载的后台或低优先级脚本。
lazyOnload 脚本可以放在任何页面或布局中,并且只会在该页面(或页面组)在浏览器中打开时加载和执行。
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 标志:
module.exports = {
experimental: {
nextScriptWorkers: true,
},
}worker 脚本目前只能在 pages/ 目录中使用:
import Script from 'next/script'
export default function Home() {
return (
<>
<Script src="https://example.com/script.js" strategy="worker" />
</>
)
}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 方法的做法。
'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]))
}}
/>
</>
)
}'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 嵌入:
'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,
})
}}
/>
</>
)
}'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,
})
}}
/>
</>
)
}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 属性来处理:
'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)
}}
/>
</>
)
}'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)
}}
/>
</>
)
}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。 |