---
title: "以编程方式使用"
description: "Nuxt Kit 提供了一组实用工具，帮助你以编程方式使用 Nuxt。这些函数允许你加载 Nuxt、构建 Nuxt，并加载 Nuxt 配置。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/kit/programmatic"
---
# 以编程方式使用

> Nuxt Kit 提供了一组实用工具，帮助你以编程方式使用 Nuxt。这些函数允许你加载 Nuxt、构建 Nuxt，并加载 Nuxt 配置。

在需要以编程方式使用 Nuxt 时，编程使用非常有用，例如在构建 [CLI 工具](https://github.com/nuxt/cli) 或 [测试工具](https://github.com/nuxt/test-utils) 时。

## `loadNuxt`

以编程方式加载 Nuxt。它会加载 Nuxt 配置，实例化并返回包含 Nuxt 实例的 Promise。

### 类型

```ts
function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
```

### 参数

**`loadOptions`**：Nuxt 的加载条件。`loadNuxt` 在内部使用 [`c12`](https://github.com/unjs/c12)，因此它接受与 `c12.loadConfig` 相同的选项，并附加以下选项：

| 属性      | 类型        | 必需      | 描述                                                                                      |
| ------- | --------- | ------- | --------------------------------------------------------------------------------------- |
| `dev`   | `boolean` | `false` | 如果设置为 `true`，Nuxt 将以开发模式加载。                                                             |
| `ready` | `boolean` | `true`  | 如果设置为 `true`，`loadNuxt` 调用后 Nuxt 将可立即使用。如果设置为 `false`，你需要调用 `nuxt.ready()` 来确保 Nuxt 可用。 |

## `buildNuxt`

以编程方式构建 Nuxt。它会调用构建器（当前为 [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite) 或 [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)）来打包应用程序。

### 类型

```ts
function buildNuxt (nuxt: Nuxt): Promise<any>
```

### 参数

**`nuxt`**：要构建的 Nuxt 实例。可以通过上下文中的 `useNuxt()` 调用获取。

## `loadNuxtConfig`

加载 Nuxt 配置。它将返回包含配置对象的 Promise。

### 类型

```ts
function loadNuxtConfig (options: LoadNuxtConfigOptions): Promise<NuxtOptions>
```

### 参数

**`options`**：用于控制如何查找、合并和加载配置的选项。

| 属性                 | 类型                                                  | 默认值             | 描述                                                               |
| ------------------ | --------------------------------------------------- | --------------- | ---------------------------------------------------------------- |
| `cwd`              | `string`                                            | `process.cwd()` | 从哪个目录加载 `nuxt.config`。                                           |
| `configFile`       | `string`                                            | `'nuxt.config'` | 要加载的配置文件名称，不带扩展名。                                                |
| `rcFile`           | `string \| false`                                   | `'.nuxtrc'`     | 与配置文件一同加载的 `.rc` 文件名称，或设置为 `false` 表示不加载任何文件。                    |
| `globalRc`         | `boolean`                                           | `true`          | 同时加载用户级和工作区级的 `.nuxtrc` 文件。                                      |
| `overrides`        | `NuxtConfig`                                        | `undefined`     | 应用于每一层之上的配置，包括根项目自身的 `nuxt.config`。                              |
| `defaults`         | `NuxtConfig`                                        | `undefined`     | 在每一层之下、架构默认值之前应用的配置。                                             |
| `dotenv`           | `boolean \| NuxtDotenvOptions`                      | `true`          | 在解析配置之前将 `.env` 文件加载到 `process.env`。如果环境变量已经填充，请设置为 `false`。     |
| `envName`          | `string \| false`                                   | `undefined`     | 用于选择 `$env.*` 配置覆盖项的环境名称。优先级高于 `nuxt.config` 中设置的 `envName`。     |
| `resolve`          | `(source, context) => ResolvedNuxtLayer \| nullish` | `undefined`     | 自行将 `extends` 条目解析为一层。返回 nullish 值时，将对该来源回退到默认解析方式。              |
| `import`           | `(id: string) => Promise<unknown>`                  | `undefined`     | 使用自定义加载器而非默认加载器导入配置文件，例如，在 Nuxt 不使用 `jiti` 的情况下加载 TypeScript 配置。 |
| `onConfigResolved` | `(context: ResolvedNuxtConfigContext) => void`      | `undefined`     | 配置成功加载后调用一次并等待其完成。如果加载抛出错误，则不会调用。                                |

### `onConfigResolved`

传递给 `onConfigResolved` 的上下文描述了加载的内容：

| 属性           | 类型                  | 描述                                                                                         |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------ |
| `rawConfig`  | `NuxtConfig`        | 合并所有层后的用户配置，不应用架构默认值，也不包含 `overrides`、`defaults` 和 `defaultConfig`，因此对未更改的项目重复加载时会产生相同的快照。 |
| `layers`     | `NuxtConfigLayer[]` | 已解析的配置层，按优先级从高到低排列。                                                                        |
| `configFile` | `string?`           | 根 `nuxt.config` 文件的绝对路径（如果找到）。                                                             |
| `cwd`        | `string`            | 加载配置的目录。                                                                                   |

## `diffNuxtConfig`

比较两个 `rawConfig` 快照（由 `onConfigResolved` 提供），并返回它们之间的差异。当你自行监视配置文件，并需要在决定是否重启之前了解哪些键发生了变化时，这很有用。

### 类型

```ts
function diffNuxtConfig (oldConfig: NuxtConfig, newConfig: NuxtConfig): NuxtConfigDiffEntry[]
```

### 参数

**`oldConfig`**：之前的 `rawConfig` 快照。

**`newConfig`**：当前的 `rawConfig` 快照。

### 返回值

一个条目数组，每个条目对应一处差异。每个条目包含：

| 属性         | 类型                                  | 描述                                                                              |
| ---------- | ----------------------------------- | ------------------------------------------------------------------------------- |
| `type`     | `'added' \| 'removed' \| 'changed'` | 值的变化类型。                                                                         |
| `path`     | `Array<string \| number>`           | 已更改值的属性路径，数组索引以数字表示，例如 `['runtimeConfig', 'public', 'foo']`。读取配置对象中的值时，优先使用此属性。 |
| `label`    | `string`                            | 将 `path` 写成属性访问器的形式，用于显示或与已知键匹配，例如 `runtimeConfig.public.foo` 或 `modules[0]`。   |
| `newValue` | `unknown`                           | 对于 `added` 和 `changed` 条目，此属性存在。                                                |
| `oldValue` | `unknown`                           | 对于 `removed` 和 `changed` 条目，此属性存在。                                              |

源代码未更改的函数不会被报告为变化，因此，声明了内联函数的配置不会在每次加载时都与自身产生差异。

### 示例

```ts
import { diffNuxtConfig, loadNuxtConfig } from '@nuxt/kit'

let previous

async function load () {
  await loadNuxtConfig({
    cwd: process.cwd(),
    onConfigResolved ({ rawConfig }) {
      if (previous) {
        for (const entry of diffNuxtConfig(previous, rawConfig)) {
          console.log(`${entry.label} was ${entry.type}`)
        }
      }
      previous = rawConfig
    },
  })
}
```

## `writeTypes`

生成 `tsconfig.json` 并将其写入项目的 buildDir。

### 类型

```ts
function writeTypes (nuxt?: Nuxt): void
```

### 参数

**`nuxt`**：要构建的 Nuxt 实例。可以通过上下文中的 `useNuxt()` 调用获取。

---

- [源码](https://github.com/nuxt/nuxt/tree/main/packages/kit/src/loader)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.