v4 (4.0.0)
Nuxt on GitHub

TypeScript

Nuxt 完全支持类型检查，并提供了实用的快捷方式，确保你在编码时能够获取准确的类型信息。

类型检查

出于性能原因，默认情况下，当你运行 nuxt dev 或 nuxt build 时，Nuxt 不会进行类型检查。

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

npm install --save-dev vue-tsc typescript

然后，运行 nuxt typecheck 命令来检查你的类型：

终端
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
  }
})