---
title: "v1.0.0"
description: "Nuxt Scripts v1 — 第一方隐私聚焦代理、Partytown Web Worker、SSR 社交嵌入、SRI 哈希以及新的注册表脚本。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/releases/v1"
last_updated: "2026-05-22T14:11:47.799Z"
---

Nuxt Scripts v1 是首个稳定版本，为第三方脚本带来更好的**隐私**和**性能**，推动生态系统向前发展。

## 📣 亮点

### 🔒 第一方模式：专注于隐私的代理

每一次第三方脚本请求都会将用户数据暴露给 [指纹识别](https://firstpartysimulator.net/learn)。

不同提供商的侵入性各不相同，例如，X Pixel 会访问 9 个浏览器指纹识别 API（包括 `navigator.getBattery()`），设置 5 个跟踪 Cookie，并向 3 个独立域发送请求。Microsoft Clarity 会跨 3 个域读取 10 个指纹识别 API。

第一方模式充当**反向代理**：Nuxt 在构建时打包脚本并通过你的域名提供，同时运行时请求会通过你的服务器安全转发。发送给第三方服务器的数据会被匿名化：IP（`180.233.124.74` -> `180.233.124.0`）、浏览器版本（`Mozilla/5.0 (compatible; Chrome/120.0)`）等等。对所有支持它的脚本都会**自动启用**。

副作用是性能提升，避免了额外的 DNS 查找，减少了 Cookie 横幅，并减少了昂贵的指纹识别查询。由于请求表现为同源，这也使得广告拦截器失效。

详见 [第一方模式指南](/docs/guides/first-party) 和 [PR #577](https://github.com/nuxt/scripts/pull/577)。

### ⚡ Partytown Web Worker 支持

使用 [Partytown](https://partytown.builder.io/) 在主线程之外加载第三方脚本。脚本在 Web Worker 中运行，释放主线程供您的应用程序使用。与第一方模式直接集成。参见 [PR #576](https://github.com/nuxt/scripts/pull/576)。

为每个脚本设置 `partytown: true`：

```ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
  scripts: {
    registry: {
      plausibleAnalytics: { domain: 'example.com', partytown: true },
      fathomAnalytics: { site: 'XXXXX', partytown: true },
      umamiAnalytics: { websiteId: 'xxx', partytown: true },
    }
  }
  // 转发数组按脚本自动配置！
})
```

**支持自动转发的脚本：** `googleAnalytics`、`plausibleAnalytics`、`fathomAnalytics`、`umamiAnalytics`、`matomoAnalytics`、`segment`、`mixpanelAnalytics`、`bingUet`、`metaPixel`、`xPixel`、`tiktokPixel`、`snapchatPixel`、`redditPixel`、`cloudflareWebAnalytics`

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

GA4 与 Partytown 存在 [已知问题](https://github.com/BuilderIO/partytown/issues/583)。GTM 不兼容（需要 DOM 访问）。请考虑使用 Plausible、Fathom 或 Umami。

</callout>

### 🐦 SSR 社交嵌入

第三方嵌入脚本（Twitter 小组件、Instagram 嵌入、Bluesky 帖子）会影响性能并泄露用户数据。遵循 [Cloudflare Zaraz 方法](https://blog.cloudflare.com/zaraz-supports-server-side-rendering-of-embeds/)，Nuxt Scripts 现在会在服务端获取嵌入数据，并通过你的域名安全代理所有资源。参见 [PR #590](https://github.com/nuxt/scripts/pull/590)。

```vue
<ScriptXEmbed tweet-id="1754336034228171055">
  <template #default="{ userName, text, likesFormatted, photos }">
    <!-- 通过作用域插槽完全控制样式 -->
  </template>
</ScriptXEmbed>

<ScriptInstagramEmbed post-url="https://instagram.com/p/ABC123/">
  <template #default="{ html, shortcode }">
    <div v-html="html" />
  </template>
</ScriptInstagramEmbed>

<ScriptBlueskyEmbed post-url="https://bsky.app/profile/...">
  <template #default="{ html }">
    <div v-html="html" />
  </template>
</ScriptBlueskyEmbed>
```

### ✋ 一等公民级别的同意控制

v1 将同意视为一等公民问题，并提供两个互补的 API。参见 [同意指南](/docs/guides/consent)、[PR #544](https://github.com/nuxt/scripts/pull/544)、[PR #631](https://github.com/nuxt/scripts/pull/631) 和 [PR #712](https://github.com/nuxt/scripts/pull/712)。

**Consent Trigger** 用于控制脚本是否加载。[`useScriptTriggerConsent()`](/docs/api/use-script-trigger-consent) 组合式函数现在支持在运行时撤销同意，而不仅仅是授予同意：

```ts
const trigger = useScriptTriggerConsent()
useScriptGoogleTagManager({ id: 'GTM-XXX', scriptOptions: { trigger } })

trigger.accept() // 授权 → 脚本加载
trigger.revoke() // 撤销 → 脚本被阻止
trigger.consented // Ref<boolean>
```

**供应商原生控制**：对于已经加载的脚本，每个具备同意感知能力的注册表脚本现在都会在返回的实例上暴露一个供应商原生的 `consent` 对象，并提供一个类型化的 `defaultConsent` 选项，该选项会在第一次跟踪调用之前应用。此功能已支持 Google Analytics、Google Tag Manager、Bing UET、Meta Pixel、TikTok Pixel、Matomo、Mixpanel、PostHog 和 Clarity。每个供应商都保留自己的方言（Google/Bing 使用 GCMv2，Meta 使用 `grant`/`revoke`，Mixpanel/PostHog 使用 `opt_in`/`opt_out` 等），因此文档和类型一一对应。`#nuxt-scripts/types` 导出了 GCMv2 的 `ConsentState`。

```ts
const gtm = useScriptGoogleTagManager({
  id: 'GTM-XXX',
  defaultConsent: { ad_storage: 'denied', analytics_storage: 'denied' },
})
// 之后，在用户接受后
gtm.consent.update({ ad_storage: 'granted', analytics_storage: 'granted' })

const ttq = useScriptTikTokPixel({ id: '...', defaultConsent: 'hold' })
ttq.consent.grant() // 或 .revoke() / .hold()

const meta = useScriptMetaPixel({ id: '...', defaultConsent: 'denied' })
meta.consent.grant()
```

### 🛠️ 重建的 DevTools

Nuxt DevTools 面板已围绕 v1 的隐私和能力模型重新编写。新的视图会展示 v1 的不同之处：

- **第一方面板**：检查每个代理路由，显示每个端点启用的匿名化标志（IP、用户代理、语言、屏幕、时区、硬件），并高亮哪些第三方域正在通过你的服务器路由。
- **注册表面板**：能力矩阵，显示哪些脚本支持 `bundle`、`proxy` 和 `partytown`，以及哪些能力默认启用、哪些需要按脚本选择启用。
- **脚本检查**：每个脚本的状态、加载时序、网络瀑布图、包体大小和内联文档。
- **独立连接视图**：将 DevTools 连接到生产构建，以便在不在生产环境运行完整 DevTools 运行时的情况下进行即时检查。

### 📦 新的注册表脚本

- **PostHog Analytics** ([#568](https://github.com/nuxt/scripts/pull/568)): 带功能标志的产品分析
- **Google reCAPTCHA v3** ([#567](https://github.com/nuxt/scripts/pull/567)): 隐形机器人保护
- **TikTok Pixel** ([#569](https://github.com/nuxt/scripts/pull/569)): 转化追踪
- **Google Sign-In** ([#573](https://github.com/nuxt/scripts/pull/573)): 一键认证
- **Rybbit Analytics** ([#453](https://github.com/nuxt/scripts/pull/453)): 专注于隐私的开源分析
- **Databuddy Analytics** ([#495](https://github.com/nuxt/scripts/pull/495)): 轻量级分析
- **Bing UET** ([#650](https://github.com/nuxt/scripts/pull/650)): Microsoft Advertising 转化追踪
- **Mixpanel Analytics** ([#648](https://github.com/nuxt/scripts/pull/648)): 产品分析及用户追踪
- **Vercel Analytics** ([#605](https://github.com/nuxt/scripts/pull/605)): Vercel Web Analytics 集成
- **Gravatar** ([#606](https://github.com/nuxt/scripts/pull/606)): 带有隐私保护代理的头像服务

## 其他变更

### 🔄 Script Reload API

脚本现在提供一个 [`.reload()`](/docs/api/use-script) 方法，用于在 SPA 导航后重新执行基于 DOM 扫描的脚本。参见 [commit 77f853b](https://github.com/nuxt/scripts/commit/77f853b)。

```ts
const script = useScript('/third-party.js')
await script.reload()
```

### 🔐 自动 SRI 完整性哈希

捆绑的脚本可以自动生成子资源完整性哈希。参见 [PR #575](https://github.com/nuxt/scripts/pull/575)。

```ts
export default defineNuxtConfig({
  scripts: {
    assets: {
      integrity: 'sha384'
    }
  }
})
```

### 📊 脚本统计导出

新的 `@nuxt/scripts/stats` 子路径导出，用于审计脚本的隐私、性能和安全特性。

```ts
import { getScriptStats } from '@nuxt/scripts/stats'

const stats = await getScriptStats()
// 隐私评级（A+ 到 F）、性能评级、CWV 估算、
// Cookie 分析、网络行为、跟踪的数据类型
```

### 🎬 YouTube 播放器全面改进

- **独立的播放器实例** ([#586](https://github.com/nuxt/scripts/pull/586))：多个播放器可正常工作
- **宽高比控制**：新增 `ratio` 属性
- **正确的清理**：卸载时销毁播放器

### 📹 Vimeo 播放器增强

- **宽高比控制** ([#624](https://github.com/nuxt/scripts/pull/624))：新增 `ratio` 属性，与 YouTube 播放器 API 保持一致

### 🗺️ Google 地图全面改进

Google 地图集成在 v1 中进行了重大 DX 改进，使其感觉像原生 Vue 组件库，而不是选项包的包装器。

**声明式 SFC 组件** ([#510](https://github.com/nuxt/scripts/pull/510))：11 个可组合组件，用于标记、形状、叠加层、聚类等。所有组件都使用 Vue 的注入系统进行父子通信，并在卸载时自动清理。

**自定义标记内容** ([#658](https://github.com/nuxt/scripts/pull/658)): `ScriptGoogleMapsMarker` 上的 `#content` 插槽可用任何 HTML 或 Vue 模板替换默认图钉。以声明方式构建价格标签、状态徽章或任何自定义标记视觉元素。

```vue
<ScriptGoogleMapsMarker :position="{ lat: -34.397, lng: 150.644 }">
  <template #content>
    <div class="price-tag">$420k</div>
  </template>
</ScriptGoogleMapsMarker>
```

**自定义叠加层视图** ([#658](https://github.com/nuxt/scripts/pull/658))：`ScriptGoogleMapsOverlayView` 在地图位置上渲染任意 Vue 内容，具有完全的样式控制。嵌套在标记内部时，它自动继承位置并随标记拖动而移动。支持 `v-model:open` 用于切换可见性而无需重新挂载。

```vue
<ScriptGoogleMapsMarker :position="pos" @click="open = !open">
  <ScriptGoogleMapsOverlayView v-model:open="open" anchor="bottom-center" :offset="{ x: 0, y: -50 }">
    <MyCustomPopup @close="open = false" />
  </ScriptGoogleMapsOverlayView>
</ScriptGoogleMapsMarker>
```

**直接 :position 属性**：Marker 组件现在接受顶层的 `:position` 属性（对于最常见的场景，无需 options 包）。

**其他组件**：

- [**ScriptGoogleMapsStaticMap**](/scripts/google-maps/api/static-map) ([#673](https://github.com/nuxt/scripts/pull/673))：静态占位符现在是一个独立组件，图片会通过你的服务器路由，因此 API 密钥保持在服务端。可将其用于 `ScriptGoogleMaps` 的 `#placeholder` 内，或单独用于从不需要交互式 Maps API 的门店定位页和联系页面。
- [**ScriptGoogleMapsGeoJson**](/scripts/google-maps/api/geojson) ([#656](https://github.com/nuxt/scripts/pull/656))：围绕 `google.maps.Data` 的声明式封装，用于加载和样式化 GeoJSON，并支持完整事件绑定。

**基础设施**：

- **色彩模式支持** ([#587](https://github.com/nuxt/scripts/pull/587))：通过 `mapIds` 属性自动切换浅色/深色地图
- **地理编码代理**：服务端地理编码可减少计费并隐藏 API 密钥
- **内存泄漏修复** ([#651](https://github.com/nuxt/scripts/pull/651))：`useGoogleMapsResource` 组合式函数确保所有子组件在卸载时安全清理，即使跨越异步边界
- **标记聚类性能** ([#517](https://github.com/nuxt/scripts/pull/517), [#653](https://github.com/nuxt/scripts/pull/653))：使用 `noDraw` 标志进行批处理操作，避免多次重新渲染

**弃用**：遗留的 `ScriptGoogleMapsMarker`（包装 `google.maps.Marker`）和 `ScriptGoogleMapsAdvancedMarkerElement` 名称已合并为 `ScriptGoogleMapsMarker`（包装 `google.maps.marker.AdvancedMarkerElement`）。我们移除了 `ScriptGoogleMapsPinElement`；请改用 `ScriptGoogleMapsMarker` 上的 `#content` 插槽。

### 🔧 环境变量配置

该模块现在会为任何已启用的注册表条目自动填充 `runtimeConfig.public.scripts` 默认值。脚本 ID、密钥和域名会从 `NUXT_PUBLIC_SCRIPTS_*` 环境变量中解析，无需任何 `runtimeConfig` 样板代码。参见 [PR #634](https://github.com/nuxt/scripts/pull/634)。

```bash
# .env
NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID=G-XXXXXX
NUXT_PUBLIC_SCRIPTS_POSTHOG_API_KEY=phc_xxx
```

## ⚠️ 破坏性变更与迁移

如果你是从 v0 升级？请查看 [v0 到 v1 迁移指南](/docs/migration-guide/v0-to-v1)，其中包含每个破坏性变更和弃用的汇总表以及变更前/后的差异。

## 🐛 Bug 修复

- `cdfb697` fix(rybbit): 在脚本加载前对自定义事件进行排队 ([#585](https://github.com/nuxt/scripts/pull/585))
- `f8ce5a1` fix(gtm): 当 ID 在配置中时调用 onBeforeGtmStart 回调 ([#584](https://github.com/nuxt/scripts/pull/584))
- `a8d20b0` fix: 添加 `estree-walker` 作为依赖 ([#583](https://github.com/nuxt/scripts/pull/583))
- `4c79486` fix(plausible): 在 clientInit stub 中使用一致的 window 引用 ([#574](https://github.com/nuxt/scripts/pull/574))
- `78367b1` fix(matomo): 尊重用户提供的 URL 协议 ([#572](https://github.com/nuxt/scripts/pull/572))
- `c685f43` fix: 损坏的类型增强
- `e2050a2` fix: 使模板与现有增强保持一致 ([#589](https://github.com/nuxt/scripts/pull/589))
- `da3a8cc` chore: 包含 `.nuxt` 类型 ([#588](https://github.com/nuxt/scripts/pull/588))
- `039380e` fix: 防止所有 Google Maps 子组件中的内存泄漏 ([#651](https://github.com/nuxt/scripts/pull/651))
- `7e139b3` fix: 避免修改 runtimeConfig scriptOptions ([#638](https://github.com/nuxt/scripts/pull/638))
- `01b1af4` fix: 展开自闭合的 `<Script*>` 标签，以避免 SFC 提取问题 ([#613](https://github.com/nuxt/scripts/pull/613))
- `c3a6098` fix: 在代理处理程序中保留压缩/二进制请求体 ([#619](https://github.com/nuxt/scripts/pull/619))
- `96db067` fix: 缺少 Bing UET 类型 ([#710](https://github.com/nuxt/scripts/pull/710))
- `fdaf089` fix(types): 防止注册表条目类型坍缩为 `never` ([#701](https://github.com/nuxt/scripts/pull/701))
- `698a585` fix: 在可组合实例中继承注册表 scriptOptions ([#691](https://github.com/nuxt/scripts/pull/691))
- `506dfd8` fix(google-maps): 为已关闭/未定位的覆盖层保护 pan-on-open ([#698](https://github.com/nuxt/scripts/pull/698))
- `6fdd533` fix(google-maps): 防止重新渲染时中心点重置，并导出聚类器类型 ([#686](https://github.com/nuxt/scripts/pull/686))
- `0e4ae9e` fix(google-maps): 防止覆盖层切换时缩放/平移重置 ([#685](https://github.com/nuxt/scripts/pull/685))
- `33ebf61` fix(google-maps): 修复 `resolveQueryToLatLng` 中的竞争条件 ([#693](https://github.com/nuxt/scripts/pull/693))
- `4df13ed` fix: 为所有组件添加 `defineSlots` 以正确推断插槽类型 ([#684](https://github.com/nuxt/scripts/pull/684))
- `afbb6bd` fix(types): 修复 IDE 中注册表类型的显示问题 ([#683](https://github.com/nuxt/scripts/pull/683))
- `63d4da5` fix: 为破坏性配置变更添加 v0 迁移警告和文档 ([#679](https://github.com/nuxt/scripts/pull/679))
- `3007458` fix(google-analytics): 为代理域添加 `www.google.com` 和 `www.googletagmanager.com` ([#678](https://github.com/nuxt/scripts/pull/678))
- `1c47e72` fix: 为所有注册表脚本添加缺失的代理域
- `e6ecfff` fix(google-maps): 将 `$attrs` 绑定到 overlay view ([#672](https://github.com/nuxt/scripts/pull/672))
- `c2f8a8b` fix(google-maps): 从 OverlayView 中移除多余的插槽属性 ([#666](https://github.com/nuxt/scripts/pull/666))
- `b65e5db` fix(google-maps): 修复 OverlayView、InfoWindow 和 AdvancedMarkerElement 的 DX 问题 ([#660](https://github.com/nuxt/scripts/pull/660))
- `a597de9` fix: 防止 `ScriptGoogleMapsAdvancedMarkerElement` 中的内存泄漏 ([#649](https://github.com/nuxt/scripts/pull/649))
- `32ff4fa` fix: 改进注册表脚本 DX 和类型安全性 ([#647](https://github.com/nuxt/scripts/pull/647))
- `569eeeb` fix(first-party): 为布尔值/mock 注册表条目注入代理端点 ([#640](https://github.com/nuxt/scripts/pull/640))
- `00fbaae` fix: 允许 `ScriptRegistry` 类型中使用自定义脚本键 ([#632](https://github.com/nuxt/scripts/pull/632))
- `3b93696` fix(plausible): 损坏的 firstParty 模式
- `1c31a71` fix(gravatar): 损坏的代理