企业官网建设流程全解析

• 前端
• UI组件

导读：本指南以仓库内置技能文档 .agents/skills/next-best-practices/scripts.md 为骨架，系统讲解在 Next.js 16（本项目锁定版本16.2.12，见 package.json）中如何正确加载第三方脚本：为什么必须用next/script替代原生<script>、内联脚本为何必须带id、四种加载策略的取舍，以及如何用@next/third-parties一键接入 Google Analytics、Google Tag Manager、YouTube 与 Google Maps 组件。读完你可以直接把这些模式复制到自己的 SaaS、内部工具或管理后台项目中，同时理解本仓库根布局 src/app/layout.tsx 中"反闪烁"内联脚本的真实落地方案。

为什么第三方脚本加载需要专门规范

第三方脚本（分析、埋点、聊天组件、广告 SDK、地图、视频嵌入等）是页面性能的主要杀手之一：默认的同步<script>标签会阻塞 HTML 解析，直接拖慢 LCP 与 TTI；而异步加载如果策略不当，又会抢占带宽、延迟首屏或造成水合期不一致。Next.js 为此提供了两层官方方案：

1. next/script（Script 组件）：把脚本交给框架调度，支持按策略注入、去重、以及onLoad/onReady/onError回调，且会自动处理其 DOM 位置。
2. @next/third-parties（第三方组件包）：把 Google Analytics、Google Tag Manager、YouTube、Google Maps 等高频嵌入封装成零配置组件，避免手写样板代码。

这两层方案正是该技能文档（被 .agents/skills/next-best-practices/SKILL.md 的 "Scripts" 一节索引）的核心内容。下面逐条展开。

一律使用 next/script，不要用原生 script 标签

原生<script>标签不会被 Next.js 优化：它无法参与策略调度、无法被框架追踪与去重，也无法利用beforeInteractive等服务端注入能力。

// Bad: Native script tag —— 无任何优化，阻塞解析 <script src='https://example.com/script.js'></script> // Good: Next.js Script 组件 —— 交给框架调度与优化 import Script from 'next/script'; <Script src='https://example.com/script.js' />

next/script在客户端渲染时会把脚本注入到正确的文档位置，在服务端渲染时则按策略输出。特别地，它还会自动处理"同一脚本在多个页面重复引用"的去重问题，这是原生标签做不到的。

仓库内的对照实验：本仓库是纯 Dashboard 模板，自身没有引入分析脚本，但它给出了判断脚本位置对错的真实参照物 —— 根布局 src/app/layout.tsx 中有一个必须在水合前执行的"主题色"脚本（见下节），这正是"什么时候该用、什么时候不该用next/script"的边界案例。

内联脚本必须携带 id

用dangerouslySetInnerHTML或子节点方式书写内联脚本时，Next.js 需要id属性来追踪、去重这些脚本，否则同一个内联脚本可能在多次渲染/导航中被重复注入。

// Bad: 缺少 id，Next.js 无法追踪 <Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} /> // Good: 带有 id <Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} /> // Good: 内联脚本的另一种写法 —— 以子节点传入，同样需要 id <Script id="show-banner"> {`document.getElementById('banner').classList.remove('hidden')`} </Script>

两种写法等效：dangerouslySetInnerHTML适合需要精确控制字符串的场景（如拼接 JSON 配置）；子节点写法更接近普通 JSX 直觉。两者都必须带id。

仓库中的真实案例（例外情形）：根布局 src/app/layout.tsx 使用了原生<script dangerouslySetInnerHTML>且没有id，位于<head>中：

<head> <script dangerouslySetInnerHTML={{ __html: ` try { // Set meta theme color if (localStorage.theme === 'dark' || ((!('theme' in localStorage) || localStorage.theme === 'system') && window.matchMedia('(prefers-color-scheme: dark)').matches)) { document.querySelector('meta[name="theme-color"]')?.setAttribute('content', '#09090b') } } catch (_) {} ` }} /> </head>

这属于有意的例外，原因有二：其一，它是原生标签而非next/script，id追踪规则不适用于它；其二，它必须在首帧之前读取localStorage以设置深色主题的meta theme-color，任何异步策略都会导致主题闪烁（FOUC）。注意它用try/catch包裹、整体幂等、无副作用 —— 这正是"内联脚本放在 head 且同步执行"场景下的安全写法。若你改用next/script承载这类预水合逻辑，则必须补上id。

不要把 Script 放进 Head

next/script会自行管理脚本的注入位置，放在next/head里反而会与框架的放置逻辑冲突，导致策略失效或重复注入。

// Bad: Script 塞进 Head import Head from 'next/head' import Script from 'next/script' <Head> <Script src="/analytics.js" /> </Head> // Good: Script 放在 Head 之外 <Head> <title>Page</title> </Head> <Script src="/analytics.js" />

正确姿势：next/head只放文档元信息（title、meta、link等），所有next/script一律放在Head组件之外，作为兄弟节点。

四种加载策略（Loading Strategies）

next/script通过strategy属性控制脚本的注入时机：

// afterInteractive（默认值）—— 页面可交互之后加载 // 适合：分析、埋点、评论等不阻塞首屏的脚本 <Script src="/analytics.js" strategy="afterInteractive" /> // lazyOnload —— 浏览器空闲时加载 // 适合：小部件、聊天浮窗等低优先级脚本 <Script src="/widget.js" strategy="lazyOnload" /> // beforeInteractive —— 页面可交互之前加载（务必克制使用） // 注意：只允许出现在根 layout.tsx 或 pages/_document.js 中 <Script src="/critical.js" strategy="beforeInteractive" /> // worker —— 在 Web Worker 中加载（实验特性） // 适合：重型数据处理脚本 <Script src="/heavy.js" strategy="worker" />

