---
title: "全局脚本"
description: "配置带有触发器、预热、类型化访问和运行时 URL 覆盖的全局脚本。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/global"
last_updated: "2026-08-11T09:33:10.273Z"
---

## 背景

Nuxt 的 `app.head` 可以加载全局脚本：

```ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [{ src: 'https://analytics.com/tracker.js', async: true }]
    }
  }
})
```

`scripts.globals` 会通过 Nuxt Scripts 加载同一个脚本，包括其触发器和预热行为。

在以下情况下使用全局脚本：

- 该脚本不是受支持的[注册表脚本](/docs/guides/registry-scripts)。
- 你不会调用第三方 API，例如 `gtag`。
- 你会调用 API，但不需要为其添加类型。

当你需要类型化 API 时，请使用注册表组合式函数或 [`useScript()`](/docs/api/use-script)。

## 用法

`globals` 键支持字符串、对象和双项元组。

### URL 字符串

```ts
export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: 'https://analytics.com/tracker.js',
    }
  }
})
```

### 脚本属性

```ts
export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: {
        src: 'https://example.com/script.js',
        integrity: 'sha256-abc123',
      }
    }
  }
})
```

### 脚本选项

使用双项元组以包含[脚本选项](/docs/api/use-script#nuxtusescriptoptions)：

```ts
export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: [
        { src: 'https://example.com/script.js' },
        // 将脚本作为 hydration 过程的一部分加载，而非在空闲时加载
        { trigger: 'client' }
      ]
    }
  }
})
```

将 `trigger` 保留在元组的第二项中。如果将其放在输入对象中与 `src` 并列，当前生成的插件会将其作为脚本输入传递，而不是作为 `useScript` 选项传递，因此该全局脚本仍会继承模块的默认触发器。

### 按部署覆盖脚本

通过 [Nuxt 的公共运行时配置](https://nuxt.com/docs/guide/going-further/runtime-config)和 `NUXT_PUBLIC_SCRIPTS_GLOBALS_*` 环境变量覆盖全局脚本。这样，同一个构建版本就可以在不同部署中使用不同的 Trusted Shops、Awin 或 GTM 值。

环境变量路径会映射为 `SCREAMING_SNAKE_CASE` 形式的全局键（camelCase 边界会变为下划线）：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    globals: {
      trustedShops: {
        src: 'https://widgets.trustedshops.com/build-default.js',
      },
    },
  },
})
```

```bash [.env per deployment]
# 仅为此部署覆盖 src：
NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC=https://widgets.trustedshops.com/X1234.js
```

可以通过这种方式覆盖 `src`、`integrity`、`crossorigin` 和 `referrerpolicy` 等对象字段。环境变量值会在运行时通过 `runtimeConfig.public.scriptsGlobals` 替换构建时的默认值。

#### 按部署禁用全局脚本

部署也可以在不重新构建的情况下跳过某个全局脚本。在环境变量中使用空的 `src`。运行时钩子或类型化的运行时配置值也可以将 `enabled` 设置为布尔值 `false`：

```bash [.env per deployment]
# 仅为此实例移除此集成：
NUXT_PUBLIC_SCRIPTS_GLOBALS_AWIN_SRC=
```

被禁用的全局脚本在 `$scripts` 上会解析为 `undefined`，因此如果某个脚本可能按实例关闭，请进行保护性访问（`$scripts.awin?.`）。

#### 在运行时计算全局脚本

当 `src` 依赖运行时配置，或部署需要有条件地移除某个条目时，请使用 [`scripts:globals`](/docs/api/nuxt-app-hooks#scriptsglobals) 运行时钩子。该钩子会在注册前立即接收解析后的输入。可以在此处重写或删除已声明的条目；它们的 `$scripts` 类型仍然可用。

**运行时不可覆盖：**

- `scriptOptions`（双项元组的第二个位置，例如 `trigger` 或 `warmupStrategy`）会在构建时固化。
- 资源打包：由于资源打包转换器无法通过运行时配置包装器静态读取 `src`，因此会跳过可通过环境变量覆盖的全局脚本。它们会在运行时直接从 CDN 加载。如果需要打包，请改用具有静态 `src` 的 `useScript()`。

环境变量键中的拼写错误会产生带有建议的警告。例如，`NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOP_SRC` 会建议使用 `trustedShops`。

### 访问全局脚本

Nuxt Scripts 会将全局脚本注册到 Nuxt 应用的类型化 `$scripts` 属性上：

```vue
<script setup lang="ts">
const { $scripts } = useNuxtApp()
$scripts.myScript // UseScriptContext<any> | undefined
</script>
```

## 生成的插件

该模块会将 `scripts.globals` 转换为虚拟 Nuxt 插件。该插件会调用 [`useScript()`](/docs/api/use-script)，因此全局脚本会共享其默认配置和单例行为。

<code-group>

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    globals: {
      tracker: 'https://analytics.com/tracker.js',
    }
  }
})
```

```vue [components/Tracking.vue]
<script setup lang="ts">
// 由于 nuxt.config 中的全局脚本，这不会再次触发脚本加载
const { proxy, onLoaded } = useNuxtApp().$scripts.tracker!

onLoaded(() => {
  console.log('脚本已加载')
})

function trackCustom() {
  proxy.track('custom_event')
}
</script>

<template>
  <button @click="trackCustom">
    追踪自定义事件
  </button>
</template>
```

:::

</code-group>