---
title: "v1 到 v2"
description: "从 Nuxt Scripts v1.x 升级到 v2.0 的迁移指南。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/migration-guide/v1-to-v2"
last_updated: "2026-09-23T10:33:09.622Z"
---

Nuxt Scripts 2 将脚本所有权和 SDK 就绪状态交由 Unhead 3.3.1 中引入的生命周期 API 管理。当组件使用者卸载时，这些 API 会移除组件回调和触发器监听器，同时不会拆除仍被其他组件使用的脚本。

## 要求

| 依赖                            | 要求版本                          |
| ----------------------------- | ----------------------------- |
| [Node.js](https://nodejs.org) | `>=24`                        |
| Nuxt                          | `>=4.5.1`，包括 Nuxt 5 和 Nitro 3 |
| `@unhead/vue`                 | `>=3.3.1 <4`                  |
| `unhead`                      | `>=3.3.1 <4`                  |

在安装 v2 之前升级 Nuxt 并刷新其锁定的依赖：

```bash
npx nuxi@latest upgrade --force
```

从项目根目录运行专用迁移 CLI。如果项目包含动态 Nuxt 配置，
请先预览其变更：

```bash
npx @nuxt/scripts-cli migrate v2 --dry-run
npx @nuxt/scripts-cli migrate v2
```

该 CLI 会处理静态注册表配置和机械式 API 重命名。
它会列出需要手动后续处理的动态配置和已移除组件。

现在，如果任一 Unhead 包缺失或版本超出支持范围，模块会显示可执行的错误信息并停止设置。

## 注册表配置

注册表条目现在接受扁平对象、`'mock'` 或 `false`。Nuxt Scripts 2
移除了已弃用的 `true`、`'proxy-only'`、元组、嵌套的
`scriptOptions` 以及 `reverseProxyIntercept` 形式。

```diff
scripts: {
   registry: {
-    googleAnalytics: true,
-    plausibleAnalytics: [{ scriptId: 'YOUR_SCRIPT_ID' }, { proxy: false }],
-    calendly: { scriptOptions: { bundle: false } },
-    posthog: { reverseProxyIntercept: false },
+    googleAnalytics: { trigger: 'onNuxtReady' },
+    plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', proxy: false },
+    calendly: { bundle: false },
+    posthog: { proxy: false },
   },
 }
```

Nuxt Scripts 2 还移除了已弃用的顶层 `globals` 数组。请使用
键控对象，以便每个脚本都有一个稳定的名称。

## Google 地图

Nuxt Scripts 2 移除了以下 v1 兼容别名和组件：

| 已移除                                                          | 替代方案                                    |
| ------------------------------------------------------------ | --------------------------------------- |
| `<ScriptGoogleMaps>`{lang="html"} 上的 `center` 和 `zoom` props | `mapOptions.center` 和 `mapOptions.zoom` |
| `googleMaps` 模板 ref 键                                        | `mapsApi`                               |
| `overlay` 模板 ref 键                                           | `overlayView`                           |
| `<ScriptGoogleMapsAdvancedMarkerElement>`{lang="html"}       | `<ScriptGoogleMapsMarker>`{lang="html"} |
| `<ScriptGoogleMapsPinElement>`{lang="html"}                  | marker 的 `#content` 插槽                  |
| `<ScriptGoogleMapsHeatmapLayer>`{lang="html"}                | 使用 [deck.gl](http://deck.gl) 等受维护的热力图库  |

Google 已从 Maps JavaScript API v3.65 中移除 `HeatmapLayer`，因此 Nuxt Scripts
不再提供依赖它的组件。

Nuxt Scripts 2 移除了旧版 `googleStaticMapsProxy` 选项和需要计费的 Google 地图服务器代理。静态地图会使用公开的浏览器密钥直接从 Google 加载。`resolveQueryToLatLng()`{lang="ts"} 使用客户端 Places 服务。为该密钥应用网站和 API 限制，然后配置配额限制。

## 注册表 API

Nuxt Scripts 2 移除了以下已弃用的注册表 API 形式：

| 已移除                                  | 替代方案                              |
| ------------------------------------ | --------------------------------- |
| `proxy.rybbit.pageview()`{lang="ts"} | `proxy.pageview()`{lang="ts"}     |
| `proxy.ttq('page')`{lang="ts"}       | `proxy.ttq.page()`{lang="ts"}     |
| `proxy.ttq('track', ...)`{lang="ts"} | `proxy.ttq.track(...)`{lang="ts"} |
| Matomo `trackPageView` 选项            | `watch`，默认为 `true`                |
| Plausible `domain` 和 `extension` 选项  | `scriptId` 和当前的初始化选项              |

## 消费者作用域

每次 `useScript()`{lang="ts"} 调用现在都会返回一个 Unhead 消费者作用域。
组件卸载时会自动释放由该调用拥有的回调和触发器监听器。

- `dispose()`{lang="ts"} 仅释放当前消费者。
- 当你释放该消费者，或任何调用方移除共享脚本时，`signal` 会中止。
- `script` 指向共享脚本实例。
- `remove()`{lang="ts"} 仍会为所有消费者移除共享脚本。

如果应用代码使用 `remove()`{lang="ts"} 作为组件清理操作，请将其改为
`dispose()`{lang="ts"}。在 Vue 组件中，通常不再需要手动清理。

## 自定义就绪回调

`use` 选项仍受支持。基于回调的 SDK 应迁移到
`resolve({ waitFor })`{lang="ts"}，它会自动移除监听器，并在脚本生命周期结束时拒绝待处理的就绪请求。

```diff
const script = useScript('https://example.com/sdk.js', {
-  use: () => readyPromise.then(() => window.example),
+  resolve: ({ waitFor }) => waitFor((resolve) => {
+    window.onExampleReady = () => resolve(window.example)
+    return () => delete window.onExampleReady
+  }),
 })
```

现已将内置的 Google Maps、YouTube Player、Crisp 和 Usercentrics 集成改为使用此 API。`load()`{lang="ts"} 仅会在每个供应商的具体 SDK API 就绪后才完成解析。

## 脚本触发器

Nuxt 的空闲超时、交互和服务工作线程辅助函数现在会返回 Unhead 触发函数。现有的 `scriptOptions.trigger` 用法保持不变。自定义触发函数可以返回一个清理回调；当使用方作用域被销毁时，Unhead 会调用该回调。

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.