各策略的定位与使用场景：

仓库中的位置证据：本仓库只有一个根布局 src/app/layout.tsx，beforeInteractive的合法使用位置就是这里（App Router 下的根layout.tsx或 Pages Router 的pages/_document.js）。也就是说，任何"必须在首屏前执行"的脚本，在本项目中的归宿都是src/app/layout.tsx，而不是任何页面级文件。

用 @next/third-parties 接入 Google Analytics

手写 Google Analytics 内联脚本非常容易出错且无法被优化：不仅要拼gtag样板，还会把脚本留在页面上占用资源。

// Bad: 手写内联 GA 脚本 <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" /> <Script id="ga-init"> {`window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-XXXXX');`} </Script> // Good: 使用 @next/third-parties 的 GoogleAnalytics 组件 import { GoogleAnalytics } from '@next/third-parties/google' export default function Layout({ children }) { return ( <html> <body>{children}</body> <GoogleAnalytics gaId="G-XXXXX" /> </html> ) }

GoogleAnalytics组件由官方维护，内部已按最佳实践处理脚本注入与加载时机，你只需传入gaId（形如G-XXXXX）。它通常放在根布局</body>之后，等价于afterInteractive语义。

接入 Google Tag Manager

Google Tag Manager（GTM）同样建议用官方组件而非手写<noscript>加内联脚本：

import { GoogleTagManager } from '@next/third-parties/google'; export default function Layout({ children }) { return ( <html> <GoogleTagManager gtmId='GTM-XXXXX' /> <body>{children}</body> </html> ); }

与GoogleAnalytics组件不同的细节在于：GoogleTagManager官方推荐放在<html>标签内部、<body>之外，以配合 GTM 官方要求的容器放置位置（注意对照上一节"Script 不进 Head"的规则——这里是第三方组件包内部处理的位置逻辑，与手写<Head>不同）。gtmId形如GTM-XXXXX。

其他第三方嵌入：YouTube 与 Google Maps

@next/third-parties还封装了高频的媒体与地图嵌入，无需手写iframe模板：

// YouTube 视频嵌入 import { YouTubeEmbed } from '@next/third-parties/google'; <YouTubeEmbed videoid='dQw4w9WgXcQ' />; // Google Maps 嵌入 import { GoogleMapsEmbed } from '@next/third-parties/google'; <GoogleMapsEmbed apiKey='YOUR_API_KEY' mode='place' q='Brooklyn+Bridge,New+York,NY' />;

• YouTubeEmbed：只需videoid（视频 ID），组件负责懒加载与合适的占位。
• GoogleMapsEmbed：需要apiKey，mode控制地图模式（如place地点模式），q是查询内容，URL 编码格式（如Brooklyn+Bridge,New+York,NY）。

这些组件同样把加载时机、占位与资源优化内置，避免手写懒加载逻辑。

快速参考表

以下问题模式与对应修复，可作为 Code Review 的检查清单：

在本仓库落地这套规范的实操建议

结合仓库现状，把这套规范落地的具体路径如下：

1. 确认依赖：本仓库 package.json 当前并未声明@next/third-parties依赖。需要接入 GA/GTM/YouTube/Google Maps 时，先安装该包，再在根布局 src/app/layout.tsx 中放置对应组件；next/script由next框架自带，无需额外安装。
2. 放置位置：本项目只有唯一根布局src/app/layout.tsx（App Router 结构见 src/app），所有beforeInteractive脚本和第三方分析组件都应挂在这里；页面级脚本使用默认的afterInteractive。
3. 内联脚本纪律：仓库现有内联脚本（根布局的主题色脚本、src/components/ui/chart.tsx 中的<style dangerouslySetInnerHTML>）均为原生标签且无副作用；若后续改用next/script承载内联逻辑，务必为每个<Script>补id。
4. 监控类脚本的特殊路径：仓库通过 next.config.ts 集成 Sentry（withSentryConfig），其客户端监控脚本由 SDK 在 src/instrumentation.ts / src/instrumentation-client.ts 中自动注入，属于"框架托管"的例外，不需要也不应手动用next/script再引一遍。
5. CSP 与安全：启用next/script后应配合Content-Security-Policy，为第三方域（googletagmanager.com、youtube.com等）单独放行script-src；内联脚本需配合nonce或将其收敛到beforeInteractive的白名单场景。

总结

第三方脚本是页面性能与合规的双重敏感区。本指南的核心结论可以压缩为四句话：

• 加载方式：一律使用next/script，让框架调度去重与策略；
• 内联脚本：使用Script时必带id，并注意Head内外之分；
• 策略选择：默认afterInteractive，低优先用lazyOnload，关键前置用beforeInteractive且只在根布局使用，worker属实验特性慎用；
• 官方封装：GA/GTM/YouTube/Maps 交给@next/third-parties，不要手写样板。

对正在使用或二次开发 next-shadcn-dashboard-starter 的开发者，上述规范配合仓库根布局的真实内联脚本案例，即构成一份可直接执行的脚本治理清单；相关原始规则始终保存在 .agents/skills/next-best-practices/scripts.md 中，可供 Agent 与人工评审持续引用。

• 前端
• UI组件