---
title: "v0 到 v1"
description: "从 Nuxt Scripts v0.x 升级到 v1.0 的迁移指南。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/migration-guide/v0-to-v1"
last_updated: "2026-08-11T09:33:15.167Z"
---

使用本指南将 Nuxt Scripts v0 项目升级到 v1。[v1 发布说明](/docs/releases/v1)介绍了新增功能。

<callout color="blue" icon="i-heroicons-information-circle">

大多数被替换的 API 仍可继续使用，但会显示弃用警告。表格标出了需要更新代码的变更。

</callout>

## 总结

<table>
<thead>
  <tr>
    <th>
      变更
    </th>
    
    <th>
      状态
    </th>
    
    <th>
      处理方式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Registry 条目在没有 <code>
        trigger
      </code>
      
       的情况下自动加载
    </td>
    
    <td>
      构建警告
    </td>
    
    <td>
      添加 <code>
        trigger: 'onNuxtReady'
      </code>
      
       或 <code>
        trigger: false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [input, options]
      </code>
      
       元组形式
    </td>
    
    <td>
      仍然有效
    </td>
    
    <td>
      可选：切换为扁平配置
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        true
      </code>
      
       简写形式
    </td>
    
    <td>
      已弃用
    </td>
    
    <td>
      使用 <code>
        { trigger: 'onNuxtReady' }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      PayPal SDK v5 API
    </td>
    
    <td>
      已移除
    </td>
    
    <td>
      迁移到 v6（见下文）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptYouTubePlayer
      </code>
      
       的 <code>
        width
      </code>
      
      /<code>
        height
      </code>
    </td>
    
    <td>
      仍然有效
    </td>
    
    <td>
      可选：使用 <code>
        ratio
      </code>
      
       属性
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptYouTubePlayer
      </code>
      
       占位符 <code>
        object-fit: contain
      </code>
      
       默认值
    </td>
    
    <td>
      已更改为 <code>
        cover
      </code>
    </td>
    
    <td>
      设置 <code>
        placeholder-object-fit="contain"
      </code>
      
       以恢复原设置
    </td>
  </tr>
  
  <tr>
    <td>
      GTM <code>
        onBeforeGtmStart
      </code>
      
       的触发时机
    </td>
    
    <td>
      现在会对缓存的脚本触发
    </td>
    
    <td>
      使用 <code>
        if (initialized) return
      </code>
      
       进行保护
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMaps
      </code>
      
       的 <code>
        markers
      </code>
      
      /<code>
        centerMarker
      </code>
      
       属性
    </td>
    
    <td>
      已移除
    </td>
    
    <td>
      使用子元素 <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sx-uw">
          <
        </span>
        
        <span class="sFfpx">
          ScriptGoogleMapsMarker
        </span>
        
        <span class="sx-uw">
          >
        </span>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMaps
      </code>
      
       的 <code>
        placeholderOptions
      </code>
      
      /<code>
        placeholderAttrs
      </code>
      
      /<code>
        aboveTheFold
      </code>
      
       属性
    </td>
    
    <td>
      已移除
    </td>
    
    <td>
      在 <code>
        #placeholder
      </code>
      
       中使用 <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sx-uw">
          <
        </span>
        
        <span class="sFfpx">
          ScriptGoogleMapsStaticMap
        </span>
        
        <span class="sx-uw">
          >
        </span>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMaps
      </code>
      
       的 <code>
        :center
      </code>
      
      /<code>
        :zoom
      </code>
      
       属性
    </td>
    
    <td>
      已弃用
    </td>
    
    <td>
      使用 <code>
        :map-options="{ center, zoom }"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMaps
      </code>
      
       的 <code>
        googleMaps
      </code>
      
       ref 键
    </td>
    
    <td>
      已弃用
    </td>
    
    <td>
      使用 <code>
        mapsApi
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMapsAdvancedMarkerElement
      </code>
    </td>
    
    <td>
      已弃用
    </td>
    
    <td>
      使用 <code>
        ScriptGoogleMapsMarker
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ScriptGoogleMapsPinElement
      </code>
    </td>
    
    <td>
      已移除；仍保留插槽透传兼容层
    </td>
    
    <td>
      在 <code>
        ScriptGoogleMapsMarker
      </code>
      
       上使用 <code>
        #content
      </code>
      
       插槽
    </td>
  </tr>
  
  <tr>
    <td>
      类型模板
    </td>
    
    <td>
      已重新组织
    </td>
    
    <td>
      运行 <code>
        nuxi prepare
      </code>
    </td>
  </tr>
</tbody>
</table>

## 注册表配置

### 脚本在没有 `trigger` 的情况下不再自动加载

