---
title: "Nuxt 配置"
description: "配置注册表脚本、默认值、代理、隐私和捆绑资源。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/api/nuxt-config"
last_updated: "2026-08-11T09:33:17.116Z"
---

## `registry`

- 类型：`NuxtConfigScriptRegistry`

注册脚本以准备其代理路由、类型、捆绑资源和组合式函数自动导入。只有包含 `trigger` 的条目才会全局加载。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      // 仅基础设施（组合式函数驱动）
      googleAnalytics: { id: 'G-XXXXXX' },
      // 基础设施 + 全局自动加载
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', trigger: 'onNuxtReady' },
      // 不使用代理
      posthog: { apiKey: 'phc_xxx', proxy: false },
      // 测试存根（不加载脚本，跳过验证）
      clarity: 'mock',
      // 禁用脚本
      hotjar: false,
    }
  }
})
```

每个脚本的功能标志（`trigger`、`proxy`、`bundle`、`partytown`、`privacy`）都可以在配置对象的顶层，与脚本的输入字段并列设置。对于代理支持依赖于重写捆绑 SDK 的脚本，`bundle: false` 也会阻止采集请求使用代理。PostHog 是例外：其 [`posthog-js` 包](https://posthog.com/docs/libraries/js#option-2-install-via-package-manager)通过 `apiHost` 接收代理端点，因此不依赖捆绑。

请浏览[脚本注册表](/scripts)，查看每种集成的输入和功能。

### 环境变量

该模块会为每个集成注册其声明的环境变量字段，例如分析 ID、令牌或 API 密钥。无需声明匹配的 `runtimeConfig` 键，即可使用 `NUXT_PUBLIC_SCRIPTS_<SCRIPT>_<FIELD>` 环境变量覆盖这些字段：

```bash [.env]
NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID=G-XXXXXX
NUXT_PUBLIC_SCRIPTS_POSTHOG_API_KEY=phc_xxx
NUXT_PUBLIC_SCRIPTS_CRISP_ID=your-crisp-id
```

脚本仍必须存在于 `scripts.registry` 中。集成未声明用于环境变量的字段仍应属于注册表配置。这些值会通过公共运行时配置暴露，因此不要将此机制用于仅限服务器端的密钥。

## `prefix`

- 类型：`string`
- 默认值：`'/_scripts'`

所有脚本端点的基础路径前缀。代理端点在 `<prefix>/p/**` 处提供，打包资源在 `<prefix>/assets/**` 处提供。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    prefix: '/_tracking', // 自定义前缀（默认：'/_scripts'）
  }
})
```

## `privacy`

- 类型：`ProxyPrivacyInput` (`boolean | ProxyPrivacy`)
- 默认值：`undefined`（每个脚本的默认值）

适用于所有代理脚本的全局隐私覆盖设置。默认情况下，每个脚本使用其在注册表中声明的隐私层级。布尔值会替换每个脚本的默认值。对象只会修改其中指定的标志，并保留每个脚本的其余标志。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    // 对所有代理流量进行完全匿名化
    privacy: true,

    // 或按标志选择性覆盖
    privacy: { ip: true },

    // 直通（仍然剥离敏感的认证头）
    privacy: false,
  }
})
```

有关隐私层级和每个脚本覆盖的详细信息，请参阅 [第一方模式指南](/docs/guides/first-party)。

## `proxy.alias`

- 类型：`boolean | Record<string, string>`
- 默认值：`false`

将第一方代理路径中的真实主机名替换为生成的别名或显式指定的别名。`true` 会为每个代理域名生成一个不透明别名。对象会将每个域名映射到其路径片段；未列出的域名保持不变。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    proxy: {
      alias: {
        'us.i.posthog.com': 'ph',
      }
    }
  }
})
```

## Partytown（Web Worker） <badge color="amber">实验性</badge>

使用 [Partytown](https://partytown.qwik.dev/) 在 Web Worker 中加载单个脚本。仍然需要注册表 `trigger` 来生成全局调用，但它不会延迟 Partytown 标签：当前实现会将该标签写入服务端渲染的 HTML 中。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
  scripts: {
    registry: {
      plausibleAnalytics: { scriptId: 'YOUR_SCRIPT_ID', partytown: true, trigger: 'onNuxtReady' },
    }
  }
})
```

<callout color="amber" icon="i-heroicons-exclamation-triangle">

你必须安装 [`@nuxtjs/partytown`](https://github.com/nuxt-modules/partytown)。Nuxt 会为支持的脚本自动配置 `forward` 数组。

</callout>

### 支持的脚本

Nuxt 会为以下脚本配置 Partytown 转发：

- `googleAnalytics`、`plausibleAnalytics`、`cloudflareWebAnalytics`、`umamiAnalytics`、`matomoAnalytics`、`mixpanelAnalytics`、`segment`、`clarity`
- `metaPixel`、`xPixel`、`tiktokPixel`、`snapchatPixel`、`redditPixel`、`linkedinInsight`、`bingUet`
- `calendly`

### 限制

<callout color="red" icon="i-heroicons-x-circle">

Partytown 仅适用于明确声明了 `partytown` 能力的注册表脚本。对任何其他注册表脚本设置 `partytown: true` 都会被忽略，并在开发环境中发出警告。上面的列表说明了哪些脚本符合转发条件，并不保证它们与当前的快速路径完全兼容。

</callout>

<callout color="amber" icon="i-heroicons-exclamation-triangle">

**一般限制**：

- Partytown 路径仅保留 `src`；会丢弃其他脚本属性，跳过注册表中的 `clientInit`/`beforeInit`，忽略触发时机，并且不会返回可调用的代理。转发列表中的多个集成依赖这些被省略的属性或初始化钩子，因此在部署前请测试生成的标签和供应商流量。
- `segment`、`mixpanelAnalytics` 和 `bingUet` 支持 Partytown 转发，但不具备收集代理能力。如果另一个已配置的集成启用了第一方代理，Nuxt 会安装一个全局 `resolveUrl`，将每个外部 Worker 请求都通过代理路由。随后，向代理允许列表之外的域名发出的请求会收到 `403`。请避免这种混合配置，或提供自定义的 Partytown `resolveUrl`，让这些主机直接访问。
- 与在主线程上运行相比，Worker 执行可能会改变时序
- 应用代码对转发全局对象发起的调用必须列在 Partytown 的 [`forward` 配置](https://partytown.qwik.dev/forwarding-events/) 中
- 如果你提供了自定义的 Partytown `resolveUrl`，请自行添加 Nuxt Scripts 的代理路由规则

</callout>

## `defaultScriptOptions`

- 类型：`NuxtUseScriptOptions`
- 默认值：`{ trigger: 'onNuxtReady' }`

每个脚本继承的默认值。[`useScript()` 参考](/docs/api/use-script)列出了可用选项。

## `globals`

- 类型：`Record<string, NuxtUseScriptInput | [NuxtUseScriptInput, NuxtUseScriptOptionsSerializable]>`
- 默认值：`{}`

通过 [`useScript()`](/docs/api/use-script) 在每个页面上注册的脚本。

[全局配置指南](/docs/guides/global)介绍了元组、环境覆盖以及 `$scripts` 的访问方式。

## `defaultScriptOptions.warmupStrategy`

- 类型：`false | 'preload' | 'preconnect' | 'dns-prefetch'`
- 默认值：对于带有 `onNuxtReady` 或 `client` 触发器的脚本为 `'preload'`；其他情况下不自动预热

控制浏览器在脚本加载前如何预热与脚本源的连接。MDN 的[推测性加载指南](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Speculative_loading)比较了每种资源提示的开销和预期用途：

- `'preload'` 插入一个 `<link rel="preload">` 标签，并下载即将加载的脚本。
- `'preconnect'` 为稍后加载的脚本完成 DNS、TCP 和 TLS 设置。
- `'dns-prefetch'` 仅解析 DNS，不下载脚本。
- `false` 完全禁用预热。当你将脚本打包并从自己的域名提供时使用。

<callout type="info">

当 [第一方模式](/docs/guides/first-party) 打包脚本时，`preconnect` 和 `dns-prefetch` 会自动回退到 `false`，因为你的源已经提供脚本。

</callout>

## `enabled`

- 类型：`boolean`
- 默认值：`true`

设置为 `false` 以禁用 Nuxt Scripts 模块。

## `debug`

- 类型：`boolean`
- 默认值：`false`

设置为 `true` 以打印调试日志。

## `assets`

- 类型：`object`
- 默认值：`{ fetchOptions: { retry: 3, retryDelay: 2000, timeout: 15_000 } }`

控制 Nuxt 为提供服务而打包脚本的方式。目前唯一支持的 `strategy` 是 `'public'`。

[一方模式指南](/docs/guides/first-party)介绍了构建缓存和回退行为。

## `assets.fallbackOnSrcOnBundleFail`

- 类型：`boolean`
- 默认值：`false`

当打包失败时回退到远程 `src` URL。默认情况下，如果无法下载第三方脚本，打包过程会停止。

## `assets.fetchOptions`

- 类型：`object`
- 默认值：`{ retry: 3, retryDelay: 2000, timeout: 15_000 }`

下载脚本时传递给 fetch 函数的选项。

## `assets.cacheMaxAge`

- 类型：`number`
- 默认值：`604800000`（7 天）

打包脚本的缓存持续时间（毫秒）。早于此时间的脚本将在构建期间重新下载。

## `assets.integrity`

- 类型：`boolean | 'sha256' | 'sha384' | 'sha512'`
- 默认值：`false`

为每个捆绑的脚本生成子资源完整性（SRI）哈希，并添加带有 `crossorigin="anonymous"` 的 `integrity` 属性。

浏览器会在执行脚本之前，将下载的脚本与其声明的哈希进行比较；请参阅 MDN 的[子资源完整性](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity)指南。