---
title: "Next.js"
description: "学习如何将 Tiptap 集成到 Next.js 中，为您的项目创建一个多功能且强大的富文本编辑器。"
canonical_url: "https://tiptap.zhcndoc.com/editor/getting-started/install/nextjs"
---

# Next.js

学习如何将 Tiptap 集成到 Next.js 中，为您的项目创建一个多功能且强大的富文本编辑器。

Integrate Tiptap with your Next.js project using this step-by-step guide.

### 要求

- 机器上已安装 [Node](https://nodejs.org/en/download/)
- 具备 [React](https://reactjs.org/) 使用经验

## 创建项目（可选）

如果您已有现成的 Next.js 项目，也可以跳过此步骤。

本指南中，我们将新建一个名为 `my-tiptap-project` 的 Next.js 项目。以下命令将设置我们开始所需的一切。

```bash
# 创建项目
npx create-next-app my-tiptap-project

# 进入项目目录
cd my-tiptap-project
```

### 安装依赖

现在我们已有一个标准的样板项目，可以开始配置 Tiptap 了！为此，我们需要安装三个包：`@tiptap/react`、`@tiptap/pm` 和 `@tiptap/starter-kit`，后者包括所有快速入门所需的扩展。

```bash
npm install @tiptap/react @tiptap/pm @tiptap/starter-kit
```

如果您按照步骤 1 和 2 进行操作，现在可以运行 `npm run dev` 启动项目，并在您喜欢的浏览器中打开 [http://localhost:3000/](http://localhost:3000/)。如果您使用的是已有项目，具体方式可能有所不同。

## 集成 Tiptap

要开始使用 Tiptap，您需要向应用添加一个新组件。首先创建一个名为 `components/` 的目录。接下来创建一个名为 `Tiptap` 的组件，将以下示例代码添加到 `components/Tiptap.jsx` 中。

```jsx
'use client'

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'

const Tiptap = () => {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World! 🌎️</p>',
    // 不立即在服务器端渲染以避免 SSR 问题
    immediatelyRender: false,
  })

  return <EditorContent editor={editor} />
}

export default Tiptap
```

> **Why immediatelyRender: false?:**
>
> Next.js 默认使用服务器端渲染。设置 `immediatelyRender: false` 可以防止编辑器在服务器端渲染，从而避免出现 [React hydration mismatch 错误](https://react.dev/errors/418)。编辑器将在客户端水合完成后初始化。`'use client'` 指令确保此组件仅在浏览器中运行。

### Add it to your app

现在，让我们用以下示例代码替换 `app/page.js`（如果您使用的是 Pages 路由，则替换 `pages/index.js`）的内容，将 `Tiptap` 组件集成到应用里。

```jsx
import Tiptap from '../components/Tiptap'

export default function Home() {
  return <Tiptap />
}
```

现在您应该能在浏览器中看到 Tiptap，给自己点个赞吧！:)

## Optimize your performance

We recommend visiting the [React Performance Guide](https://tiptap.zhcndoc.com/guides/performance.md) to integrate the Tiptap Editor efficiently. This will help you avoid potential issues as your app scales.

## Next steps

为避免出现错误：“Yjs was already imported. This breaks constructor checks and will lead to issues!”，请在您的 Next.js 配置文件中添加以下内容。根据您的 `node_modules` 目录所在位置，您可能需要将 `'node_modules/yjs'` 调整为 `'../node_modules/yjs'` 或 `'../../node_modules/yjs'`。

```js
const path = require('path')

module.exports = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      // 确保所有 'yjs' 的导入都解析为同一个实例
      config.resolve.alias['yjs'] = path.resolve(__dirname, 'node_modules/yjs')
    }
    return config
  },
}
```

关于此问题的讨论和修复方案，请参见 [Github](https://github.com/yjs/yjs/issues/438#issuecomment-2225079409)。

## 后续步骤

- [配置您的编辑器](https://tiptap.zhcndoc.com/editor/getting-started/configure.md)
- [为编辑器添加样式](https://tiptap.zhcndoc.com/editor/getting-started/style-editor.md)
- [了解更多 Tiptap 的概念](https://tiptap.zhcndoc.com/editor/core-concepts/introduction.md)
- [学习如何持久化编辑器状态](https://tiptap.zhcndoc.com/editor/core-concepts/persistence.md)
- [开始构建您自己的扩展](https://tiptap.zhcndoc.com/editor/extensions/custom-extensions.md)