Tiptap 官方 Demos 包版本演进解析：从 2.x 到 3.0 的构建体系、依赖与安全修复全记录

本文以 demos/CHANGELOG.md 为主体，逐条解读 tiptap 官方演示站点（tiptap-demos）包从 2.0.0-beta 一路演进到 3.0.3 的关键变更记录，并结合 demos/package.json、pack.config.mts 及 packages/ 下的相关源码，说明每条变更背后的实际影响——构建产物格式变化、UMD 产物下线、Link 扩展 shouldAutoLink 选项、Selection 扩展失焦高亮修复、KaTeX 版本兼容等。读完本文，你可以快速判断当前 demos 仓库所处的版本状态，理解 tiptap 3.0 构建链迁移到 tsup 后对产物的影响，并掌握在本地运行/构建这套官方演示站点的具体命令与前提条件。

一、demos 包的定位与基本事实

demos/CHANGELOG.md 记录的是 demos/ 目录下 tiptap-demos 包的变更历史。从 demos/package.json 可以看到该包当前的核心事实：

• 包名为 tiptap-demos，当前版本 3.0.3，且标记为 "private": true——它是仓库内部用于承载官方示例的站点包，不对外发布；
• 运行脚本为：start（vp dev --host）、start:e2e（vp dev --host --port 4080，供端到端测试使用）、build:demos（vp build）、preview（vp preview），全部基于 vite-plus（命令前缀 vp）；
• 依赖体现了 demos 站的“全景性”：同时引入 @hocuspocus/provider、yjs（协作编辑）、lexical/@lexical/react（跨框架对比教程）、shiki/highlight.js/lowlight（代码高亮）、katex（公式渲染）、全套 prosemirror-* 包（底层直接演示），以及 react 19、vue 3.5、svelte 5 三个前端框架，这正是 CHANGELOG 中大量 "demos 依赖升级" 条目的来源。

根目录 package.json 则给出了整套 monorepo 的运行前提：engines.node >= 24、packageManager: pnpm@11.2.2，以及 start、build:demos、serve（构建后用 http-server 在 3000 端口静态托管）等编排脚本。

二、一份 CHANGELOG，两套变更记录体系

通读 demos/CHANGELOG.md 可以发现，该文件实际上由两套不同的变更记录格式拼接而成，这本身就是一条有价值的信息：

1. 新版 changesets 风格（文件上半部分，3.0.x ～ 2.4.2）：每条以短哈希 + 描述组成，如 - a1c6243: Allow KaTeX 0.17，并按 ### Patch Changes / ### Minor Changes / ### Major Changes 分组。这与根 package.json 中引入的 @changesets/cli、changeset 与 changelog 脚本（node ./scripts/aggregate-changeset.js）相对应，说明仓库已将版本管理迁移到 changesets 工作流；
2. 旧版 conventional-changelog 风格（文件下半部分，2.4.0 及更早）：带发布日期、commit 链接，大量出现 **Note:** Version bump only for package tiptap-demos——即这些版本 bumps 本身没有 demos 专属改动，只是 monorepo 统一版本号联动产生的占位条目；文件末尾还注明遵循 Conventional Commits 规范。

对使用者的实际意义是：当你在 2.4.0 之后的历史中只看到 "Version bump only" 时，真正的内容变化需要去对应包的 CHANGELOG 里找；而 2.4.2 之后的条目则是实打实记录在 demos 包自身名下的变更。

三、3.0 系列：构建体系切换与两项修复（3.0.0 → 3.0.3）

3.0.0 / 3.0.1：迁移到 tsup 构建，UMD 产物下线

CHANGELOG 中 3.0.0-next.0、3.0.0-next.1、3.0.1 三个版本均重复出现了同一条 Major 变更（哈希 a92f4a6）：

We are now building packages with tsup which does not support UMD builds, please repackage if you require UMD builds.

