---
title: "TypeScript"
description: "Nuxt 完全支持类型，并提供了有用的快捷方式，确保您在编码时能够访问准确的类型信息。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/typescript"
---
# TypeScript

> Nuxt 完全支持类型，并提供了有用的快捷方式，确保您在编码时能够访问准确的类型信息。

## 类型检查

默认情况下，出于性能考虑，运行 [`nuxt dev`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/dev) 或 [`nuxt build`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/build) 时，Nuxt 不会检查类型。

要在构建或开发时启用类型检查，请将 `vue-tsc` 和 `typescript` 安装为开发依赖：

::code-group{sync="pm"}
```bash [npm]
npm install --save-dev vue-tsc typescript
```

```bash [yarn]
yarn add --dev vue-tsc typescript
```

```bash [pnpm]
pnpm add -D vue-tsc typescript
```

```bash [bun]
bun add -D vue-tsc typescript
```

```bash [deno]
deno add -D npm:vue-tsc npm:typescript
```
::

然后，运行 [`nuxt typecheck`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/typecheck) 命令来检查类型：

```bash [Terminal]
npx nuxt typecheck
```

您也可以在 `nuxt.config` 文件中使用 [`typescript.typeCheck`](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#typecheck) 选项，在构建或开发时启用类型检查：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  typescript: {
    typeCheck: true,
  },
})
```

## 自动生成的类型

当您运行 `nuxt dev` 或 `nuxt build` 时，Nuxt 会生成以下文件以支持 IDE 的类型提示（以及类型检查）：

### `.nuxt/nuxt.d.ts`

该文件包含您使用的任何模块的类型，以及 Nuxt 所需的关键类型。您的 IDE 应该能够自动识别这些类型。

该文件中的部分引用是指仅在您的 `buildDir` (`.nuxt`) 中生成的文件，因此为了获得完整的类型支持，您需要运行 `nuxt dev` 或 `nuxt build`。

### `.nuxt/tsconfig.json`

该文件包含项目的推荐基础 TypeScript 配置，包括 Nuxt 或您所使用模块注入的已解析别名，这样您就可以获得完整的类型支持和像 `~/file` 或 `#build/file` 这样的别名路径的自动补全。

::note
可以考虑使用 [nuxt.config](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#imports) 中的 `imports` 部分来包含默认目录之外的目录。这对于自动导入您在应用中使用的类型很有用。
::

::warning
Nuxt 依赖此配置，[Nuxt 模块](https://nuxt.zhcndoc.com/docs/3.x/guide/modules) 也可以扩展此配置。为此，不建议直接修改 `tsconfig.json` 文件，因为这样做可能会覆盖重要设置。请改为通过 `nuxt.config.ts` 扩展配置。[在此了解有关扩展配置的更多信息](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/tsconfig)。
::

[阅读更多关于如何扩展此配置的信息](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/tsconfig)。

::tip{icon="i-lucide-video" to="https://youtu.be/umLI7SlPygY" target="_blank"}
观看 Daniel Roe 讲解内置 Nuxt 别名的视频。
::

::note
Nitro 也会为 API 路由[自动生成类型](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/server-engine#typed-api-routes)。此外，Nuxt 还会为全局可用的组件、[来自您的组合式函数的自动导入](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/composables)以及其他核心功能生成类型。
::

::note
请注意，从 `./.nuxt/tsconfig.json` 扩展的所有选项都会被您在 `tsconfig.json` 中定义的选项覆盖。
如果您覆盖了例如 `"compilerOptions.paths"` 这类选项，TypeScript 将不会考虑来自 `./.nuxt/tsconfig.json` 的模块解析。这可能导致诸如 `#imports` 等模块解析无法被识别。
:br :br
如果您需要进一步扩展 `./.nuxt/tsconfig.json` 提供的选项，可以在 `nuxt.config` 中使用 [`alias` 属性](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#alias)。Nuxt 会识别这些属性，并相应地扩展 `./.nuxt/tsconfig.json`。
::

### 使用项目引用增强类型

由于项目被划分为**多个类型上下文**，因此非常重要的是要在**正确的上下文中增强类型**，以确保它们被正确识别。

启用 [`typescript.typeCheck`](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/typescript#type-checking) 选项时，Nuxt 默认会启用[严格检查](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks)，以提供更高的类型安全性。

类似地：

- 对于 `server` 上下文，将增强文件放在 `server/` 目录下。
- 对于 **app 和 server 共享** 的类型，将文件放在 `shared/` 目录中。

::warning
在这些目录之外增强类型将不会被 TypeScript 识别。
::

## 严格检查

TypeScript 提供了某些检查以增强程序的安全性和分析能力。

[严格检查](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) 在 Nuxt 中默认启用，以提供更高的类型安全性。

如果您正在将代码库转换为 TypeScript，可能想临时关闭严格检查，可以在 `nuxt.config` 中将 `strict` 设置为 `false`：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  typescript: {
    strict: false,
  },
})
```


## Sitemap

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