NNext.js 中文网 GitHub

如何优化第三方库

使用 @next/third-parties 包优化应用中第三方库的性能。

@next/third-parties 是一个库,提供了一组组件和实用工具,用于改善在 Next.js 应用中加载流行第三方库的性能和开发者体验。

@next/third-parties 提供的所有第三方集成都针对性能和易用性进行了优化。

开始使用#

要开始使用,请安装 @next/third-parties 库:

bash · pnpm
pnpm add @next/third-parties@latest next@latest
bash · npm
npm install @next/third-parties@latest next@latest
bash · yarn
yarn add @next/third-parties@latest next@latest
bash · bun
bun add @next/third-parties@latest next@latest

@next/third-parties 目前是一个处于积极开发中的实验性库。在我们继续添加更多第三方集成期间,建议使用 latest 或 canary 标签安装它。

Google 第三方库#

所有受支持的 Google 第三方库都可以从 @next/third-parties/google 导入。

Google Tag Manager#

GoogleTagManager 组件可用于在你的页面中实例化一个 Google Tag Manager 容器。默认情况下,它会在页面发生 hydration 后获取原始内联脚本。

要为所有路由加载 Google Tag Manager,请直接在根布局中包含该组件,并传入你的 GTM 容器 ID:

app/layout.tsx
import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

要为所有路由加载 Google Tag Manager,请直接在自定义的 _app 中包含该组件,并传入你的 GTM 容器 ID:

pages/_app.js
import { GoogleTagManager } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleTagManager gtmId="GTM-XYZ" />
    </>
  )
}

要为单个路由加载 Google Tag Manager,请在你页面文件中包含该组件:

app/page.js
import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}
pages/index.js
import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

发送事件#

sendGTMEvent 函数可用于通过使用 dataLayer 对象发送事件来跟踪页面上的用户交互。要使此函数正常工作,<GoogleTagManager /> 组件必须包含在父级布局、页面或组件中,或直接包含在同一个文件中。

app/page.js
'use client'

import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}
pages/index.js
import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

请参阅 Tag Manager 的开发者文档,了解可以传递给该函数的各种变量和事件。

服务端标记#

如果你使用服务端标记管理器并从标记服务器提供 gtm.js 脚本,可以使用 gtmScriptUrl 选项来指定脚本的 URL。

选项#

传递给 Google Tag Manager 的选项。有关选项的完整列表,请阅读 Google Tag Manager 文档。

名称类型描述
gtmId必需\*你的 GTM 容器 ID。通常以 GTM- 开头。
gtmScriptUrl可选\*GTM 脚本 URL。默认为 https://www.googletagmanager.com/gtm.js。
dataLayer可选用于实例化容器的数据层对象。
dataLayerName可选数据层的名称。默认为 dataLayer。
auth可选环境代码段的身份验证参数(gtm_auth)的值。
preview可选环境代码段的预览参数(gtm_preview)的值。

\*当提供 gtmScriptUrl 时可以省略 gtmId,以支持面向广告客户的 Google 代码网关。

Google Analytics#

GoogleAnalytics 组件可用于通过 Google 代码(gtag.js)将 Google Analytics 4 包含到你的页面中。默认情况下,它会在页面发生 hydration 后获取原始脚本。

建议:如果你的应用中已经包含了 Google Tag Manager,你可以直接使用它来配置 Google Analytics,而不必将 Google Analytics 作为单独的组件包含进来。请参阅文档,了解 Tag Manager 与 gtag.js 之间的区别。

要为所有路由加载 Google Analytics,请直接在根布局中包含该组件,并传入你的衡量 ID:

app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}
app/layout.js
import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

要为所有路由加载 Google Analytics,请直接在自定义的 _app 中包含该组件,并传入你的衡量 ID:

pages/_app.js
import { GoogleAnalytics } from '@next/third-parties/google'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleAnalytics gaId="G-XYZ" />
    </>
  )
}

要为单个路由加载 Google Analytics,请在你页面文件中包含该组件:

app/page.js
import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}
pages/index.js
import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

发送事件#

sendGAEvent 函数可用于通过使用 dataLayer 对象发送事件来衡量页面上的用户交互。要使此函数正常工作,<GoogleAnalytics /> 组件必须包含在父级布局、页面或组件中,或直接包含在同一个文件中。

app/page.js
'use client'

import { sendGAEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}
pages/index.js
import { sendGAEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

请参阅 Google Analytics 的开发者文档,了解有关事件参数的更多信息。

跟踪页面浏览量#

当浏览器历史记录状态发生变化时,Google Analytics 会自动跟踪页面浏览量。这意味着 Next.js 路由之间的客户端导航无需任何配置即可发送页面浏览数据。

要确保正确衡量客户端导航,请确认你的管理面板中已启用“增强衡量”属性,并且已选中“基于浏览器历史记录事件的页面更改”复选框。

注意:如果你决定手动发送页面浏览事件,请务必禁用默认的页面浏览量衡量,以避免数据重复。请参阅 Google Analytics 的开发者文档了解更多信息。

选项#

传递给 <GoogleAnalytics> 组件的选项。

名称类型描述
gaId必需你的衡量 ID。通常以 G- 开头。
dataLayerName可选数据层的名称。默认为 dataLayer。
debugMode可选启用 Google Analytics 调试模式。
nonce可选一个 nonce。

Google Maps 嵌入#

GoogleMapsEmbed 组件可用于在你的页面中添加 Google Maps 嵌入。默认情况下,它使用 loading 属性对首屏之外的嵌入内容进行懒加载。

app/page.js
import { GoogleMapsEmbed } from '@next/third-parties/google'

export default function Page() {
  return (
    <GoogleMapsEmbed
      apiKey="XYZ"
      height={200}
      width="100%"
      mode="place"
      q="Brooklyn+Bridge,New+York,NY"
    />
  )
}
pages/index.js
import { GoogleMapsEmbed } from '@next/third-parties/google'

export default function Page() {
  return (
    <GoogleMapsEmbed
      apiKey="XYZ"
      height={200}
      width="100%"
      mode="place"
      q="Brooklyn+Bridge,New+York,NY"
    />
  )
}

选项#

传递给 Google Maps Embed 的选项。有关选项的完整列表,请阅读 Google Map Embed 文档。

名称类型描述
apiKey必需你的 api key。
mode必需地图模式
height可选嵌入内容的高度。默认为 auto。
width可选嵌入内容的宽度。默认为 auto。
style可选向 iframe 传递样式。
allowfullscreen可选允许某些地图部分进入全屏的属性。
loading可选默认为懒加载。如果你知道嵌入内容将在首屏内,请考虑更改此项。
q可选定义地图标记的位置。根据地图模式,此项可能是必需的。
center可选定义地图视图的中心。
zoom可选设置地图的初始缩放级别。
maptype可选定义要加载的地图瓦片类型。
language可选定义用于 UI 元素和地图瓦片上标签显示的语言。
region可选根据地缘政治敏感性,定义要显示的适当边界和标签。

YouTube 嵌入#

YouTubeEmbed 组件可用于加载和显示 YouTube 嵌入内容。该组件在底层使用 lite-youtube-embed,因此加载速度更快。

app/page.js
import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}
pages/index.js
import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

选项#

名称类型描述
videoid必需YouTube 视频 id。
width可选视频容器的宽度。默认为 auto
height可选视频容器的高度。默认为 auto
playlabel可选为无障碍访问提供的播放按钮的视觉隐藏标签。
params可选此处定义的视频播放器参数。
参数以查询参数字符串的形式传递。
例如:params="controls=0&start=10&end=30"
style可选用于向视频容器应用样式。
Next.js 中文网