TypeScript

Next.js 内置了 TypeScript，当您使用 create-next-app 创建新项目时，会自动安装必要的包并配置正确的设置。

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

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

IDE 插件

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

您可以在 VS Code 中启用该插件，方法是

1. 打开命令面板 (`Ctrl/⌘` + `Shift` + `P`)
2. 搜索 "TypeScript: 选择 TypeScript 版本"
3. 选择 "使用工作区版本"

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

TypeScript 插件可以帮助您：

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

🎥 观看： 了解内置的 TypeScript 插件 → YouTube (3 分钟)

端到端类型安全

Next.js App Router 具有增强的类型安全性。这包括

1. 获取函数和页面之间的数据无需序列化：您可以直接在服务器上的组件、布局和页面中 fetch 数据。此数据无需序列化（转换为字符串）即可传递到客户端以在 React 中使用。相反，由于 `app` 默认使用服务器组件，我们可以直接使用 Date、Map、Set 等值，而无需任何额外的步骤。以前，您需要使用 Next.js 特定的类型手动键入服务器和客户端之间的边界。
2. 组件之间简化的数据流：随着 _app 被移除，取而代之的是根布局，现在更容易可视化组件和页面之间的数据流。以前，在各个 `pages` 和 `_app` 之间流动的数据很难进行类型化，并且可能引入令人困惑的错误。通过 App Router 中的同地数据获取，这不再是一个问题。

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 或类型安全的查询构建器来实现。

示例

类型检查 next.config.ts

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

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* config options here */
}
 
export default nextConfig

须知：`next.config.ts` 中的模块解析目前仅限于 `CommonJS`。这可能会导致在 `next.config.ts` 中加载仅 ESM 的包时出现不兼容性。

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

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
}
 
module.exports = nextConfig

静态类型链接

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 可以使用该信息在编辑器中提供有关无效链接的反馈。

目前，实验性支持包括任何字符串字面量，包括动态段。对于非字面量字符串，您目前需要使用 `as Route` 手动转换 `href`

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` 文件并在编辑器中提供有关无效链接的反馈。

使用异步服务器组件

要将 `async` 服务器组件与 TypeScript 一起使用，请确保您使用的是 TypeScript `5.1.3` 或更高版本以及 `@types/react` `18.2.8` 或更高版本。

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

增量类型检查

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

在生产环境中禁用 TypeScript 错误

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

如果您希望 Next.js 即使在您的应用程序有错误的情况下也危险地生成生产代码，您可以禁用内置的类型检查步骤。

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

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

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  typescript: {
    // !! WARN !!
    // Dangerously allow production builds to successfully complete even if
    // your project has type errors.
    // !! WARN !!
    ignoreBuildErrors: true,
  },
}
 
export default nextConfig

须知：您可以在构建之前运行 `tsc --noEmit` 来自行检查 TypeScript 错误。这对于 CI/CD 管道很有用，您可以在部署之前检查 TypeScript 错误。

自定义类型声明

当您需要声明自定义类型时，您可能会想修改 `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"]
}

版本变更