3分钟上手 Novel：Notion 风格编辑器本地部署与配置全攻略

3分钟上手 Novel：Notion 风格编辑器本地部署与配置全攻略

【免费下载链接】novel Notion-style WYSIWYG editor with AI-powered autocompletion. 项目地址: https://gitcode.com/gh_mirrors/no/novel

还在为寻找一款功能强大又易于部署的富文本编辑器而烦恼？Novel 作为一款开源的 Notion 风格所见即所得（WYSIWYG）编辑器，不仅具备优雅的界面设计，还集成了 AI 自动补全功能，完美满足文档编辑与内容创作需求。本文将带你从环境准备到启动运行，一站式完成 Novel 项目的本地部署与基础配置，让你快速拥有媲美 Notion 的编辑体验。

项目概述与环境要求

Novel 项目采用现代化技术栈构建，核心基于 Next.js 框架和 Tiptap 编辑器，结合 OpenAI 提供 AI 能力支持。官方文档：apps/docs/introduction.mdx

技术栈概览

• 前端框架：Next.js
• 编辑器核心：Tiptap（packages/headless/src/components/editor.tsx）
• AI 能力：OpenAI API 与 Vercel AI SDK
• 样式解决方案：TailwindCSS（apps/web/tailwind.config.ts）
• 部署工具：Vercel

环境依赖

• Node.js 18.x+
• pnpm 包管理器
• Git
• 环境变量：
  • OPENAI_API_KEY：用于 AI 自动补全功能（apps/web/app/api/generate/route.ts）
  • BLOB_READ_WRITE_TOKEN：Vercel Blob 存储服务令牌（apps/web/app/api/upload/route.ts）

快速部署步骤

1. 克隆项目仓库

git clone https://gitcode.com/gh_mirrors/no/novel.git
cd novel

2. 安装依赖包

项目采用 pnpm 工作区管理多包架构，执行以下命令安装所有依赖：

pnpm install

依赖配置文件：package.json、pnpm-workspace.yaml

3. 配置环境变量

在项目根目录创建 .env.local 文件，添加必要环境变量：

# AI 功能配置
OPENAI_API_KEY=your_openai_api_key_here

# 文件存储配置
BLOB_READ_WRITE_TOKEN=your_vercel_blob_token_here

获取 OpenAI API 密钥：OpenAI 账户设置
获取 Vercel Blob 令牌：Vercel Blob 控制台

4. 启动开发服务器

pnpm dev

等待编译完成后，访问 http://localhost:3000 即可看到编辑器界面。开发配置文件：apps/web/next.config.js

核心功能与目录结构

项目架构概览

Novel 采用 monorepo 结构组织代码，主要包含以下模块：

目录路径	功能说明
packages/headless/	核心编辑器组件库，基于 Tiptap 封装
apps/web/	示例应用，包含完整编辑器实现
apps/docs/	官方文档，包含详细使用指南
examples/novel-tailwind/	Tailwind 集成示例

关键功能模块

• AI 自动补全：apps/web/components/tailwind/generative/
• 图片上传：apps/web/app/api/upload/route.ts
• 命令面板：apps/web/components/tailwind/slash-command.tsx
• 气泡菜单：apps/web/components/tailwind/selectors/

常见问题解决

依赖安装失败

若执行 pnpm install 时出现依赖冲突，尝试清除缓存后重新安装：

pnpm store prune
pnpm install

AI 功能无法使用

1. 检查 OPENAI_API_KEY 是否正确配置
2. 确认网络环境可访问 OpenAI API（国内用户可能需要配置代理）
3. 查看 API 调用日志：apps/web/app/api/generate/route.ts

样式显示异常

Novel 本身不包含样式文件，需配合 UI 框架使用：

• Tailwind 集成方案：apps/docs/guides/tailwind/setup.mdx
• 自定义样式示例：examples/novel-tailwind/src/app/globals.css

扩展与定制

集成到现有项目

通过 npm 安装核心包：

npm install novel

基础使用示例：

import { EditorRoot, EditorContent } from 'novel';

export default function MyEditor() {
  return (
    <EditorRoot>
      <EditorContent />
    </EditorRoot>
  );
}

详细集成指南：apps/docs/quickstart.mdx

添加自定义扩展

参考 packages/headless/src/extensions/ 实现自定义编辑器功能，例如添加数学公式支持：

// 自定义扩展示例
import { Extension } from '@tiptap/core';

const MathExtension = Extension.create({
  name: 'math',
  // 实现扩展逻辑
});

结语

通过本文指南，你已成功部署并运行 Novel 编辑器。如需进一步定制功能，可参考官方文档的高级指南：apps/docs/guides/。社区贡献指南：CONTRIBUTING.md

祝使用愉快！如有问题，欢迎通过项目 Issue 系统反馈。

【免费下载链接】novel Notion-style WYSIWYG editor with AI-powered autocompletion. 项目地址: https://gitcode.com/gh_mirrors/no/novel