Next.js 中文网

主题

脚本 ​

¥Scripts

应用脚本 ​

¥Application Scripts

要为所有路由加载第三方脚本，请导入 next/script 并将该脚本直接添加到你的自定义 _app 中：

¥To load a third-party script for all routes, import next/script and include the script directly in your custom _app:

当访问应用中的任何路由时，该脚本将加载并执行。Next.js 将确保脚本仅加载一次，即使用户在多个页面之间导航也是如此。

¥This script will load and execute when any route in your application is accessed. Next.js will ensure the script will only load once, even if a user navigates between multiple pages.

建议：我们建议仅在特定页面或布局中包含第三方脚本，以尽量减少对性能的不必要影响。

¥Recommendation: We recommend only including third-party scripts in specific pages or layouts in order to minimize any unnecessary impact to performance.

战略 ​

¥Strategy

尽管 next/script 的默认行为允许你在任何页面或布局中加载第三方脚本，但你可以使用 strategy 属性微调其加载行为：

¥Although the default behavior of next/script allows you to load third-party scripts in any page or layout, you can fine-tune its loading behavior by using the strategy property:

  • beforeInteractive：在任何 Next.js 代码之前以及任何页面水合发生之前加载脚本。

    ¥beforeInteractive: Load the script before any Next.js code and before any page hydration occurs.

  • afterInteractive：（默认）尽早加载脚本，但要在页面发生一些水合作用之后。

    ¥afterInteractive: (default) Load the script early but after some hydration on the page occurs.

  • lazyOnload：稍后在浏览器空闲时加载脚本。

    ¥lazyOnload: Load the script later during browser idle time.

  • worker：（实验性）将脚本加载到 Web Worker 中。

    ¥worker: (experimental) Load the script in a web worker.

请参阅 next/script API 参考文档，了解有关每种策略及其用例的更多信息。

¥Refer to the next/script API reference documentation to learn more about each strategy and their use cases.

将脚本卸载到 Web Worker（实验性） ​

¥Offloading Scripts To A Web Worker (experimental)

警告：worker 策略尚不稳定，尚不适用于 App Router。谨慎使用。

¥Warning: The worker strategy is not yet stable and does not yet work with the App Router. Use with caution.

使用 worker 策略的脚本将在具有 Partytown 的 Web Worker 中卸载并执行。这可以通过将主线程专用于应用代码的其余部分来提高站点的性能。

¥Scripts that use the worker strategy are offloaded and executed in a web worker with Partytown. This can improve the performance of your site by dedicating the main thread to the rest of your application code.

该策略仍处于实验阶段，只有在 next.config.js 中启用 nextScriptWorkers 标志时才能使用：

¥This strategy is still experimental and can only be used if the nextScriptWorkers flag is enabled in next.config.js:

然后，运行 next（通常是 npm run dev 或 yarn dev），Next.js 将引导你安装所需的软件包以完成设置：

¥Then, run next (normally npm run dev or yarn dev) and Next.js will guide you through the installation of the required packages to finish the setup:

bash
npm run dev

你会看到类似这样的说明：请运行 npm install @builder.io/partytown 安装 Partytown

¥You'll see instructions like these: Please install Partytown by running npm install @builder.io/partytown

设置完成后，定义 strategy="worker" 将自动在你的应用中实例化 Partytown 并将脚本卸载给 Web Worker。

¥Once setup is complete, defining strategy="worker" will automatically instantiate Partytown in your application and offload the script to a web worker.

tsx
import Script from 'next/script'

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

在 Web Worker 中加载第三方脚本时需要考虑许多权衡。请参阅 Partytown 的 tradeoffs 文档以获取更多信息。

¥There are a number of trade-offs that need to be considered when loading a third-party script in a web worker. Please see Partytown's tradeoffs documentation for more information.

使用自定义 Partytown 配置 ​

¥Using custom Partytown configuration

