本文详细讲解如何使用 @tiptap/extension-code-block-lowlight 为 TipTap 编辑器添加带语法高亮的代码块功能，涵盖依赖安装、扩展配置、StarterKit 冲突规避及配套 CSS 样式方案。
本文详细讲解如何使用 @tiptap/extension-code-block-lowlight 为 tiptap 编辑器添加带语法高亮的代码块功能，涵盖依赖安装、扩展配置、starterkit 冲突规避及配套 css 样式方案。
TipTap 默认的 codeBlock 节点（来自 @tiptap/starter-kit）仅提供纯文本格式的代码容器，不支持语法高亮。要实现类似 GitHub 或 VS Code 风格的彩色语法渲染，需引入官方推荐的 code-block-lowlight 扩展——它基于 lowlight（Prism 的轻量替代），支持按需加载语言定义与主题样式。
✅ 正确集成步骤
1. 安装依赖
npm install lowlight @tiptap/extension-code-block-lowlight
⚠️ 注意：
lowlight是必需对等依赖，不可省略；否则运行时会报lowlight is not defined错误。
2. 配置扩展（关键：避免命名冲突）
@tiptap/starter-kit 内置了名为 blockCode 的扩展，而 CodeBlockLowlight 也注册同名节点，直接共存将触发警告：
Duplicate extension names found: ['blockCode']
因此必须显式禁用 StarterKit 中的默认代码块：
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import { CodeBlockLowlight } from '@tiptap/extension-code-block-lowlight';
import { common, createLowlight } from 'lowlight';
const editor = new Editor({
element: document.querySelector('#editor')!,
extensions: [
// ✅ 禁用 StarterKit 自带 codeBlock
StarterKit.configure({
codeBlock: false,
}),
// ✅ 启用高亮版代码块，预载常用语言
CodeBlockLowlight.configure({
lowlight: createLowlight(common),
}),
],
content: '<p>Try typing <code>```js</code> and press Enter!</p>',
});?
common是 lowlight 提供的常用语言集合（含 JavaScript、TypeScript、HTML、CSS、JSON、Python 等）。如需精简体积，可改用createLowlight({ javascript, html, css })按需导入。
3. 添加语法高亮 CSS 样式
code-block-lowlight 本身不注入样式，需手动引入或编写 .hljs-* 类规则。以下是一套简洁、高对比度的暗色主题示例（适配 pre > code 结构）：
pre {
background: #0D0D0D;
color: #FFF;
font-family: 'JetBrainsMono', 'SFMono-Regular', Consolas, monospace;
padding: 0.75rem 1rem;
border-radius: 0.5rem;
overflow-x: auto;
}
pre code {
color: inherit;
padding: 0;
background: none;
font-size: 0.875rem;
line-height: 1.5;
}
/* Highlight.js 样式类（对应 lowlight 输出） */
.hljs-comment,
.hljs-quote {
color: #616161;
}
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-tag,
.hljs-name,
.hljs-regexp,
.hljs-link,
.hljs-selector-id,
.hljs-selector-class {
color: #F98181;
}
.hljs-number,
.hljs-meta,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #FBBC88;
}
.hljs-string,
.hljs-symbol,
.hljs-bullet {
color: #B9F18D;
}
.hljs-title,
.hljs-section {
color: #FAF594;
}
.hljs-keyword,
.hljs-selector-tag {
color: #70CFF8;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: 700;
}✅ 小贴士：若使用 Tailwind CSS，建议将上述规则提取为
<style></style>块或独立 CSS 文件，避免被 PurgeCSS 误删。
? 使用效果验证
在编辑器中输入：
```ts
interface User {
id: number;
name: string;
}
const user: User = { id: 1, name: 'Alice' };→ 渲染后将自动识别 TypeScript 语法，并应用对应颜色高亮。 ### ? 总结 - ✅ 必须禁用 `StarterKit.codeBlock`，否则扩展注册冲突； - ✅ `lowlight` + `createLowlight()` 是语法解析核心，不可跳过； - ✅ CSS 是高亮可见的前提，`.hljs-*` 类名需与 lowlight 输出完全匹配； - ✅ 支持 SSR（如 SvelteKit/Vite），但需确保 `lowlight` 在服务端可安全执行（无 DOM 依赖）。 完成以上配置后，你的 TipTap 编辑器即可原生支持多语言、高性能、可定制的代码块语法高亮。
