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: Select TypeScript Version"
3. 选择 "Use Workspace Version"

现在，当编辑文件时，将启用自定义插件。当运行 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 可以使用这些信息在您的编辑器中提供有关无效链接的反馈。

目前，实验性支持包括任何字符串字面量，包括动态段。对于非字面量字符串，您目前需要手动将 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 并在您的编辑器中提供有关无效链接的反馈。

使用异步服务器组件

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

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

增量类型检查

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

在生产环境中禁用 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"]
}

版本变更