在 v0 中，任何已配置的注册表项都会通过 `defaultScriptOptions.trigger: 'onNuxtReady'` 全局自动加载。在 v1 中，存在配置只会注册基础设施（类型、打包、代理路由），但除非设置了 `trigger`，否则**不会**注入 `<script>` 标签。当你提供了配置值但没有提供 `trigger` 时，会出现构建警告。参见 [PR #661](https://github.com/nuxt/scripts/pull/661)。

```diff [nuxt.config.ts]
scripts: {
   registry: {
-    googleAnalytics: { id: 'G-XXXXXX' },
+    googleAnalytics: { id: 'G-XXXXXX', trigger: 'onNuxtReady' },
   }
 }
```

如果你是从 composable（`useScriptGoogleAnalytics()` 等）按需加载脚本，而不是全局加载，请显式设置 `trigger: false`。这样可以消除构建警告，并在不注入 `<script>` 标签的情况下保留代理路由、类型和打包配置。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      googleAnalytics: { id: 'G-XXXXXX', trigger: false }, // 由 composable 驱动
    }
  }
})
```

### 旧式简写（仍可使用）

`[input, options]` 元组形式、`true` 简写以及 `'mock'` 字符串形式都仍然可用。`true` 会发出弃用警告。

```diff [nuxt.config.ts]
scripts: {
   registry: {
-    googleAnalytics: true,
+    googleAnalytics: { trigger: 'onNuxtReady' },
-    plausibleAnalytics: [{ domain: 'mysite.com' }, { trigger: 'onNuxtReady' }],
+    plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
     cloudflareWebAnalytics: 'mock', // 未更改
   }
 }
```

## 重大变更

### PayPal SDK v6 ([#628](https://github.com/nuxt/scripts/pull/628))

PayPal v6 使用基于实例的初始化（`createInstance()`）、渲染前的资格检查以及基于会话的支付流程。请参阅 [PayPal 文档](/scripts/paypal) 了解新的组件 API。

- SDK URL 现在使用 v6 端点（`/web-sdk/v6/core`）
- `PayPalOptions` 精简为 `clientId`、`clientToken` 和 `sandbox`；请提供 `clientId` 或 `clientToken`（v6 在 `createInstance()` 时配置，而不是通过 URL 查询参数配置）
- 开发环境中的沙盒模式默认为 `true`
- 已移除 `ScriptPayPalMarks`；没有对应的 v6 API，请改用 `sdkInstance.findEligibleMethods()`
- `PayPalNamespace` 类型替换为 `PayPalV6Namespace`

`<ScriptPayPalButtons>` 不再直接渲染按钮。现在它通过 `#default` 作用域插槽暴露 v6 SDK 实例：

```diff
-<ScriptPayPalButtons
-  :client-id="clientId"
-  @paypal-payment-success="onSuccess"
-/>
+<ScriptPayPalButtons :client-id="clientId" :components="['paypal-payments']">
+  <template #default="{ sdkInstance }">
+    <button @click="pay(sdkInstance)">使用 PayPal 支付</button>
+  </template>
+</ScriptPayPalButtons>
```

支付流程改为使用会话而不是按钮回调：

```ts
const eligibility = await sdkInstance.findEligibleMethods()
if (eligibility.isEligible('paypal')) {
  const session = sdkInstance.createPayPalOneTimePaymentSession({
    onApprove: async (data) => { /* 捕获订单 */ },
  })
  await session.start({ presentationMode: 'auto' }, createOrderPromise)
}
```

```diff
-import type { PayPalNamespace } from '@paypal/paypal-js'
+import type { PayPalV6Namespace, SdkInstance } from '@paypal/paypal-js/sdk-v6'
```

### YouTube 播放器 ([#563](https://github.com/nuxt/scripts/pull/563), [#586](https://github.com/nuxt/scripts/pull/586))

#### 宽高比

使用 `ratio` 属性，而不是通过 `width`/`height` 推导宽高比。`width` 和 `height` 属性仍会用于 iframe 尺寸，但不再驱动外层容器的宽高比。

```diff
<ScriptYouTubePlayer
   video-id="..."
-  :width="1280"
-  :height="720"
+  ratio="16/9"
 />
```

默认为 `16/9`。

#### 占位图片

默认的 `object-fit` 已从 `contain` 改为 `cover`。要恢复 v0 行为：

```vue
<ScriptYouTubePlayer video-id="..." placeholder-object-fit="contain" />
```

#### 多个播放器

播放器实例不再共享状态。请移除页面上用于多个播放器的任何 v0 变通方案。

### Google Tag Manager ([#584](https://github.com/nuxt/scripts/pull/584))

#### `onBeforeGtmStart` 回调

v1 也会为缓存或预初始化的脚本调用此钩子。请防止重复初始化：

