---
title: "TypeScript"
description: "Nuxt 完全支持类型，并提供有用的快捷方式，确保在编码时可以获得准确的类型信息。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/typescript"
---
# TypeScript

> Nuxt 完全支持类型，并提供有用的快捷方式，确保在编码时可以获得准确的类型信息。

## 类型检查

出于性能考虑，默认情况下，在运行 [`nuxt dev`](https://nuxt.zhcndoc.com/docs/4.x/api/commands/dev) 或 [`nuxt build`](https://nuxt.zhcndoc.com/docs/4.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/4.x/api/commands/typecheck) 命令来检查类型：

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

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

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

## 自动生成的类型

Nuxt 项目依赖自动生成的类型才能正常运行。这些类型存储在 [`.nuxt`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt) 目录中，并在运行开发服务器或构建应用时生成。你也可以运行 `nuxt prepare` 手动生成这些文件。

[`.nuxt`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/nuxt) 目录中生成的 `tsconfig.json` 文件包含项目**推荐的基本 TypeScript 配置**、对[自动导入](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/auto-imports)、[API 路由类型](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/server-engine#typed-api-routes)的引用、`#imports`、`~/file` 或 `#build/file` 等路径别名，以及其他配置。

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

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

## 项目引用

Nuxt 使用 [TypeScript 项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)来提升类型检查性能并提供更好的 IDE 支持。此功能允许 TypeScript 将你的代码库拆分成更小、更易管理的部分。

### Nuxt 如何使用项目引用

运行 `nuxt dev`、`nuxt build` 或 `nuxt prepare` 时，Nuxt 会为应用的不同部分生成多个 `tsconfig.json` 文件。

- **`.nuxt/tsconfig.app.json`** - 用于 `app/` 目录下应用代码的配置
- **`.nuxt/tsconfig.node.json`** - 用于 `nuxt.config.ts` 及其他上下文外文件的配置
- **`.nuxt/tsconfig.server.json`** - 用于服务器端代码的配置（如适用）
- **`.nuxt/tsconfig.shared.json`** - 用于应用和服务器上下文共享的代码（如类型和非环境特定工具）

这些文件均配置了适当的依赖引用，以便为各自的上下文提供最佳的类型检查。

::note
为保持向后兼容，Nuxt 仍会生成 `.nuxt/tsconfig.json`。不过，为了获得更好的类型安全性和性能，我们建议使用新的配置文件（`.nuxt/tsconfig.app.json`、`.nuxt/tsconfig.server.json` 等）进行 [TypeScript 项目引用](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/tsconfig)。此旧版文件将在 Nuxt 的未来版本中移除。
::

### 项目引用的优势

- **构建更快**：TypeScript 可以跳过对未更改项目的重新构建
- **IDE 性能更好**：你的 IDE 可提供更快的 IntelliSense 和错误检查
- **隔离编译**：应用某部分出错不会阻止其他部分编译
- **依赖管理更清晰**：每个项目都会显式声明其依赖

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

由于项目被划分为**多个类型上下文**，因此**在正确的上下文中增强类型**很重要，这样才能确保类型被正确识别。除非显式包含在相应的上下文中，否则 TypeScript 不会识别放置在这些目录之外的增强类型。

例如，如果你想为 `app` 上下文增强类型，增强文件应放在 `app/` 目录中。

类似地：

- 对于 `server` 上下文，将增强文件放在 `server/` 目录中。
- 对于应用和服务器之间**共享**的类型，将文件放在 `shared/` 目录中。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/modules/recipes-advanced#extend-typescript-config"}
在《模块作者指南》中，详细了解如何从**这些上下文之外的文件**增强特定类型上下文。
::

## 严格检查

TypeScript 提供了一些检查，可为你的程序带来更多安全性和分析能力。

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

如果你正在将代码库迁移到 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.