---
title: "脚本触发器"
description: "控制 Nuxt Scripts 何时开始加载脚本。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/script-triggers"
last_updated: "2026-08-11T09:33:09.872Z"
---

<callout icon="i-heroicons-play" target="_blank" to="https://stackblitz.com/github/nuxt/scripts/tree/main/examples/performance">

在 StackBlitz 上试用实时的[性能示例](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/performance)，体验触发器的实际效果。

</callout>

`trigger` 选项控制脚本何时开始加载。

## 触发器的工作原理

将受支持的触发器源作为 `trigger` 传入：当响应式源变为真值，或 Promise 解析为 `undefined` 或真值时，脚本会加载。解析为 `false` 的 Promise 不会加载脚本。

```ts
const shouldLoad = ref(false)

useScript('https://example.com/script.js', {
  trigger: shouldLoad
})

// 后续：触发加载
shouldLoad.value = true
```

它支持 refs、计算属性 refs、getter 函数和 Promise：

```ts
// Ref
trigger: shouldLoad

// 计算属性
trigger: computed(() => !!route.query.affiliateId)

// Getter 函数
trigger: () => shouldLoad.value

// Promise
trigger: new Promise(resolve => setTimeout(resolve, 3000))
```

## 默认值：onNuxtReady

默认情况下，脚本使用 [`onNuxtReady`](https://nuxt.com/docs/api/utils/on-nuxt-ready) 触发器。Nuxt 会等待水合完成，然后通过 `requestIdleCallback` 或较短的计时器回退机制安排加载。

```ts
// 显式写出默认值
useScript('https://widget.intercom.io/widget/abc123', {
  trigger: 'onNuxtReady'
})

// 注册表组合式函数默认继承 onNuxtReady
useScriptGoogleAnalytics({
  id: 'GA_MEASUREMENT_ID',
  // 默认使用 trigger: 'onNuxtReady'
})
```

除非某个集成定义了更早的触发器，否则注册表组合式函数会继承此默认值。在 `nuxt.config` 中的注册表条目仍需要显式设置 `trigger` 才能创建全局实例；不设置该值的条目只会启用其类型、打包、代理路由和其他基础设施。

<callout color="amber">

`partytown: true` 是一个例外。当前的 Partytown 路径会在 SSR 期间插入脚本，并将其报告为已加载，因此不会等待 `trigger`。注册表条目仍需要一个真值 `trigger` 才能生成全局实例，但触发器的值不会控制该 Partytown 脚本的运行时间。

</callout>

你可以通过修改 [defaultScriptOptions](/docs/api/nuxt-config#defaultscriptoptions) 来更改此默认值。

## 专用触发器

### 空闲超时

[`useScriptTriggerIdleTimeout()`](/docs/api/use-script-trigger-idle-timeout) 会在 Nuxt 准备就绪后启动计时器：

<code-group>

```ts [Composable]
useScript('https://example.com/analytics.js', {
  trigger: useScriptTriggerIdleTimeout({ timeout: 5000 })
})
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      googleAnalytics: {
        id: 'GA_MEASUREMENT_ID',
        trigger: { idleTimeout: 3000 },
      }
    }
  }
})
```

</code-group>

### 用户交互

[`useScriptTriggerInteraction()`](/docs/api/use-script-trigger-interaction) 会在首次发生配置的交互时加载：

<code-group>

```ts [Composable]
useScript('https://example.com/chat-widget.js', {
  trigger: useScriptTriggerInteraction({
    events: ['scroll', 'click', 'keydown']
  })
})
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    globals: {
      chatWidget: ['https://widget.example.com/chat.js', {
        trigger: { interaction: ['scroll', 'click', 'touchstart'] }
      }]
    }
  }
})
```

</code-group>

### 元素事件触发器

[`useScriptTriggerElement()`](/docs/api/use-script-trigger-element) 会监听一个元素的可见性或事件：

```ts
const buttonEl = ref<HTMLElement>()

useScript('https://example.com/feature.js', {
  trigger: useScriptTriggerElement({
    trigger: 'visible', // 或 'mouseover'、'click' 等
    el: buttonEl,
  })
})
```

## 基础触发器

### 手动控制

当你的代码应直接调用 `load()` 时，使用 `manual` 触发器：

```ts
const { load } = useScript('https://example.com/script.js', {
  trigger: 'manual'
})

// 你决定何时加载
await load()
```