---
title: "第一方模式：注重隐私的代理"
description: "通过您域名上的反向代理路由第三方脚本流量，并自动进行匿名化处理。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/first-party"
last_updated: "2026-08-11T09:33:10.271Z"
---

## 为什么要代理第三方脚本？

第三方请求会将访客的浏览器直接连接到供应商服务器，从而暴露 IP 地址和浏览器信号，这些信息可能会促成[指纹识别](https://developer.mozilla.org/en-US/docs/Glossary/Fingerprinting)。当前的 [Nuxt Scripts 审计快照](https://github.com/nuxt/scripts/blob/main/packages/script/src/script-sizes.json) 说明了为什么仅统计脚本标签数量是不够的：集成可能会设置多个 Cookie、联系多个域名，并在其加载器运行后检查设备数据。

广告拦截器可能会阻止这些请求，导致依赖这些请求的分析数据出现缺失。

## 第一方模式的工作原理

对于受支持的注册脚本，第一方模式可以捆绑 SDK、代理其运行时请求，并在转发数据之前将其匿名化。每个注册表定义都会声明该脚本支持其中哪些功能。

### 打包

在 `nuxt build` 期间，模块下载第三方脚本并将其保存为本地资产在 `/_scripts/assets/[hash].js`。在运行时，您的服务器（或 CDN）从您自己的域名提供这些文件，而不是原始的第三方 CDN。

初始请求不再访问原始主机，也无需承担其 [DNS 和连接设置开销](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/dns-prefetch)。内容寻址的文件名还允许浏览器长期缓存捆绑后的脚本。

### 反向代理

运行时请求（分析信标、像素触发、跟踪调用）被拦截并通过 Nitro 服务器路由在 `/_scripts/p/` 转发。模块在两个级别重写 URL：

1. **构建时的 AST 重写**：将捆绑脚本源代码中的第三方域名替换为您的代理路径
2. **客户端运行时包装器**：AST 转换会将受支持捆绑 SDK 中的 `fetch`、`sendBeacon`、`XMLHttpRequest` 和 `Image` 调用重定向到 Nuxt Scripts 包装器，通过这些包装器代理动态构造的 URL

受支持的脚本和采集请求使用同源 URL，因此在这些响应上设置的 Cookie 不属于[第三方 Cookie](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Third-party_cookies)。基于主机的阻止规则不太可能匹配这些请求，但基于路径或行为的规则仍可能阻止请求。

### 匿名化

默认情况下，代理会将 IP 地址匿名化到子网级别，并在转发请求之前移除 Cookie 和身份验证令牌等敏感标头。每个脚本的隐私级别决定了它是否还会更改用户代理、屏幕尺寸和硬件指纹。

即使仅进行最低限度的匿名化，通过反向代理路由的请求也会显示为同源请求，并且不会暴露浏览器与上游服务之间的直接连接。

<callout color="amber">

隐私转换器会有意保留分析标识符和 `uid`、`cid`、`email` 及 `phone` 等用户数据字段；SDK 可能会在发送这些值之前对其中一些值进行哈希处理。第一方模式会减少选定的网络数据和指纹数据，但不会使包含身份信息的分析负载变为匿名。

</callout>

## 使用方法

注册表脚本默认使用其支持的第一方功能。添加条目后，无需加载脚本即可准备其代理路由、捆绑资源、类型和组合式函数：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      // 仅基础设施；使用组合式函数在特定页面加载
      googleAnalytics: { id: 'G-XXXXXX' },
      metaPixel: { id: '123456' },

      // 基础设施 + 全局自动加载
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', trigger: 'onNuxtReady' },
    }
  }
})
```

没有 `trigger` 的脚本仅作为基础设施：该模块为脚本准备任何支持的基础设施（代理路由、打包、组合式函数），但脚本仅在您在组件中调用组合式函数时加载。添加 `trigger` 以全局自动加载。

## 隐私层级

每个代理脚本都有一个默认隐私层级，该层级根据其 SDK 所需的数据选择：

<table>
<thead>
  <tr>
    <th>
      层级
    </th>
    
    <th>
      匿名化内容
    </th>
    
    <th>
      脚本
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        完全
      </strong>
    </td>
    
    <td>
      IP、用户代理、语言、屏幕、时区、硬件指纹
    </td>
    
    <td>
      Meta Pixel、TikTok Pixel、X Pixel、Snapchat Pixel、Reddit Pixel、LinkedIn Insight Tag
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        热图安全
      </strong>
    </td>
    
    <td>
      IP、语言、硬件指纹（保留屏幕和用户代理，以支持会话回放）
    </td>
    
    <td>
      Google Analytics、Google AdSense、Microsoft Clarity、Hotjar
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        仅 IP
      </strong>
    </td>
    
    <td>
      将 IP 地址匿名化至子网级别
    </td>
    
    <td>
      Plausible、PostHog、Umami、Cloudflare Web Analytics、Vercel Analytics、Rybbit、Databuddy、Matomo、Ahrefs Web Analytics、Intercom、YouTube、Vimeo、Gravatar、Calendly
    </td>
  </tr>
</tbody>
</table>

敏感请求头（`cookie`、`authorization`）无论层级如何都会被**始终**剥离。

### 六项隐私标识

每个层级都会从六个隐私标识中进行选择。[隐私转换器源代码](https://github.com/nuxt/scripts/blob/main/packages/script/src/runtime/server/utils/privacy.ts)定义了每个标识所修改的具体请求头、查询参数和载荷字段：

<table>
<thead>
  <tr>
    <th>
      标识
    </th>
    
    <th>
      功能说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ip
      </code>
    </td>
    
    <td>
      将请求头和载荷参数中的 IP 地址匿名化至子网级别
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent
      </code>
    </td>
    
    <td>
      将 User-Agent 规范化为浏览器系列 + 主版本（例如 <code className="language-ts shiki shiki-themes github-light github-light material-theme-palenight" language="ts" style="">
        <span class="sqjlB">
          Mozilla
        </span>
        
        <span class="sc1V3">
          /
        </span>
        
        <span class="sjz_z">
          5.0
        </span>
        
        <span class="sqjlB">
          (compatible; Chrome
        </span>
        
        <span class="sc1V3">
          /
        </span>
        
        <span class="sjz_z">
          131.0
        </span>
        
        <span class="sqjlB">
          )
        </span>
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      将 Accept-Language 规范化为主要语言标签
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        screen
      </code>
    </td>
    
    <td>
      将屏幕分辨率、视口、硬件并发数和设备内存概括为常见区间
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timezone
      </code>
    </td>
    
    <td>
      将时区偏移量和 IANA 时区名称概括化
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hardware
      </code>
    </td>
    
    <td>
      将画布/WebGL/音频指纹、插件/字体列表、浏览器版本和设备信息匿名化
    </td>
  </tr>
</tbody>
</table>

### 层级标识矩阵

<table>
<thead>
  <tr>
    <th>
      标识
    </th>
    
    <th align="center">
      仅 IP
    </th>
    
    <th align="center">
      热图安全
    </th>
    
    <th align="center">
      完全
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ip
      </code>
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        userAgent
      </code>
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        screen
      </code>
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timezone
      </code>
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hardware
      </code>
    </td>
    
    <td align="center">
      
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
    
    <td align="center">
      <icon name="i-heroicons-check">
        
      </icon>
    </td>
  </tr>
</tbody>
</table>

**仅 IP** 会将 IPv4 地址的最后一个八位组归零（/24），或仅保留 IPv6 地址的前 48 位。这会降低精度，但不保证特定的地理定位准确度。**热图安全**会规范化语言和硬件指纹数据，同时保留会话回放工具所使用的用户代理和屏幕尺寸。**完全**会应用全部六项隐私转换。

### 全局覆盖

使用顶层的 `privacy` 选项替换所有代理脚本的默认设置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    privacy: true, // 对所有代理脚本进行完全匿名化
  }
})
```

