TypeScript

Next.js 提供了一种以 TypeScript 为先导的开发体验，用于构建您的 React 应用程序。

它具有内置的 TypeScript 支持，可自动安装必要的软件包并配置正确的设置。

还有一个用于您的编辑器的 TypeScript 插件。

🎥 观看：了解内置 TypeScript 插件 → YouTube（3 分钟）

新项目

现在，create-next-app 默认使用 TypeScript 进行创建。

npx create-next-app@latest

现有项目

通过将文件重命名为 .ts / .tsx 将 TypeScript 添加到您的项目。 运行 next dev 和 next build 以自动安装必要的依赖项并添加一个带有推荐配置选项的 tsconfig.json 文件。

如果您已经有一个 jsconfig.json 文件， 请将旧的 jsconfig.json 中的 paths 编译器选项复制到新的 tsconfig.json 文件中， 并删除旧的 jsconfig.json 文件。

TypeScript 插件

Next.js 包含一个自定义的 TypeScript 插件和类型检查器， VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。

您可以在 VS Code 中启用该插件：

1. 打开命令面板（Ctrl/⌘ + Shift + P）
2. 搜索 "TypeScript: Select TypeScript Version"
3. 选择 "Use Workspace Version"

TypeScript 命令面板

现在，在编辑文件时，将启用自定义插件。运行 next build 时，将使用自定义类型检查器。

插件功能

TypeScript 插件可以帮助：

• 警告是否传递了段配置选项的无效值。
• 显示可用选项和上下文文档。
• 确保正确使用 use client 指令。
• 确保客户端钩子（如 useState）仅在客户端组件中使用。

备注

将来将添加更多功能。

最低 TypeScript 版本

强烈建议至少使用 TypeScript 的 v4.5.2 版本，以获取 import 名称上的类型修饰符和性能改进等语法功能。

静态类型链接

Next.js 可以在使用 next/link 时静态地为链接提供类型，以防止拼写错误和其他错误， 从而在页面之间导航时提高类型安全性。

要启用此功能，需要启用 experimental.typedRoutes，并且项目需要使用 TypeScript。

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig

Next.js 将在 .next/types 中生成一个链接定义，其中包含有关应用程序中所有现有路由的信息， TypeScript 可以使用这些信息在编辑器中提供有关无效链接的反馈。

当前，实验性支持包括任何字符串文字，包括动态段。 对于非文字字符串，您目前需要使用 as Route 手动将 href 强制转换：

import type { Route } from 'next';
import Link from 'next/link'

// 如果 href 是有效路由，则没有 TypeScript 错误
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// 如果 href 不是有效路由，则有 TypeScript 错误
<Link href="/aboot" />

要在包装 next/link 的自定义组件中接受 href，请使用泛型：

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>My Card</div>
    </Link>
  )
}

它是如何工作的？

在运行 next dev 或 next build 时，Next.js 会生成一个隐藏的 .d.ts 文件， 位于 .next 中，其中包含有关应用程序中所有现有路由的信息（Link 的 href 类型）。 此 .d.ts 文件已包含在 tsconfig.json 中，TypeScript 编译器将检查该 .d.ts 文件， 并在编辑器中提供有关无效链接的反馈。

端到端类型安全性

Next.js 13 增强了类型安全性。这包括：

• 在获取函数和页面之间不再对数据进行序列化：您可以在组件、布局和服务器上直接获取数据。此数据无需序列化（转换为字符串）即可传递到用于在 React 中使用的客户端。由于应用程序默认使用 Server Components，因此我们可以在没有任何额外步骤的情况下使用诸如 Date、Map、Set 等值。以前，您需要手动为 Next.js 特定类型定义服务器和客户端之间的边界。
• 组件之间的数据流更加流畅：随着对根布局的移除，现在更容易可视化组件和页面之间的数据流。以前，在单个页面和根布局之间传递的数据难以定义，并且可能引入混乱的错误。在 Next.js 13 中，通过在一起放置数据获取，这不再是一个问题。

Next.js 现在提供了尽可能接近端到端类型安全的数据获取，而不会对您的数据库或内容提供者的选择进行规定。

我们能够像使用普通 TypeScript 一样对响应数据进行类型化。例如：

app/page.tsx

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // 返回值 *不* 被序列化
  // 您可以返回 Date、Map、Set 等。
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

要实现完整的端到端类型安全性，这还要求您的数据库或内容提供者支持 TypeScript。 这可以通过使用 ORM 或类型安全的查询构建器来实现。

异步服务器组件 TypeScript 错误

要在 TypeScript 中使用异步服务器组件， 请确保使用 TypeScript 的 v5.1.3 或更高版本以及 @types/react 的 v18.2.8 或更高版本。

如果使用较旧版本的 TypeScript，可能会看到 'Promise<Element>' 不是有效的 JSX 元素类型错误。 更新到最新版本的 TypeScript 和 @types/react 应该解决此问题。

在服务器和客户端组件之间传递数据

通过 props 在服务器和客户端组件之间传递数据时，数据仍然被序列化（转换为字符串）以在浏览器中使用。 但是，它不需要特殊类型。它的类型与在组件之间传递任何其他 props 相同。

此外，需要序列化的代码更少，因为未呈现的数据不会在服务器和客户端之间交叉（它仍然在服务器上）。 这仅通过对 Server Components 的支持才能实现。

路径别名和 baseUrl

Next.js 自动支持 tsconfig.json 中的 "paths" 和 "baseUrl" 选项。

您可以在 Module Path aliases 文档中详细了解此功能。

对 next.config.js 进行类型检查

next.config.js 文件必须是 JavaScript 文件， 因为它不会被 Babel 或 TypeScript 解析， 但是您可以在 IDE 中使用 JSDoc 添加一些类型检查，如下所示：

// @ts-check

/**
 * @type {import('next').NextConfig}
 **/
const nextConfig = {
  /* 配置选项在这里 */
}

module.exports = nextConfig

增量类型检查

自 v10.2.1 起，Next.js 在 tsconfig.json 中启用时支持增量类型检查， 这有助于加速对较大应用程序的类型检查。

忽略 TypeScript 错误

当您的项目中存在 TypeScript 错误时，Next.js 会在生产构建（next build）时失败。

如果希望 Next.js 在应用程序存在错误时危险地生成生产代码，可以禁用内置的类型检查步骤。

如果禁用，请确保在构建或部署过程中运行类型检查，否则可能会很危险。

打开 next.config.js 并在 typescript 配置中启用 ignoreBuildErrors 选项：

next.config.js

module.exports = {
  typescript: {
    // !! 警告 !!
    // 危险地允许在您的项目有类型错误时成功完成生产构建。
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

版本更改

版本	更改
v13.2.0	静态类型链接在 beta 中可用
v12.0.0	默认使用 SWC 编译 TypeScript 和 TSX 以实现更快的构建
v10.2.1	启用 tsconfig.json 中的增量类型检查支持