Next.js 为构建 React 应用提供了以 TypeScript 为首的开发体验。

它内置了 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 文件。

我们还建议你使用 next.config.ts 代替 next.config.js 以获得更好的类型推断。

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

你可以通过以下步骤在 VS Code 中启用该插件：

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

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

插件功能

TypeScript 插件可以帮助：

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

注意：未来将添加更多功能。

最低 TypeScript 版本

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

Next.js 配置中的类型检查

next.config.js 文件中的类型检查

在使用 next.config.js 文件时，可以使用以下 JSDoc 方式在 IDE 中添加类型检查：

// next.config.js
// @ts-check
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在此处添加配置选项 */
}
module.exports = nextConfig

next.config.ts 文件中的类型检查

你可以使用 TypeScript 并在 Next.js 配置中导入类型，通过使用 next.config.ts 文件实现。

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* 在此处添加配置选项 */
}

export default nextConfig

注意：你可以在 next.config.ts 中导入原生 ESM 模块，无需任何额外配置。支持导入 .cjs、.cts、.mjs 和 .mts 等扩展名。

静态类型链接

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

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

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

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

目前，实验支持包括任何字符串字面量，包括动态段。对于非字面量字符串，目前需要手动将 href 转换为 as Route：

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 会在 .next 中生成一个隐藏的 .d.ts 文件，其中包含应用程序中所有现有路由的信息（所有有效路由作为 Link 的 href 类型）。此 .d.ts 文件包含在 tsconfig.json 中，TypeScript 编译器将检查该 .d.ts 文件并在编辑器中提供无效链接的反馈。

端到端类型安全

Next.js App Router 提供了 增强的类型安全，包括：

在获取函数和页面之间无数据序列化：你可以直接在组件、布局和服务器上的页面中使用 fetch。这些数据 不需要 序列化（转换为字符串）即可传递给客户端供 React 使用。由于 app 默认使用服务器组件，我们可以使用 Date、Map、Set 等值，无需任何额外步骤。之前，你需要使用 Next.js 特定类型手动键入服务器和客户端之间的边界。
组件之间的数据流简化：通过去除 _app 而采用根布局，现在更容易可视化组件和页面之间的数据流。之前，在单个 pages 和 _app 之间的数据流很难类型化，可能会引入令人困惑的错误。通过共置数据获取(colocated data fetching) 在 App Router 中，这不再是问题。

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 的 async 服务器组件，请确保使用 TypeScript 5.1.3 或更高版本，以及 @types/react 18.2.8 或更高版本。

如果你使用的是较旧版本的 TypeScript，可能会看到 'Promise<Element>' is not a valid JSX element 类型错误。更新到最新版本的 TypeScript 和 @types/react 应该可以解决此问题。

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

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

此外，由于未渲染的数据不会在服务器和客户端之间传递（它保留在服务器上），因此需要序列化的代码更少。这只通过支持服务器组件才能实现。

路径别名和 baseUrl

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

你可以在模块路径别名文档中了解有关此功能的更多信息。

增量类型检查

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

忽略 TypeScript 错误

Next.js 会在 生产构建（next build）时检测项目中的 TypeScript 错误，并且如果存在错误，构建将失败。

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

禁用后，请确保你在构建或部署过程中运行类型检查，否则这可能会非常危险。

在 next.config.ts 文件中，启用 typescript 配置中的 ignoreBuildErrors 选项：

// next.config.ts
export default {
  typescript: {
    // !! 警告 !!
    // 允许生产构建即使项目存在类型错误也能成功完成。
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

自定义类型声明

当你需要声明自定义类型时，可能会倾向于修改 next-env.d.ts 文件。然而，该文件是自动生成的，因此你所做的任何更改都会被覆盖。相反，你应该创建一个新文件，比如 new-types.d.ts，并在 tsconfig.json 中引用它：

// tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
    //...其他配置选项...
  },
  "include": ["new-types.d.ts", "next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

版本更改

版本	更改说明
`v15.0.0`	在 TypeScript 项目中添加对 `next.config.ts` 的支持。
`v13.2.0`	提供静态类型链接功能的测试版本。
`v12.0.0`	默认使用 SWC 编译 TypeScript 和 TSX 以加快构建速度。
`v10.2.1`	当在 `tsconfig.json` 中启用时，添加了对增量类型检查的支持。

这是关于 Next.js 中 TypeScript 的完整指南，涵盖了插件功能、版本要求、静态类型链接、端到端类型安全、异步服务器组件错误处理、路径别名、自定义类型声明等。随着 Next.js 的发展和更新，新的功能和改进将不断加入，使开发人员能够更好地利用 TypeScript 提供的类型安全性。

TypeScript插件

新项目