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文件。

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

TypeScript 插件

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

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

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

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

插件功能

TypeScript 插件可以帮助:

如果传递段配置选项的无效值，则警告。
显示可用选项和上下文文档。
确保正确使用use client指令。
确保客户端 hooks (如 useState)仅在客户端组件中使用。

您需要知道:将来会添加更多功能。

最低 TypeScript 版本

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

Next.js 中的类型检查配置

类型检查 next.config.js

当使用next.config.js文件时，您可以使用 JSDoc 在您的 IDE 中添加一些类型检查，如下所示：

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
};

module.exports = nextConfig;

类型检查 next.config.ts

您可以使用 TypeScript，并通过使用next.config.ts在您的 Next.js 配置中导入类型。

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

export default nextConfig;

您需要知道: 您可以在next.config.ts中无需任何额外配置地导入原生 ESM 模块。支持导入.cjs、.cts、.mjs和.mts等扩展名。

静态类型链接

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

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

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'

// No TypeScript errors if href is a valid route
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// TypeScript errors if href is not a valid route
<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之间流动时很难进行类型检查，并且可能引入令人困惑的错误。通过在 App Router 中使用colocated data fetching，这个问题不再存在。

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

我们可以像使用普通 TypeScript 一样对响应数据进行类型定义。例如：

async function getData() {
  const res = await fetch("https://api.example.com/...");
  // The return value is *not* serialized
  // You can return Date, Map, Set, etc.
  return res.json();
}

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

  return "...";
}

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

异步服务器组件 TypeScript 错误

要将async服务器组件与 TypeScript 一起使用, 请确保您使用的是 TypeScript5.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"选项。

您可以在Module Path aliases 文档中了解更多关于此功能的信息。

增量类型检查

自v10.2.1起，Next.js 在您的tsconfig.json中启用后，支持增量类型检查，这可以帮助加快大型应用程序中的类型检查速度。

忽略 TypeScript 错误

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

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

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

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

export default {
  typescript: {
    // !! WARN !!
    // Dangerously allow production builds to successfully complete even if
    // your project has type errors.
    // !! WARN !!
    ignoreBuildErrors: true,
  },
};

自定义类型声明

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

{
  "compilerOptions": {
    "skipLibCheck": true
    //...truncated...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

版本变更

Version	Changes
`v15.0.0`	`next.config.ts` 增加对 TypeScript 项目的支持。
`v13.2.0`	静态类型链接在测试版中可用。
`v12.0.0`	SWC现在默认用于编译 TypeScript 和 TSX，以加快构建速度。
`v10.2.1`	在`tsconfig.json`中启用时，添加了增量类型检查支持。

新项目​

现有项目​

TypeScript 插件​

插件功能​

最低 TypeScript 版本​

Next.js 中的类型检查配置​

类型检查 next.config.js​

类型检查 next.config.ts​

静态类型链接​

端到端类型安全​

异步服务器组件 TypeScript 错误​

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

路径别名和 baseUrl​

增量类型检查​

忽略 TypeScript 错误​

自定义类型声明​

版本变更​

新项目