或者选择性覆盖特定标识：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    privacy: { ip: true }, // 对代理流量中的 IP 进行匿名化；直接请求不受影响
  }
})
```

### 每个脚本的隐私覆盖

向注册表条目添加 `privacy`，以覆盖单个脚本的设置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      // 对 Plausible 应用所有隐私转换，而不是使用其仅 IP 的默认设置
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', privacy: true },
      // 对由你控制数据的自托管 PostHog 仅匿名化 IP
      posthog: { apiKey: 'phc_xxx', privacy: { ip: true } },
    }
  }
})
```

### 禁用匿名化

按脚本或全局设置 `privacy: false`，即可停止匿名化数据。请求仍会通过你的服务器：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    privacy: false, // 不对任何脚本进行匿名化（路由仍然有效）
  }
})
```

## 隐藏主机名

默认情况下，代理路径包含第三方主机名，例如 `/_scripts/p/us.i.posthog.com/e/`。使用自托管服务时，这可能会暴露内部域名，例如 `/_scripts/p/analytics.internal.example.com/api/send`。原样显示的主机名也会让广告拦截器和网络观察者更容易对请求进行分类。

使用 `proxy.alias` 将主机名部分替换为别名。

设置 `alias: true`，即可为每个域名自动生成一个简短的不透明别名：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    proxy: {
      alias: true, // /_scripts/p/a1b2c3d4/e/
    }
  }
})
```

