TypeScript

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 文件，请将 paths 编译器选项从旧的 jsconfig.json 复制到新的 tsconfig.json 文件中，并删除旧的 jsconfig.json 文件。

TypeScript 插件

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

您可以通过以下方式在 VS Code 中启用该插件：

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

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

插件功能

TypeScript 插件可帮助：

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

须知： 未来将添加更多功能。

最低 TypeScript 版本

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

静态类型链接

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

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

/** @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>我的卡片</div>
    </Link>
  )
}

工作原理是什么？

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

端到端类型安全

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

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

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

我们可以像普通 TypeScript 那样对响应数据进行类型化。例如：

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>' 不是有效的 JSX 元素 类型错误。更新到最新版本的 TypeScript 和 @types/react 应可解决此问题。

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

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

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

路径别名和 baseUrl

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

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

检查 next.config.js 类型

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

// @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 选项：

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

版本变更