---
title: "v1.0.0"
description: "Nuxt Scripts v1 增加了官方代理、Partytown Worker、服务器渲染的社交媒体嵌入、SRI 哈希和注册表脚本。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/releases/v1"
last_updated: "2026-08-11T09:33:05.555Z"
---

Nuxt Scripts v1 是该项目的首个稳定版本。它增加了官方代理、单脚本 Partytown 支持、服务器渲染的社交媒体嵌入、同意 API 以及新的注册表集成。

## 亮点

### 第一方模式

加载第三方脚本会向其提供商提供浏览器数据，这些数据可用于[浏览器指纹识别](https://developer.mozilla.org/en-US/docs/Glossary/Fingerprinting)。

数据量因提供商而异。[Nuxt Scripts 审计快照](https://github.com/nuxt/scripts/blob/main/packages/script/src/script-sizes.json)记录了 5 个 X Pixel Cookie 和向 3 个域名发出的请求，以及电池状态、CPU 数量、屏幕信息、时区、语言、平台和触控能力等浏览器信号。它还记录了跨 3 个域名的 Clarity 流量。

第一方模式会在构建时打包受支持的脚本，并从你的域名提供这些脚本。其反向代理会通过你的服务器转发受支持的运行时请求，并对 IP 地址（`180.233.124.74` → `180.233.124.0`）和浏览器版本（`Mozilla/5.0 (compatible; Chrome/120.0)`）等字段进行匿名化。注册表脚本在声明支持这些功能后，默认使用这些能力。

从你的源站提供已打包的脚本，可以避免连接原始脚本主机时的 DNS 和连接建立过程。同源代理 URL 也不太可能匹配基于主机的拦截规则，但其他拦截规则仍可能识别出这些请求。第一方模式不会免除同意要求，也不会免除法律规定必须展示同意横幅时的相关义务。

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

### Partytown Web Worker 支持

设置 `partytown: true`，即可在 [Partytown](https://partytown.qwik.dev/) Web Worker 中运行受支持的注册表脚本。其第一方打包和代理功能仍然适用。详见 [PR #576](https://github.com/nuxt/scripts/pull/576)。

[当前的 Partytown 快速路径](https://github.com/nuxt/scripts/blob/main/packages/script/src/runtime/composables/useScript.ts)会将脚本渲染到初始 HTML 中，并返回一个已加载的存根。它会绕过触发器解析、`use()` 代理、`load()` 和 `reload()`。在下面的配置中，`trigger` 会启用每个全局注册表实例的生成，但 `onNuxtReady` 不会延迟 Partytown 脚本。

Nuxt Scripts 为 `googleAnalytics`、`plausibleAnalytics`、`cloudflareWebAnalytics`、`umamiAnalytics`、`matomoAnalytics`、`segment`、`mixpanelAnalytics`、`clarity`、`bingUet`、`metaPixel`、`xPixel`、`tiktokPixel`、`snapchatPixel`、`redditPixel`、`linkedinInsight` 和 `calendly` 配置了转发。

不要假设仅凭转发就能让每个注册表集成在当前快速路径上正常使用。例如，Plausible 和 Umami 需要该路径会丢弃的属性，而 Clarity 依赖一个永远不会运行的客户端初始化回调。

<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>

### 服务端渲染的社交媒体嵌入

Twitter 小组件、Instagram 嵌入内容和 Bluesky 帖子通常会在浏览器中加载供应商脚本。遵循 [Cloudflare Zaraz 的实现方式](https://blog.cloudflare.com/zaraz-supports-server-side-rendering-of-embeds/)，Nuxt Scripts 可以在服务器上获取嵌入数据，并通过你的域名重写受支持的媒体 URL。详见 [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="{ displayName, text, images }">
    <article>
      <strong>{{ displayName }}</strong>
      <p>{{ text }}</p>
      <img v-for="image in images" :key="image.fullsize" :src="image.thumb" :alt="image.alt">
    </article>
  </template>
</ScriptBlueskyEmbed>
```

### 同意控制

v1 新增了两层同意控制。详见[同意指南](/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)。

**同意触发器：**[`useScriptTriggerConsent()`](/docs/api/use-script-trigger-consent) 会阻止脚本加载，直到获得同意。其响应式状态会记录之后的撤销操作，但撤销同意不会卸载脚本：

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

trigger.accept() // 授予同意 → 脚本加载
trigger.revoke() // 将 consented 设置为 false；不会卸载已经加载的脚本
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 的隐私和功能模型（[实现提交](https://github.com/nuxt/scripts/commit/1c2855fa)）：

- **第一方面板：**代理路由、启用的匿名化标志和上游域名。
- **注册表面板：**`bundle`、`proxy` 和 `partytown` 的支持状态与激活状态。
- **脚本检查：**状态、加载时间、网络瀑布流、打包大小和内联文档。
- **独立视图：**连接到 Nuxt 开发服务器的独立 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)): 带有隐私保护代理的头像服务。

## 其他变更

### 脚本重新加载 API

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

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

### 子资源完整性哈希

设置 `assets.integrity` 以为打包脚本生成[子资源完整性](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity)哈希。参见 [PR #575](https://github.com/nuxt/scripts/pull/575)。

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

### 脚本统计导出

新的 `@nuxt/scripts/stats` 子路径会导出脚本隐私和性能数据，供审计使用；[源代码列出了其测量字段和评级输入](https://github.com/nuxt/scripts/blob/main/packages/script/src/stats.ts)。

```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 地图集成现在为标记、形状、覆盖层、聚合、静态地图和 GeoJSON 提供 Vue 组件。

**声明式组件** ([#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 属性：** 标记组件无需选项对象即可接受 `:position`。

**其他组件：**

- [**ScriptGoogleMapsStaticMap**](/scripts/google-maps/api/static-map) ([#673](https://github.com/nuxt/scripts/pull/673))：静态占位图现在是一个独立组件。默认情况下，图片会通过你的服务器转发，由服务器将 API 密钥注入上游请求。Google 当前的条款限制从应用服务器存储和提供 Static Maps 图片；[计费指南](/scripts/google-maps/guides/billing)说明了如何通过显式设置 `api-key` 绕过此代理。
- [**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 密钥并缓存结果。使用前请在[计费指南](/scripts/google-maps/guides/billing)中查看当前的缓存限制。
- **资源清理** ([#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` 以避免重复渲染

**弃用：** v1 将旧版 `ScriptGoogleMapsMarker`（封装 `google.maps.Marker`）和 `ScriptGoogleMapsAdvancedMarkerElement` 的名称统一为 `ScriptGoogleMapsMarker`（封装 `google.maps.marker.AdvancedMarkerElement`）。v1 移除 `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)，其中包含每个破坏性变更和弃用的汇总表以及变更前后的差异。

## 修复问题

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