---
title: "核心概念"
description: "了解 Nuxt Scripts 的核心概念。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/key-concepts"
last_updated: "2026-08-11T09:33:10.033Z"
---

[`useScript()`](/docs/api/use-script) 是基础 API。注册表脚本和全局脚本基于它实现常见的加载模式：

1. [注册表脚本](/docs/guides/registry-scripts)：通过 Nuxt 配置、组合式函数和组件加载的预配置第三方脚本。
2. [全局脚本](/docs/guides/global)：通过 Nuxt 配置文件加载的脚本。

## Unhead 抽象层

Nuxt Scripts 封装了 Unhead 的 [`useScript()`](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-script)，而后者基于 [`useHead()`](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-head) 构建。因此，`useHead` 支持的脚本属性也可通过 Nuxt Scripts 使用。

## 脚本单例

Nuxt Scripts 会对具有相同 `src`（或 `key`）的调用进行去重，因为脚本是全局加载的，所有组件都会共享它们。

第一次调用会初始化脚本。之后具有相同标识的调用会返回该实例。

将重复调用封装在一个组合式函数中，这样每个组件都会使用相同的配置：

```ts [useMyScript.ts]
export function useMyScript() {
  return useScript({
    src: 'https://example.com/script.js',
  })
}
```

## 默认行为

默认情况下，Nuxt Scripts 会将脚本标签从 SSR 响应中排除，并通过 `onNuxtReady` 触发器在客户端加载脚本。这样可以避免第三方代码参与 hydration。

你可以通过修改 [defaultScriptOptions](/docs/api/nuxt-config#defaultscriptoptions) 来改变此行为。

Nuxt Scripts 还会为跨源脚本元素应用一些隐私和性能方面的默认设置：

- `crossorigin="anonymous"`：防止脚本请求发送跨源凭据，包括 Cookie。
- `referrerpolicy="no-referrer"`：防止与第三方服务器共享页面 URL。

启用 warmup 时，`<link>` 提示会使用 `fetchpriority="low"`，以避免与关键资源竞争。

> **注意：** 默认不使用 `async`，而是使用 `defer`。如果需要 `async`，你可以显式禁用 `defer`。

[`useScript()`](/docs/api/use-script) 可以在浏览器加载其脚本之前返回函数：

```ts
const { proxy } = useScript('/script.js', {
  use: () => ({ gtag: (window as any).gtag }),
})
proxy.gtag('event', 'page_view')
```

代理会将 `gtag` 调用加入队列，并在脚本加载完成后重放该调用。如果脚本始终未能加载，则该调用永远不会执行。

以下情况适用：

- 相同的代码会在 SSR 期间运行；
- 广告拦截器可能会阻止脚本加载；或者
- 应用可能会在请求完成前调用该 API。

代理调用有两个权衡：

- 代理调用会返回 `undefined`。当需要函数的返回值时，请使用 `load()` 或 `onLoaded()`。
- 加入队列的调用可能更难追踪，因为它会在脚本可用后延迟执行。

当需要直接使用脚本 API 时，请等待加载完成：

```ts
const { onLoaded } = useScript('/script.js', {
  use: () => ({ gtag: (window as any).gtag }),
})
// 直接使用脚本实例，而不是代理
onLoaded(({ gtag }) => {
  gtag('event', 'page_view')
})
```