虽然 worker 策略不需要任何额外配置即可运行，但 Partytown 支持使用配置对象来修改其部分设置，包括启用 debug 模式以及转发事件和触发器。

¥Although the worker strategy does not require any additional configuration to work, Partytown supports the use of a config object to modify some of its settings, including enabling debug mode and forwarding events and triggers.

如果你想添加其他配置选项，可以将其包含在 定制 _document.js 中使用的 <Head /> 组件中：

¥If you would like to add additional configuration options, you can include it within the <Head /> component used in a custom _document.js:

要修改 Partytown 的配置，必须满足以下条件：

¥In order to modify Partytown's configuration, the following conditions must be met:

  1. 必须使用 data-partytown-config 属性才能覆盖 Next.js 使用的默认配置。

    ¥The data-partytown-config attribute must be used in order to overwrite the default configuration used by Next.js

  2. 除非你决定将 Partytown 的库文件保存在单独的目录中，否则必须将 lib: "/_next/static/~partytown/" 属性和值包含在配置对象中，以便 Partytown 知道 Next.js 存储必要静态文件的位置。

    ¥Unless you decide to save Partytown's library files in a separate directory, the lib: "/_next/static/~partytown/" property and value must be included in the configuration object in order to let Partytown know where Next.js stores the necessary static files.

注意：如果你正在使用 资源前缀 并希望修改 Partytown 的默认配置，则必须将其作为 lib 路径的一部分。

¥Note: If you are using an asset prefix and would like to modify Partytown's default configuration, you must include it as part of the lib path.

查看 Partytown 的 配置选项 以了解可添加的其他属性的完整列表。

¥Take a look at Partytown's configuration options to see the full list of other properties that can be added.

内联脚本 ​

¥Inline Scripts

脚本组件还支持内联脚本或不从外部文件加载的脚本。它们可以通过将 JavaScript 放在大括号内来编写：

¥Inline scripts, or scripts not loaded from an external file, are also supported by the Script component. They can be written by placing the JavaScript within curly braces:

或者使用 dangerouslySetInnerHTML 属性：

¥Or by using the dangerouslySetInnerHTML property:

警告：必须为内联脚本分配 id 属性，以便 Next.js 跟踪和优化脚本。

¥Warning: An id property must be assigned for inline scripts in order for Next.js to track and optimize the script.

执行附加代码 ​

¥Executing Additional Code

事件处理程序可以与脚本组件一起使用，以便在某个事件发生后执行附加代码：

¥Event handlers can be used with the Script component to execute additional code after a certain event occurs:

  • onLoad：脚本加载完成后执行代码。

    ¥onLoad: Execute code after the script has finished loading.

  • onReady：在脚本完成加载后以及每次安装组件时执行代码。

    ¥onReady: Execute code after the script has finished loading and every time the component is mounted.

  • onError：如果脚本加载失败则执行代码。

    ¥onError: Execute code if the script fails to load.

这些处理程序仅在 next/script 被导入并在 客户端组件 内部使用时才起作用，其中 "use client" 被定义为第一行代码：

¥These handlers will only work when next/script is imported and used inside of a Client Component where "use client" is defined as the first line of code:

tsx
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onLoad={() => {
          console.log('Script has loaded')
        }}
      />
    </>
  )
}

请参阅 next/script API 参考以了解有关每个事件处理程序的更多信息并查看示例。

¥Refer to the next/script API reference to learn more about each event handler and view examples.

附加属性 ​

¥Additional Attributes

有许多 DOM 属性可以分配给脚本组件未使用的 <script> 元素，例如 nonce 或 自定义数据属性。包含任何其他属性都会自动将其转发到 HTML 中包含的最终优化的 <script> 元素。

¥There are many DOM attributes that can be assigned to a <script> element that are not used by the Script component, like nonce or custom data attributes. Including any additional attributes will automatically forward it to the final, optimized <script> element that is included in the HTML.

tsx
import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        id="example-script"
        nonce="XUENAJFW"
        data-test="script"
      />
    </>
  )
}