```diff
+let initialized = false
 useScriptGoogleTagManager({
   onBeforeGtmStart: (gtag) => {
+    if (initialized) return
+    initialized = true
     // 你的初始化代码
   }
 })
```

### Google Maps ([实现提交](https://github.com/nuxt/scripts/commit/d381c9a2))

v1 统一了 Google Maps 标记组件，移除了旧的 `google.maps.Marker` API，并将静态占位图提取为独立组件。

#### `ScriptGoogleMapsAdvancedMarkerElement` → `ScriptGoogleMapsMarker`（已弃用）

旧组件仍作为轻量兼容层保留，并会发出开发环境警告。

```diff
-<ScriptGoogleMapsAdvancedMarkerElement :position="{ lat: 0, lng: 0 }" />
+<ScriptGoogleMapsMarker :position="{ lat: 0, lng: 0 }" />
```

#### 已移除 `ScriptGoogleMapsPinElement`（保留兼容层）

旧组件现在只渲染其默认插槽，并会发出开发环境警告；其 `options` 属性不再创建 Google Maps 图钉。请将标记内容移入 `<ScriptGoogleMapsMarker>` 的 `#content` 插槽：

```diff
-<ScriptGoogleMapsAdvancedMarkerElement :position="pos">
-  <ScriptGoogleMapsPinElement :options="{ background: 'red' }" />
-</ScriptGoogleMapsAdvancedMarkerElement>
+<ScriptGoogleMapsMarker :position="pos">
+  <template #content>
+    <div class="custom-pin" style="background: red;">📍</div>
+  </template>
+</ScriptGoogleMapsMarker>
```

#### 已移除 `markers` 和 `centerMarker` 属性

改为使用子级 `<ScriptGoogleMapsMarker>` 组件：

```diff
-<ScriptGoogleMaps
-  :center="center"
-  :markers="[{ position: { lat: 0, lng: 0 } }]"
-  center-marker
-/>
+<ScriptGoogleMaps :map-options="{ center, zoom: 12 }">
+  <ScriptGoogleMapsMarker :position="center" />
+  <ScriptGoogleMapsMarker :position="{ lat: 0, lng: 0 }" />
+</ScriptGoogleMaps>
```

#### 已移除静态占位图属性 ([#673](https://github.com/nuxt/scripts/pull/673))

v1 从 `<ScriptGoogleMaps>` 中移除了 `placeholderOptions`、`placeholderAttrs` 和 `aboveTheFold` 属性。请将独立的 `<ScriptGoogleMapsStaticMap>` 组件放入 `#placeholder` 插槽中。该插槽默认为空，不再接收 `placeholder` URL。

```diff
-<ScriptGoogleMaps
-  :center="center"
-  :zoom="7"
-  above-the-fold
-  :placeholder-options="{ maptype: 'satellite' }"
-  :placeholder-attrs="{ class: 'rounded' }"
-/>
+<ScriptGoogleMaps :map-options="{ center, zoom: 7 }">
+  <template #placeholder>
+    <ScriptGoogleMapsStaticMap
+      :center="center"
+      :zoom="7"
+      loading="eager"
+      maptype="satellite"
+      :img-attrs="{ class: 'rounded' }"
+    />
+  </template>
+</ScriptGoogleMaps>
```

#### 顶层 `:center` / `:zoom` 已弃用 ([#694](https://github.com/nuxt/scripts/pull/694))

建议改为通过 `:map-options` 传递这些属性。两种 API 仍然可用；旧版形式会在开发模式下发出警告。如果两者同时设置，则以 `mapOptions` 为准。

```diff
-<ScriptGoogleMaps :center="{ lat, lng }" :zoom="12" />
+<ScriptGoogleMaps :map-options="{ center: { lat, lng }, zoom: 12 }" />
```

#### 模板 ref `googleMaps` → `mapsApi` ([#695](https://github.com/nuxt/scripts/pull/695))

`mapsApi` 保存 `google.maps` API 命名空间。旧的 `googleMaps` 键仍作为已弃用的别名保留，并会在第一次读取时发出开发环境警告。

```diff
const mapRef = ref()
 onMounted(() => {
-  console.log(mapRef.value?.googleMaps)
+  console.log(mapRef.value?.mapsApi)
 })
```

同样的更名也适用于 `<ScriptGoogleMapsOverlayView>`：其暴露的 `overlay` 键现在是 `overlayView`，同时保留 `overlay` 作为已弃用别名。

```diff
const overlayRef = ref()
 onMounted(() => {
-  console.log(overlayRef.value?.overlay)
+  console.log(overlayRef.value?.overlayView)
 })
```

### 类型扩展 ([#589](https://github.com/nuxt/scripts/pull/589))

v1 重新组织了生成的类型模板。升级后请运行 `nuxi prepare`：

```bash
npx nuxi prepare
```