v4 (4.0.0)
GitHub

TypeScript

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

类型检查

默认情况下，出于性能考虑，Nuxt 在运行 nuxt dev 或 nuxt build 时不会检查类型。

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

npm install --save-dev vue-tsc typescript

然后，运行 nuxt typecheck 命令以检查您的类型：

Terminal
npx nuxt typecheck

要在构建或开发时启用类型检查，您还可以在 nuxt.config 文件中使用 typescript.typeCheck 选项：

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.app.json

此文件包含您项目的推荐基本 TypeScript 配置，包括由 Nuxt 或您所使用的模块注入的解析别名，因此您可以获得完整的类型支持和路径自动补全，例如 ~/file 或 #build/file。

考虑使用 nuxt.config 的 imports 部分来包含超出默认目录的目录。这对于自动导入您在应用程序中使用的类型非常有用。

详细了解如何扩展此配置。

观看来自 Daniel Roe 的视频，解释内置的 Nuxt 别名。
Nitro 也会为 API 路由 自动生成类型。此外，Nuxt 还会生成全局可用组件和来自您的组合函数的 自动导入 的类型，以及其他核心功能。
为了向后兼容，Nuxt 仍然生成 ./.nuxt/tsconfig.json。然而，我们建议使用 TypeScript 项目引用 和新的配置文件（如 .nuxt/tsconfig.app.json、.nuxt/tsconfig.server.json 等）来提升类型安全性和性能。如果您扩展自 ./.nuxt/tsconfig.json，请注意所有选项将被您 tsconfig.json 中定义的选项覆盖。覆盖诸如 "compilerOptions.paths" 等选项会导致 TypeScript 忽略模块解析，从而导致无法识别例如 #imports 之类的模块解析。如果您需要进一步扩展选项，可以在您的 nuxt.config 中使用 alias 属性。Nuxt 会自动拾取并相应地扩展生成的 TypeScript 配置。

项目引用

Nuxt 使用 TypeScript 项目引用 来提升类型检查性能并提供更好的 IDE 支持。此功能允许 TypeScript 将您的代码库拆分为更小、更易管理的部分。

Nuxt 如何使用项目引用

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

  • .nuxt/tsconfig.app.json - 应用程序代码的配置
  • .nuxt/tsconfig.node.json - 用于 nuxt.config 和模块的配置
  • .nuxt/tsconfig.server.json - 服务器端代码的配置（如适用）
  • .nuxt/tsconfig.shared.json - 用于应用程序和服务器上下文之间共享的代码（如类型和非环境特定实用程序）
  • .nuxt/tsconfig.json - 向后兼容的旧配置

每个文件都被配置为引用适当的依赖项，并为其特定情境提供最佳的类型检查。

项目引用的好处

  • 构建更快：TypeScript 可以跳过未更改项目的重建
  • 更佳的 IDE 性能：您的 IDE 能提供更快的智能感知和错误检查
  • 隔离的编译：应用程序某部分的错误不会阻止其他部分的编译
  • 更清晰的依赖管理：每个项目明确声明其依赖关系
项目引用的设置由 Nuxt 自动处理。通常您不需要手动修改这些配置，但了解它们的工作方式有助于您排查类型检查问题。

严格检查

TypeScript 带有某些检查，以为您提供更多的安全性和对程序的分析。

在 Nuxt 中，默认启用 严格检查，以提高类型安全性。

如果您目前正在将代码库转换为 TypeScript，您可能希望通过在 nuxt.config 中将 strict 设置为 false 来暂时禁用严格检查：

nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    strict: false
  }
})