本文详细讲解如何使用 @tiptap/extension-code-block-lowlight 为 TipTap 编辑器添加带语法高亮的代码块功能，涵盖安装配置、语言加载、StarterKit 冲突解决及配套 CSS 样式，适用于 Vite/SvelteKit 等现代前端环境。
本文详细讲解如何使用 @tiptap/extension-code-block-lowlight 为 tiptap 编辑器添加带语法高亮的代码块功能，涵盖安装配置、语言加载、starterkit 冲突解决及配套 css 样式，适用于 vite/sveltekit 等现代前端环境。
TipTap 默认的 StarterKit 提供了基础的 <code> 行内代码支持，但不支持多行代码块的语法高亮。若需在三重反引号（``<code>lang）包裹的代码块中启用如 JavaScript、Python、HTML 等语言的彩色语法高亮，必须引入专用扩展 ——@tiptap/extension-code-block-lowlight`，它基于轻量级高亮引擎 lowlight 构建，兼顾性能与可定制性。
✅ 正确集成步骤（适配 Vite/SvelteKit）
1. 安装依赖
npm install lowlight @tiptap/extension-code-block-lowlight
⚠️ 注意：
lowlight是必需对等依赖（peer dependency），不可省略；仅安装@tiptap/extension-code-block-lowlight会导致运行时错误。
2. 配置编辑器扩展
关键点在于禁用 StarterKit 自带的 codeBlock（否则会触发 Duplicate extension names found: ['blockCode'] 警告），并显式传入初始化后的 lowlight 实例：
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,
}),
// 启用高亮版代码块，预载常用语言（如 js/ts/html/css/python）
CodeBlockLowlight.configure({
lowlight: createLowlight(common),
}),
],
content: '<p>Type <code>```js</code> and press Enter to insert a highlighted code block.</p>',
});?
common是lowlight提供的预设语言集合（约 30+ 种），适合大多数场景。如需精简体积，可按需导入特定语言：import javascript from 'highlight.js/lib/languages/javascript'; import typescript from 'highlight.js/lib/languages/typescript'; const lowlight = createLowlight({ javascript, typescript });
3. 添加高亮 CSS 样式
lowlight 生成的 HTML 使用标准 hljs-* 类名（兼容 Highlight.js 主题）。你需手动引入或编写对应样式。以下是一套简洁、深色主题的示例（可直接嵌入 <style></style> 或 CSS 文件）：
pre {
background: #0D0D0D;
color: #FFF;
font-family: 'JetBrains Mono', '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 兼容类名（部分） */
.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; }✅ 验证效果
在编辑器中输入：
```ts
const greet = (name: string) => `Hello, ${name}!`;
console.log(greet("TipTap"));将自动渲染为带 TypeScript 语法高亮的代码块。 ### ? 注意事项 - **不要同时启用 `StarterKit.codeBlock` 和 `CodeBlockLowlight`**：二者注册同名节点 `blockCode`，会导致扩展冲突； - **语言加载是静态的**：`createLowlight()` 在初始化时绑定语言，切换语言需重建编辑器（或使用动态加载方案）； - **SSR/构建优化**：在 SvelteKit/Vite 中，确保 `lowlight` 未被错误地服务端打包（通常无问题，但若遇 `window is not defined`，请检查是否误在 `onCreate` 中调用浏览器 API）； - **主题可替换**：上述 CSS 可替换为任意 [Highlight.js 主题](https://github.com/highlightjs/highlight.js/tree/main/src/styles)，只需保持类名一致。 通过以上配置，你的 TipTap 编辑器即可开箱即用地支持专业级代码块语法高亮，兼顾开发体验与最终用户阅读体验。