这条变更的含义在仓库中有直接的代码佐证。pack.config.mts 是各 @tiptap/* 包打包的共享配置，其中明确只输出两种格式：

export const basePackConfig = (): PackUserConfig => ({
  tsconfig: '../../tsconfig.build.json',
  outDir: 'dist',
  dts: { sourcemap: true },
  clean: true,
  sourcemap: true,
  target: 'es2019',
  format: ['esm', 'cjs'], // 仅 ESM + CJS，无 UMD
  outExtensions: tsupCompatibleExtensions,
})

文件头部的注释也直接点明：输出文件名刻意对齐 tsup 的命名（ESM 为 index.js/index.d.ts，CJS 为 index.cjs/index.d.cts），以保证已发布的 package.json 中 main/module/types/exports 字段继续可用——packages/extension-mathematics/package.json 等包的 exports 映射（./dist/index.js / ./dist/index.cjs）正是这一约定的落地。因此对 tiptap 3.x 的结论是：官方产物只提供 ESM 与 CJS，需要 UMD（例如直接 <script> 标签引入）的使用者必须自行重新打包，这一点在 demos 包中同样生效。

同版本还有两条 Patch 变更：

• 89bd9c7：强制 type-only imports，让打包器在生成 dist/index.js 时忽略 TypeScript 类型导入。这保证了运行时产物中不会出现 import type 残留，属于构建正确性问题；
• 8c69002：Synced beta with stable features，该条同时出现在 3.0.0-beta.1 与 3.0.1，说明 3.0.1 的正式版与 beta 通道在功能上做了对齐，beta 用户可直接升级到稳定版。

3.0.2：Selection 扩展的多行选区高亮越界修复

3.0.2 的 Patch 变更（75e8404）：

Fix the Selection extension highlighting beyond the selected text on multi-line selections: the native browser selection is now hidden while the editor is blurred, so only the styled .selection decoration is shown.

即修复 Selection 扩展在多行选区时高亮“溢出”所选文字的问题：当编辑器失焦时隐藏浏览器原生选区，只显示带样式的 .selection 装饰。该修复的当前实现可在 packages/extensions/src/selection/selection.ts 中完整印证：

• shouldSyncDomSelection 判断是否需要同步 DOM 选区（非空选区、非节点选区、编辑器可编辑）；
• shouldPreserveSelection 在编辑器失焦且未拖拽时返回 true，此时 decorations 插件属性为选区生成 Decoration.inline(from, to, { class: options.className })，默认类名 selection（见 addOptions 的 className: 'selection'）；
• handleDOMEvents.blur 中调用 clearDomSelection()（window.getSelection()?.removeAllRanges()）清除原生选区，focus 中再通过 requestAnimationFrame + view.focus() 恢复。

测试用例 packages/extensions/tests/selection.spec.ts 中验证了失焦状态下 editor.view.dom.querySelector('.selection') 应存在，可作为该行为的验收依据。

3.0.3：允许 KaTeX 0.17

当前最新版本 3.0.3（与 demos/package.json 中 "version": "3.0.3" 一致）只有一条变更（a1c6243）：Allow KaTeX 0.17。

这条变更的直接受益者是数学公式扩展：查看 packages/extension-mathematics/package.json 可以看到，其对 KaTeX 的 peer 依赖已放宽为 "katex": "^0.16.4 || ^0.17.0 || ^0.18.0"，而 demos 包自身依赖的则是 "katex": "^0.18.0"。也就是说，demos 仓库的这条 changelog 记录的是公式示例在 KaTeX 0.17/0.18 下验证通过的版本兼容进展。

四、2.5 系列：类型产物瘦身与 Link 扩展安全/自动链接选项

2.5.0：打包不再包含 tiptap 依赖的类型定义

2.5.0 的 Minor 变更（6834a7f）：Bundling of packages no longer includes tiptap dependency type definitions。即各扩展包构建出的 .d.ts 不再把 tiptap 相关依赖的类型定义一并卷进去，减少类型产物的体积与重复。这与上文 89bd9c7（强制 type imports）属于同一方向上的产物治理：3.0 之后，各包只携带自身类型的声明（对照 packages/extension-mathematics/package.json 中 types 指向单一 dist/index.d.ts，dts 构建开启 sourcemap 但入口唯一）。

2.5.1：Link 扩展 validate 与 shouldAutoLink 的分工

2.5.1（7619215）记录了一次 API 语义调整：

The link extension's validate option now applies to both auto-linking and XSS mitigation. While, the new shouldAutoLink option is used to disable auto linking on an otherwise valid url.

当前源码 packages/extension-link/src/link.ts 完整体现了这一设计：

• validate 已被标注 @deprecated，文档注释要求改用 shouldAutoLink；
• 在扩展初始化处（约 L230-L234），若用户只配置了 validate 而未配置 shouldAutoLink，代码会把 validate 复制给 shouldAutoLink，并输出弃用警告 The 'validate' option is deprecated. Rename to the 'shouldAutoLink' option instead.——即旧配置保持向后兼容；
• 默认选项（L255-L294）给出了两者的默认值与分工：validate: url => !!url（空串不合法），而默认 shouldAutoLink 实现了较细的自动链接判定：带显式协议（https:// 等）的直接通过；裸 IP（127.0.0.1）、无 TLD 的单词主机名（localhost、myserver）不自动链接，但加协议后允许（http://localhost、ftp://myserver 通过）；
• shouldAutoLink 还被传给自动链接插件与粘贴处理器（L527、L548 附近），因此该选项同时约束输入时自动链接与粘贴链接两个入口。

测试文件 packages/extension-link/tests/link.spec.ts 的 shouldAutoLink 用例覆盖了上述全部边界：拒绝裸主机名、拒绝裸 IP、允许自定义 () => true 覆盖默认行为等，是理解该选项语义的最可靠材料。

2.5.2：升级 prosemirror-tables 修复只读编辑器的可缩放单元格

2.5.2（98fffbb）：Upgraded prosemirror-tables to 1.6.3 to fix cells being resizable while the editor is uneditable——升级 prosemirror-tables 至 1.6.3，修复编辑器处于不可编辑状态时表格单元格仍可拖拽缩放的问题。demos 站中当前锁定的版本是 prosemirror-tables ^1.8.5（见 demos/package.json），说明该依赖在后续版本中持续跟进。

五、2.4.x：低依赖声明与一次审慎的“回滚”

2.4.2：lowlight 声明为 peerDependency 并升级到 v3

2.4.2（d6e56c4）：declare lowlight to be a peer dep of extension-code-block-lowlight, update usage to v3。在 packages/extension-code-block-lowlight/package.json 中可以确认最终形态：peerDependencies 为 "lowlight": "^2 || ^3"、"highlight.js": "^11"，同时 devDependencies 用 lowlight ^3.3.0 做开发期验证——低依赖下沉给使用者后，包自身对 lowlight 2.x/3.x 双版本保持兼容。demos 站依赖的正是 lowlight ^3.3.0。

2.4.1：Vue 3 性能优化的回滚

2.4.1（85d21ca）记录了一次值得注意的工程决策：Updated demos and reverted vue specific performance enhancements until we know they work，并引用了两个 revert commit，分别撤销了 vue-3 的“faster component rendering (#5206)”与“fix editor.state updating too late during a transaction (#5252)”。对读者的启示是：demos 包的 changelog 不只记录“加了什么”，也如实记录“撤回了什么”及其原因（验证不充分），这类条目在升级排查时尤其重要。

六、2.4.0 及更早：联动版本 bump 与真实修复的甄别

文件下半部分（conventional-changelog 风格）从 [2.4.0] 追溯到 2.0.0-beta 早期，可以提炼出以下有实质内容的节点（其余 "Version bump only" 条目略过）：

版本	变更类型	内容（哈希/issue）
2.4.0 (2024-05-14)	版本 bump	仅 tiptap-demos 联动升级
2.3.2 (2024-05-08)	Bug Fix	NodePos querySelectorAll 函数修复（#5094）
2.3.0 (2024-04-09)	Bug Fix + Feature	core: 修复 nodepos 子节点查找（#5038）；core: insertContent 系列方法应用 input/paste rules（#5046）
2.2.0 (2024-01-29)	Bug Fix	elementFromString 引入多余换行（#4767）、insertContent 换行剥离、修复 imports 并解除 y-prosemirror 版本钉住
2.2.0-rc.0	Feature	placeholder 允许 editor-is-empty class 作用于任意节点（#4335）
2.1.16	Bug Fix	elementFromString 换行问题（#4767，与 2.2.0 同源修复的正式线版本）
2.1.15	Bug Fix	insertContentAt 保留 HTML 内容中的换行（#4465）、link 测试修复
2.1.14	Bug Fix	typography：分隔符后需空格，避免破坏日期格式（#4696）
2.1.2 (2023-08-17)	Bug Fix	core: 合并 class 属性时的报错修复（#4340）
2.0.2 (2023-04-03)	Feature	协作 demo 加 box-shadow、新增 landing page demo、collab demo 样式

其中与 demos 站直接相关的还有 2.1.0-rc.13 的两条 demos: 前缀修复（补漏 extensions、更新依赖）以及 2.1.0-rc.5 的 add tiptap class。

七、2.0.0-beta 时期：demos 站依赖的核心能力如何成形

CHANGELOG 中 2.0.0-beta 的长列表（beta.193 ～ beta.220）其实是 tiptap 2.0 重构期间的完整留痕，其中多条能力至今仍是 demos 站示例的基础：

• beta.210：**pm:** new prosemirror package for dependency resolving（f387ad3）——引入统一的 @tiptap/pm 包解决 prosemirror 依赖解析问题。当前仓库 packages/pm/ 下按 state/view/model/tables/keymap 等分目录组织，根 tsconfig.json 中 paths 将 @tiptap/pm/* 映射到 packages/pm/*/index.ts，demos 的 demos/vite.config.ts 也对 packages/pm 做了同样的逐包别名处理，这条 beta 变更是理解整个 monorepo 依赖拓扑的起点；
• beta.219：core 修复 destroyed view 在 dispatchTransaction 上的报错（#3799），并允许 insertContentAt/insertContent 接受 text node 数组（#3790）；同版引入 Ability to preserve marks on lists（#3540/#3541）；
• beta.193（大版本节点） 集中记录了一批后来成为标准 API 的能力：
  • Add extension storage（#2069）——扩展私有存储，对应 core 中 extensionStorage 相关实现与测试（packages/core/__tests__/extensionStorage.spec.ts）；
  • add getText() and generateText()（#1428/#1875）——纯文本输出，对应 packages/core/__tests__/generateText.spec.ts；
  • Add support for autolink（#2226）与 link extension: add validate option（#2779）——即上文 2.5.1 中 validate/shouldAutoLink 机制的起点；
  • Integrate input rules and paste rules into the core（#1997）——输入/粘贴规则进入核心；
  • new youtube embed extension（#2814）、CharacterCount 扩展改进等。