或者将特定域名映射到自定义别名。未列出的域名将保留其原始主机名：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    proxy: {
      alias: {
        'us.i.posthog.com': 'ph',
        'analytics.internal.example.com': 'a',
      }
    }
  }
})
```

别名会应用于所有生成代理路径的场景：构建时 URL 重写、自动注入的端点（例如 PostHog 的 `apiHost`）、运行时拦截的请求，以及 Partytown worker 请求。服务器处理程序会在向上游转发之前，将别名解析回真实域名。

<callout type="info">

别名只会更改主机名部分。要更改 `/_scripts/p`，请设置顶层 `prefix` 选项，例如 `prefix: '/_t'`。

</callout>

<callout type="warning">

别名会将真实主机名从请求的**URL**中移除。如果 SDK 在运行时构建其数据收集 URL，主机名仍可能出现在客户端 JavaScript 中。别名会更改网络中可见的路径，但不会混淆你的 bundle。

</callout>

## 选择退出

### 每个脚本

在其注册表配置中使用 `proxy: false` 禁用特定脚本的代理：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', proxy: false },
      googleAnalytics: { id: 'G-XXXXXX' }, // 仍然使用代理
    }
  }
})
```

对于其采集请求依赖 AST URL 重写的脚本，设置 `bundle: false` 也会阻止这些请求使用代理。没有打包的脚本源，就没有可供转换器重写的 SDK URL 或调用。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      // 禁用打包以及依赖打包的代理重写
      googleAnalytics: { id: 'G-XXXXXX', bundle: false },
    }
  }
})
```

<callout type="info">

PostHog 通过 SDK 配置接收代理端点，因此无需打包即可代理采集请求。Matomo 则不同：除非使用下文所述的独立 Partytown 路由路径，否则其正常的主线程加载器仍会直接连接。

</callout>

### 静态托管 (SSG)

反向代理需要**服务器运行时**。完全静态的部署会提供 [`nuxt generate`](https://nuxt.com/docs/getting-started/prerendering) 的输出，但没有 Nitro 进程来处理 `/_scripts/p/**`。Nuxt Scripts 会针对已知的静态预设发出警告，但不会将代理 URL 重写为其第三方源站。请为受影响的脚本禁用代理，或使用支持外部源站重写的托管平台。例如，[Vercel 重写](https://vercel.com/docs/routing/rewrites)支持 `/:path*` 捕获以及外部目标地址：

```json [vercel.json]
{
  "rewrites": [
    { "source": "/_scripts/p/www.google-analytics.com/:path*", "destination": "https://www.google-analytics.com/:path*" },
    { "source": "/_scripts/p/www.googletagmanager.com/:path*", "destination": "https://www.googletagmanager.com/:path*" },
    { "source": "/_scripts/p/connect.facebook.net/:path*", "destination": "https://connect.facebook.net/:path*" }
  ]
}
```

[Netlify 代理重写](https://docs.netlify.com/manage/routing/redirects/rewrites-proxies/)使用类似 `/_scripts/p/www.google-analytics.com/* https://www.google-analytics.com/:splat 200` 的 `200` 规则。Cloudflare Pages 则有所不同：其 [`_redirects` 代理规则](https://developers.cloudflare.com/pages/configuration/redirects/#proxying)仅支持相对目标地址，不支持外部域名。如果需要在静态 Cloudflare Pages 部署中使用此代理，请使用 [Pages Function](https://developers.cloudflare.com/pages/functions/) 或 Worker。只配置站点实际使用的域名；Nuxt DevTools → Scripts 和 Nitro 日志会显示已注册的域名集合。

<callout type="warning">

平台级重写会绕过隐私匿名化层。代理处理程序只会在 Nitro 服务器运行时中执行。

</callout>

## 代理端点安全

嵌入、头像和分析代理路由是公共资源。它们不包含服务器端 API 密钥。每个路由只接受其集成所声明的上游主机和请求结构。

<callout type="warning">

运行时代理获取请求会在请求之前验证初始上游 URL 以及每个重定向目标。在每个运行时中，直接指向本地、私有、链路本地和保留地址的目标都会被拒绝；Node 部署还会在建立套接字连接之前验证并固定 DNS 解析结果。图像路由会拒绝 HTML 和 SVG 等活动内容类型。Instagram 嵌入路由会限制帖子和样式表主机，然后在客户端渲染之前对返回的片段进行清理。

</callout>

Nuxt Scripts 不会代理 Google Maps 请求。静态地图使用公开的浏览器密钥从 Google 加载，而位置查找使用 Maps JavaScript Places 服务。请为该密钥应用网站和 API 限制，然后配置 Google Cloud 配额以控制支出。请参阅 [Google Maps Platform 安全指南](https://developers.google.com/maps/api-security-best-practices)。

如果公共嵌入流量需要请求限制，请在部署边缘配置这些限制，或添加应用程序中间件。Nitro 2 路由规则不提供可移植的速率限制器。

## 支持的脚本

以下分组遵循 [Nuxt Scripts 注册表中的能力声明](https://github.com/nuxt/scripts/blob/main/packages/script/src/registry.ts)。

### 完整第一方（已捆绑 + 已代理）

这些脚本会在构建时下载，从您的域名提供，并通过您的服务器代理其收集请求：

<table>
<thead>
  <tr>
    <th>
      类别
    </th>
    
    <th>
      脚本
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        分析
      </strong>
    </td>
    
    <td>
      <a href="/scripts/google-analytics">
        Google Analytics
      </a>
      
      、<a href="/scripts/plausible-analytics">
        Plausible
      </a>
      
      、<a href="/scripts/cloudflare-web-analytics">
        Cloudflare Web Analytics
      </a>
      
      、<a href="/scripts/umami-analytics">
        Umami
      </a>
      
      、<a href="/scripts/rybbit-analytics">
        Rybbit
      </a>
      
      、<a href="/scripts/databuddy-analytics">
        Databuddy
      </a>
      
      、<a href="/scripts/ahrefs-analytics">
        Ahrefs Web Analytics
      </a>
      
      、<a href="/scripts/vercel-analytics">
        Vercel Analytics
      </a>
      
      、<a href="/scripts/clarity">
        Microsoft Clarity
      </a>
      
      、<a href="/scripts/hotjar">
        Hotjar
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        广告像素
      </strong>
    </td>
    
    <td>
      <a href="/scripts/meta-pixel">
        Meta Pixel
      </a>
      
      、<a href="/scripts/tiktok-pixel">
        TikTok Pixel
      </a>
      
      、<a href="/scripts/x-pixel">
        X Pixel
      </a>
      
      、<a href="/scripts/snapchat-pixel">
        Snapchat Pixel
      </a>
      
      、<a href="/scripts/reddit-pixel">
        Reddit Pixel
      </a>
      
      、<a href="/scripts/linkedin-insight">
        LinkedIn Insight Tag
      </a>
      
      、<a href="/scripts/google-adsense">
        Google AdSense
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        视频
      </strong>
    </td>
    
    <td>
      <a href="/scripts/vimeo-player">
        Vimeo Player
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        工具
      </strong>
    </td>
    
    <td>
      <a href="/scripts/intercom">
        Intercom
      </a>
      
      、<a href="/scripts/gravatar">
        Gravatar
      </a>
    </td>
  </tr>
</tbody>
</table>

### 仅代理（基于软件包）

该模块不会捆绑 PostHog 的 SDK，因为它来自软件包依赖，但仍可通过您的服务器发送收集请求：

<table>
<thead>
  <tr>
    <th>
      脚本
    </th>
    
    <th>
      工作原理
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/scripts/posthog">
        PostHog
      </a>
    </td>
    
    <td>
      SDK 作为 <a href="https://posthog.com/docs/libraries/js#option-2-install-via-package-manager" rel="nofollow">
        <code>
          posthog-js
        </code>
      </a>
      
       安装。通过 <code>
        apiHost
      </code>
      
       配置自动注入代理端点。
    </td>
  </tr>
</tbody>
</table>

### 已捆绑，但包含第三方运行时流量

这些集成会从您的域名提供其主要加载器，但部分运行时请求仍会直接发送到第三方服务器：

<table>
<thead>
  <tr>
    <th>
      脚本
    </th>
    
    <th>
      剩余的直接流量
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/scripts/google-tag-manager">
        Google Tag Manager
      </a>
    </td>
    
    <td>
      GTM 的核心功能是在运行时加载其他脚本。这些运行时脚本会绕过构建时重写。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/fathom-analytics">
        Fathom
      </a>
    </td>
    
    <td>
      Fathom 的机器人检测会拒绝来自服务器 IP 的信标请求，因此 Nuxt Scripts 会捆绑 SDK，但让信标请求保持直接发送。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/segment">
        Segment
      </a>
    </td>
    
    <td>
      SDK 会动态构造 API URL，从而绕过请求拦截。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/crisp">
        Crisp
      </a>
    </td>
    
    <td>
      SDK 会在运行时从 <code>
        client.crisp.chat
      </code>
      
       加载辅助脚本和 CSS。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/mixpanel-analytics">
        Mixpanel
      </a>
    </td>
    
    <td>
      尚无代理集成。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/bing-uet">
        Bing UET
      </a>
    </td>
    
    <td>
      尚无代理集成。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/npm">
        npm
      </a>
    </td>
    
    <td>
      注册表条目会捆绑所选软件包文件，但没有特定于供应商的代理规则。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/youtube-player">
        YouTube Player
      </a>
    </td>
    
    <td>
      Nuxt Scripts 会捆绑 API 加载器，但 facade 会在捆绑转换完成后提供直接的 <code>
        youtube.com
      </code>
      
       或 <code>
        youtube-nocookie.com
      </code>
      
       iframe 主机。该 iframe 及其内部请求仍属于第三方。
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/scripts/calendly">
        Calendly
      </a>
    </td>
    
    <td>
      小组件脚本和资源可以使用第一方路由，但预约 iframe 及其流量会直接从 <code>
        calendly.com
      </code>
      
       加载。
    </td>
  </tr>
</tbody>
</table>

捆绑可以避免主要加载器连接到其原始主机，但不会使所有运行时流量都变为第一方流量。

### 直接加载（无活跃捆绑或收集代理）

这些集成会直接从其配置的主机加载 SDK 及运行时流量：

<table>
<thead>
  <tr>
    <th>
      脚本
    </th>
    
    <th>
      直接加载行为
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Stripe
      </strong>
    </td>
    
    <td>
      为满足 PCI 合规要求，<a href="https://docs.stripe.com/payments/finalize-payments-on-the-server?platform=web&type=setup" rel="nofollow">
        Stripe 要求直接从 <code>
          js.stripe.com
        </code>
        
         加载 Stripe.js
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        PayPal
      </strong>
    </td>
    
    <td>
      Nuxt Scripts 会从 PayPal 文档规定的 <a href="https://developer.paypal.com/upgrade/ec/guide/Web%20SDK%20v6/" rel="nofollow">
        <code>
          /web-sdk/v6/core
        </code>
        
         URL
      </a>
      
       加载 PayPal v6 核心；注册表未声明捆绑或收集代理。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Google reCAPTCHA
      </strong>
    </td>
    
    <td>
      Nuxt Scripts 会直接从 Google 或 <code>
        recaptcha.net
      </code>
      
       加载 <code>
        api.js
      </code>
      
       或 <code>
        enterprise.js
      </code>
      
      ；注册表未声明捆绑或收集代理。Google 还建议尽早加载 reCAPTCHA，因为<a href="https://developers.google.com/recaptcha/docs/loading" rel="nofollow">
        更多页面上下文有助于改进其评估
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Google Sign-In
      </strong>
    </td>
    
    <td>
      Google 表示，<a href="https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid" rel="nofollow">
        不支持自托管副本和离线副本
      </a>
      
      ，以确保客户端能够接收安全性和兼容性更新。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Matomo
      </strong>
    </td>
    
    <td>
      主线程 SDK 不会被捆绑，因此其常规请求会继续使用配置的 Matomo 主机。启用 <code>
        partytown: true
      </code>
      
       后，Nuxt Scripts 可以通过 Partytown 的 <code>
        resolveUrl
      </code>
      
       路由匹配的 worker 请求；但下方的 Partytown 限制仍然适用。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Carbon Ads
      </strong>
    </td>
    
    <td>
      该组件会直接加载广告脚本。由于此条目不会被捆绑，收集重写会跳过它。
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Lemon Squeezy
      </strong>
    </td>
    
    <td>
      该可组合函数会直接加载支付小组件。由于此条目不会被捆绑，收集重写会跳过它。
    </td>
  </tr>
</tbody>
</table>

Google Maps、SpeedCurve LUX 和 Usercentrics 也会直接加载，因为它们没有声明捆绑或收集代理能力。

## Partytown（Web Worker）

通过为每个脚本设置 `partytown: true`，在 [Partytown web worker](https://partytown.qwik.dev/how-does-partytown-work/) 中加载单个脚本。下面的 `trigger` 会使 registry 插件全局调用该组合式函数；它不会延迟 Partytown 标签的加载，该标签会被写入服务端渲染的 HTML 中。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
  scripts: {
    registry: {
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', partytown: true, trigger: 'onNuxtReady' },
    }
  }
})
```

转发数组会为受支持的脚本自动配置。您必须安装 `@nuxtjs/partytown`。

<callout color="amber">

当前的 Partytown 路径仅保留脚本的 `src`。它会跳过其他属性、registry 初始化钩子、触发时机以及通常的组合式函数代理/上下文 API。声明 Partytown 能力意味着 Nuxt Scripts 知道转发和路由配置；但这并不保证依赖 `data-*` 属性或 `clientInit` 的集成能够正确初始化。请验证生成的标签和供应商流量。

</callout>

<callout color="amber" icon="i-heroicons-exclamation-triangle">

当 Google Tag Manager 在 worker 中运行时，Partytown 跟踪器存在一个关于 GA4 会话丢失的[公开报告](https://github.com/QwikDev/partytown/issues/583)。Nuxt Scripts 不声明对 GTM 的 Partytown 支持。在将 GA4 移至 Partytown 之前，请先测试分析数据的发送。

</callout>

## 同意集成

第一方模式控制请求的*去向*。[同意触发器](/docs/guides/consent)控制主线程脚本的*加载时机*。当前的 Partytown 路径会忽略触发时机，因此不要依赖 Nuxt Scripts 的同意触发器来控制 Partytown 标签的加载。

```vue
<script setup lang="ts">
const trigger = useScriptTriggerConsent()

useScriptGoogleAnalytics({
  id: 'G-XXXXXX',
  scriptOptions: { trigger }
})
</script>
```

### 第三方同意管理器

对于 OneTrust、CookieBot 或 Osano 等工具，将其同意信号绑定到响应式 ref：

```vue
<script setup lang="ts">
const hasAnalyticsConsent = ref(false)

// 示例：OneTrust 回调
onMounted(() => {
  window.OneTrust?.OnConsentChanged(() => {
    hasAnalyticsConsent.value = window.OnetrustActiveGroups?.includes('C0002') ?? false
  })
})

useScriptGoogleAnalytics({
  id: 'G-XXXXXX',
  scriptOptions: {
    trigger: useScriptTriggerConsent({ consent: hasAnalyticsConsent }),
  }
})
</script>
```

或者让注册表条目仅负责基础设施，并在获得同意后对组合式函数结果调用 `load()`：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      // 仅基础架构，在获得同意后手动加载
      googleAnalytics: { id: 'G-XXXXXX' },
    }
  }
})
```

```vue [app.vue]
<script setup lang="ts">
const script = useScriptGoogleAnalytics()

function onConsentGranted() {
  script.load()
}
</script>
```

[同意管理指南](/docs/guides/consent)介绍了 `useScriptTriggerConsent()` 以及针对特定供应商的控制方式。

<callout type="info">

通过你的域名转发请求并不能解决同意问题。对于在欧盟的部署，EDPB 最终发布的 [第 5(3) 条技术范围指南](https://www.edpb.europa.eu/system/files/documents/2024-10/edpb_guidelines_202302_technical_scope_art_53_eprivacydirective_v2_en_0.pdf)涵盖跟踪 URL、像素和 JavaScript，以及 Cookie。在加载每个脚本之前，请评估其用途和适用司法管辖区。

</callout>

## 故障排除

<table>
<thead>
  <tr>
    <th>
      问题
    </th>
    
    <th>
      解决方案
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Analytics 未进行跟踪
    </td>
    
    <td>
      在 DevTools → Network 中检查 <code>
        /_scripts/p/
      </code>
      
       请求。检查 Nitro 服务器日志中是否存在代理错误
    </td>
  </tr>
  
  <tr>
    <td>
      静态网站上的代理无法工作
    </td>
    
    <td>
      静态托管服务不会运行 Nitro 代理处理程序。禁用代理、添加平台重写规则，或切换到服务器部署。请参阅<a href="#static-hosting-ssg">
        静态托管
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      脚本过时
    </td>
    
    <td>
      删除 <code>
        node_modules/.cache/nuxt/scripts
      </code>
      
       并重新构建
    </td>
  </tr>
  
  <tr>
    <td>
      构建下载失败
    </td>
    
    <td>
      设置 <code className="language-ts shiki shiki-themes github-light github-light material-theme-palenight" language="ts" style="">
        <span class="sqjlB">
          assets
        </span>
        
        <span class="sx-uw">
          .
        </span>
        
        <span class="sqjlB">
          fallbackOnSrcOnBundleFail:
        </span>
        
        <span class="sGFTI">
          true
        </span>
      </code>
      
      ，以回退到直接加载
    </td>
  </tr>
  
  <tr>
    <td>
      调试
    </td>
    
    <td>
      打开 Nuxt DevTools → Scripts，查看代理路由和隐私状态
    </td>
  </tr>
  
  <tr>
    <td>
      地理位置准确度降低
    </td>
    
    <td>
      IP 匿名化使用 IPv4 /24 或 IPv6 /48 前缀。为单个脚本或全局设置 <code>
        privacy: false
      </code>
      
      ，以转发精确 IP
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bundle: false
      </code>
      
       导致收集代理停止工作
    </td>
    
    <td>
      对代理支持依赖 AST 重写的脚本保持捆绑启用。自动注入的集成（如 PostHog）不需要捆绑；主线程 Matomo 仍保持直接加载
    </td>
  </tr>
  
  <tr>
    <td>
      每个脚本的退出配置不起作用
    </td>
    
    <td>
      对于启用了自动注入的脚本（Plausible、PostHog、Umami、Rybbit、Databuddy），在注册表配置中使用 <code>
        proxy: false
      </code>
    </td>
  </tr>
</tbody>
</table>