这些条目说明：demos 站的 CHANGELOG 虽以“演示包”名义发布，但通过 monorepo 联动，实际上镜像了 tiptap 核心 API 的成型过程。

八、本地运行与验证：把 changelog 中的变更跑起来

结合 demos/package.json 与根 package.json，在本地验证上述版本行为的标准路径是：

1. 环境前提：Node.js >= 24，使用仓库指定的 pnpm@11.2.2 安装工作区依赖；
2. 启动演示站：仓库根执行 pnpm start（等价于对 ./demos 过滤执行 vp dev --host），开发服务默认监听 3000 端口（见 demos/vite.config.ts 中 server.port: 3000）；
3. 构建/预览：pnpm build:demos 构建全部示例页面（demos/vite.config.ts 以 fast-glob 收集 ./**/index.html 作为多入口，并按 JS/Vue/React/Svelte 目录后缀自动注入对应 setup/*.ts 引导脚本），pnpm serve 则构建后用 http-server 在 3000 端口静态托管 demos/dist；
4. 端到端测试：pnpm test:e2e 使用 Playwright 的 chromium 项目运行，demos 侧 start:e2e 脚本以 4080 端口起服务配合；
5. 对照验证 changelog 条目：例如验证 3.0.2 的 Selection 修复，可查看 packages/extensions/tests/selection.spec.ts；验证 2.5.1 的自动链接语义，查看 packages/extension-link/tests/link.spec.ts 中 shouldAutoLink 分组；验证构建产物格式（无 UMD、ESM/CJS 双产物），查看 pack.config.mts 与各包 package.json 的 exports 字段。

九、小结：这份 CHANGELOG 能告诉你什么

• demos/CHANGELOG.md 是 tiptap-demos 包的完整版本档案，当前版本 3.0.3，采用 changesets（新版）与 conventional-changelog（旧版）双格式拼接，"Version bump only" 条目是 monorepo 联动升版的占位；
• 3.0 线的关键事实：构建切换至 tsup，产物仅 ESM + CJS、无 UMD（pack.config.mts 可佐证），类型导入强制 type-only，beta 与 stable 功能对齐；
• 可直接复用的行为修复：Selection 扩展失焦高亮越界（packages/extensions/src/selection/selection.ts）、Link 扩展 validate 弃用并被 shouldAutoLink 取代（packages/extension-link/src/link.ts）、prosemirror-tables 只读时单元格可缩放问题；
• 依赖兼容信号：KaTeX 放宽至 ^0.16.4 || ^0.17.0 || ^0.18.0（packages/extension-mathematics/package.json）、lowlight peer 化且兼容 v2/v3（packages/extension-code-block-lowlight/package.json）；
• 工程文化信号：2.4.1 中对 Vue 3 性能优化的回滚记录表明该文件如实保留“撤回型”变更，升级排障时应重点检索此类条目。