Plate Slate v2 Tranche 2 执行复盘React 19.2 与 Next 16 兼容性升级实战【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文是 Plate 仓库 Slate v2 迁移计划中 Tranche 2 执行记录的深度解读。该 Tranche 的核心目标是在不改变任何编辑器行为语义的前提下将控制仓库plate-2与执行仓库slate-v2的运行时与站点基线整体升级到 React 19.2 与 Next 16并同时处理升级带来的依赖、配置与源码类型连锁影响。读者读完本文后将掌握这次升级的完整决策链路、站点配置适配要点、React 19 类型层面的三类修复模式、以及一套可复用的构建 → 类型检查 → 代码规范 → 测试验证流水线可直接迁移到自己的 Next React 大型 monorepo 升级场景中。本文以 docs/plans/2026-04-16-slate-v2-tranche-2-execution.md 为骨架结合当前仓库中 package.json、apps/www/package.json、apps/www/next.config.ts 等真实配置与源码展开。一、Tranche 2 在 Slate v2 迁移计划中的定位Slate v2 的迁移被组织为一系列顺序执行的 tranche批次车道每个 tranche 只负责一个独立的兼容性/功能面避免把运行时语义改动与依赖升级混在一起。Tranche 2 的定位是runtime/site compatibility lane——即行为保持behavior-preserving的运行时与站点兼容性车道根目录与站点root/site的 React Next 升级这是本车道的主线工作被迫的包/运行时兼容性连带修复forced package/runtime compatibility fallout升级依赖后暴露出的类型与构建问题属于本车道必须处理的范围可选的slate-browser落地只有在确认与当前车道无冲突时才允许顺手合入明确不做引擎语义工作no engine semantics work任何改变编辑器核心行为语义的改动都不得进入本车道。这一划分背后有一条重要的tranche 规则Next 升级属于 Tranche 2而不是 Tranche 1。也就是说依赖基线的整体提升被刻意推迟到专门车道执行保证前序车道只专注于自身主题这也是大型迁移工程中常见的 关注点隔离 实践。执行过程被拆为五个阶段盘点当前仓库与草拟车道 → 选定精确目标版本与受影响文件 → 实施依赖/配置/源码兼容性改动 → 验证安装/构建/类型检查/代码规范/测试 → 按需更新 tranche 文档与台账ledger。五个阶段形成一个可回溯的闭环最终状态记录在本文档中。二、目标版本与影响面Registry TargetsTranche 2 为本次升级选定了精确的 registry 目标版本依赖目标版本react/react-dom19.2.5types/react19.2.14types/react-dom19.2.3next16.2.4需要说明的是文档记录的是 2026-04-16 执行当日的 registry 目标。在当前仓库快照中版本号已发生小幅演进根 package.json 中react/react-dom为19.2.4、types/react为19.2.7、types/react-dom为19.2.3站点侧 apps/www/package.json 中next已推进到16.2.6。这说明 19.2.x / 16.2.x 系列已成为该迁移项目的稳定基线后续 patch 级更新持续跟进而 Tranche 2 确立的 React 19.2 Next 16 组合保持不变。版本选定遵循repair-drift修复漂移原则优先在同路径源码same-path source上修复只允许最小化的强制漂移minimum forced drift。即升级的目标不是引入新特性而是让现有源码在新基线上无行为差异地继续工作。三、站点配置适配 Next 16 的四项关键改动站点site即文档站点应用的 Next 16 适配是本车道的主要工作量之一。升级后对站点配置做了四类改动启用顶层turbopack配置Next 16 的默认构建/开发链路已切换为 Turbopack站点配置相应在顶层声明turbopack字段。TypeScript 配置增加.next/types的 includeNext 16 生成的类型声明被纳入类型检查范围。删除无效的eslint配置Next 16 不再接受next.config.js中的eslint键。不再强制使用 webpack放弃--webpack强制定向让 Next 16 运行在默认的 Turbopack 链路上。在当前仓库的 apps/www/next.config.ts 中可以找到与这些决策呼应的实现痕迹配置顶层存在turbopack字段开发环境下注入resolveAlias将platejs/*与udecode/*等 workspace 包映射到src或dist入口具体由buildWorkspaceDevAliases()依据PLATE_WWW_DEV_SOURCE环境变量决定typescript.ignoreBuildErrors被保留为true原先的webpack自定义块externals、polyfill、NormalModuleReplacementPlugin 等已被整体注释只保留transpilePackages: [ts-morph]与reactCompiler: !isDev等与打包器无关的配置。从源码结构看移除无效 eslint 键、放弃强制 webpack、回归 Turbopack 默认链路 这一改动方向在该配置文件中得到了完整落实。其中移除next.config.js中的eslint键是最容易踩坑的点旧项目迁移到 Next 16 时如果直接带着eslint.ignoreDuringBuilds等旧配置next build会给出 eslint 不再是受支持的 next.config.js 选项 的警告而该警告并不会在旧配置下自动消失必须显式删除。四、React 19 类型落地的三类修复文档明确记录React 19 的类型连锁影响范围很小且局部small and local主要集中在三类问题上修复落在slate-react源码中更严格的useRef初始化stricteruseRefinitializationReact 19 类型对useRef的初始参数与返回类型约束更严空初始值场景必须显式给出类型否则推断为undefined。null 感知的 ref 对象类型null-aware ref object typingref 对象在挂载前的类型为nullReact 19 类型系统要求代码对这些 null 状态进行收窄处理。可编辑输入处理器上的React.InputEvent原本依赖的事件类型需要显式改用React.InputEvent以匹配新的合成事件类型定义。这类 类型收窄 修复是 React 大版本升级中最常见的落地形态——它们不改变任何运行逻辑纯粹是为了让既有的、本来正确的代码通过新版本的类型检查。对于维护者而言这印证了升级时优先跑tsc/typecheck 而非手工逐文件排查的价值类型错误通常已经精确定位到需要改动的位置。五、显式导入映射解决 Next 16 路由打包 .d.ts 文件的经典问题本次升级暴露了一个极具代表性的 Next 16 构建问题示例页面的模板字符串动态导入导致路由打包器把.d.ts声明文件当作运行时模块编译其配套解决方案文档详见 docs/solutions/developer-experience/2026-04-16-next-16-webpack-example-imports-must-use-explicit-maps-and-drop-next-config-eslint.md。症状生产构建在site/examples/ts/custom-types.d.ts上报Module parse failed: Unexpected token导入追溯链指向示例页加载器site/pages/examples/[example].tsx尽管包级 build/typecheck/lint/test 在 React 19.2 下已全部变绿站点构建仍持续红色。根因旧的示例页加载器使用模板字符串动态导入dynamic(() import(../../examples/ts/${path}))模板字符串的导入上下文范围太宽Next 16 的路径分析会把匹配目录下的所有文件包括custom-types.d.ts纳入路由 bundle 的编译范围声明文件自然无法通过模块编译。文档明确指出如果 Next 16 构建开始把.d.ts当作模块解析先检查是否有过宽的动态导入而不是去动声明文件本身。解决方案显式导入映射表将模板字符串动态导入替换为显式 importer map把 bundle 图收窄到真实的示例模块const EXAMPLE_IMPORTERS: Record string, () Promise{ default: React.ComponentType } { richtext: () import(../../examples/ts/richtext), tables: () import(../../examples/ts/tables), // ... } dynamic(EXAMPLE_IMPORTERS[path], { loading: path huge-document ? HugeDocumentLoader : ComponentLoader, })显式映射表让路由打包器只能看见真实存在的示例模块声明文件不再被当作运行时代码。文档特别注明这个修复不会扩大运行时漂移without widening runtime drift与 Tranche 2 的 repair-drift 约束一致。配套的预防规则有三条跨大版本升级时不要无条件沿用旧next.config.js键示例画廊类路由的动态导入优先使用显式映射表遇到.d.ts被解析为模块时先怀疑动态导入宽度。六、验证流水线从安装到全量测试Tranche 2 的完成判定不依赖单点验证而是完整的质量流水线。文档记录的验证命令序列如下在独立执行仓库slate-v2中运行# 1. 依赖安装 pnpm install # 2. 目标包构建串行按 filter 限定影响面 pnpm turbo build --concurrency1 \ --filter./packages/slate \ --filter./packages/slate-history \ --filter./packages/slate-hyperscript \ --filter./packages/slate-dom \ --filter./packages/slate-react # 3. 目标包类型检查 pnpm turbo typecheck --concurrency1 \ --filter./packages/slate \ --filter./packages/slate-history \ --filter./packages/slate-hyperscript \ --filter./packages/slate-dom \ --filter./packages/slate-react # 4. 站点类型检查 pnpm typecheck:site # 5. 全量构建 pnpm build # 6. 代码规范修复与校验 pnpm lint:fix pnpm lint # 7. 全量测试 pnpm test这套流水线体现了 monorepo 升级的三个要点用turbo --filter限定包范围先在小范围内验证核心包slate、slate-history、slate-hyperscript、slate-dom、slate-react的构建与类型避免升级噪音污染全仓--concurrency1串行执行保证构建/类型检查顺序可复现、错误归属清晰lint 与 test 放在最后全量执行确认代码规范与行为在升级后无回归。在当前仓库中这些验证能力被收敛为根 package.json 的聚合脚本pnpm build对应g:buildTurbo 并行构建全部包并在失败时自动降级为串行、pnpm typecheck对应g:typecheck先构建再对包执行--only类型检查、pnpm lint/pnpm lint:fixBiome ESLint 双引擎、pnpm testBun 测试快车道另有test:slow/test:slowest分档以及pnpm check一键串联 lint、typecheck、全部测试。读者在自己仓库复刻这套验证顺序时可直接对照此脚本布局。七、约束执行与完成状态Tranche 2 明确遵守两条硬性约束并在完成时保留一条后续门禁Tranche 规则Next 升级必须归属本车道不得提前在 Tranche 1 完成Repair-drift同路径源码优先只做最小强制漂移Review stop评审暂停点Tranche 完成后仍适用即本车道的合入结果需要经过评审门禁不能直接视作可无限制推进。文档进度记录显示该 Tranche 已执行完毕根目录升级至 React19.2.5与 Next16.2.4站点配置完成 Next 16 适配slate-react的显式 Tranche 2 源码连锁问题已修复显式示例导入映射表已恢复Next 16 不再打包custom-types.d.ts上述七步验证全部通过状态标记为status: complete。从后续路线看Tranche 2 只是 Slate v2 迁移的中间车道后续的 docs/slate-v2/slate-tranche-3-execution.md 记录了packages/slate内核的收尾text-units、transaction-contract、bookmark、normalization 等 proof-owner 文件的落地再往后是slate-history/slate-hyperscript、slate-domTranche 5、slate-reactTranche 6以及示例对齐、根 proof 闭环、overlay/超大文档/局部性基准车道Tranche 7。进度同步会持续反映到 docs/slate-v2/master-roadmap.md、docs/slate-v2/replacement-gates-scoreboard.md 与 docs/slate-v2/release-readiness-decision.md 等控制文档中。八、可迁移的工程经验小结结合 Tranche 2 的执行记录与配套解决方案文档可以提炼出四条适用于任何大型编辑器/富文本仓库做框架大版本升级的经验按车道隔离升级把依赖基线升级、行为语义改动、性能优化拆成独立 tranche每个车道只回答一个问题评审与回滚边界清晰。升级前先确认目标版本升级后先跑类型检查React 19 的类型连锁影响通常是小而局部的useRef初始化、null-aware ref、合成事件类型交给 typecheck 定位即可不必预判所有改动点。Next 大版本升级要主动清点next.config.js键像eslint这类被移除的配置键不会静默忽略必须显式删除同时跟随默认打包器Turbopack迁移而不是强撑 webpack 定制。路由级动态导入用显式映射表模板字符串动态导入会放大路由 bundle 的扫描范围把.d.ts等声明文件误当模块编译显式 importer map 是窄化 bundle 图的标准解法。如果读者正在计划将 React 19.2 / Next 16 引入自己的 monorepo本文档及其引用的站点配置apps/www/next.config.ts与执行记录docs/plans/2026-04-16-slate-v2-tranche-2-execution.md提供了一份可直接对照的完整范本。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plate Slate v2 Tranche 2 执行复盘：React 19.2 与 Next 16 兼容性升级实战
Plate Slate v2 Tranche 2 执行复盘React 19.2 与 Next 16 兼容性升级实战【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文是 Plate 仓库 Slate v2 迁移计划中 Tranche 2 执行记录的深度解读。该 Tranche 的核心目标是在不改变任何编辑器行为语义的前提下将控制仓库plate-2与执行仓库slate-v2的运行时与站点基线整体升级到 React 19.2 与 Next 16并同时处理升级带来的依赖、配置与源码类型连锁影响。读者读完本文后将掌握这次升级的完整决策链路、站点配置适配要点、React 19 类型层面的三类修复模式、以及一套可复用的构建 → 类型检查 → 代码规范 → 测试验证流水线可直接迁移到自己的 Next React 大型 monorepo 升级场景中。本文以 docs/plans/2026-04-16-slate-v2-tranche-2-execution.md 为骨架结合当前仓库中 package.json、apps/www/package.json、apps/www/next.config.ts 等真实配置与源码展开。一、Tranche 2 在 Slate v2 迁移计划中的定位Slate v2 的迁移被组织为一系列顺序执行的 tranche批次车道每个 tranche 只负责一个独立的兼容性/功能面避免把运行时语义改动与依赖升级混在一起。Tranche 2 的定位是runtime/site compatibility lane——即行为保持behavior-preserving的运行时与站点兼容性车道根目录与站点root/site的 React Next 升级这是本车道的主线工作被迫的包/运行时兼容性连带修复forced package/runtime compatibility fallout升级依赖后暴露出的类型与构建问题属于本车道必须处理的范围可选的slate-browser落地只有在确认与当前车道无冲突时才允许顺手合入明确不做引擎语义工作no engine semantics work任何改变编辑器核心行为语义的改动都不得进入本车道。这一划分背后有一条重要的tranche 规则Next 升级属于 Tranche 2而不是 Tranche 1。也就是说依赖基线的整体提升被刻意推迟到专门车道执行保证前序车道只专注于自身主题这也是大型迁移工程中常见的 关注点隔离 实践。执行过程被拆为五个阶段盘点当前仓库与草拟车道 → 选定精确目标版本与受影响文件 → 实施依赖/配置/源码兼容性改动 → 验证安装/构建/类型检查/代码规范/测试 → 按需更新 tranche 文档与台账ledger。五个阶段形成一个可回溯的闭环最终状态记录在本文档中。二、目标版本与影响面Registry TargetsTranche 2 为本次升级选定了精确的 registry 目标版本依赖目标版本react/react-dom19.2.5types/react19.2.14types/react-dom19.2.3next16.2.4需要说明的是文档记录的是 2026-04-16 执行当日的 registry 目标。在当前仓库快照中版本号已发生小幅演进根 package.json 中react/react-dom为19.2.4、types/react为19.2.7、types/react-dom为19.2.3站点侧 apps/www/package.json 中next已推进到16.2.6。这说明 19.2.x / 16.2.x 系列已成为该迁移项目的稳定基线后续 patch 级更新持续跟进而 Tranche 2 确立的 React 19.2 Next 16 组合保持不变。版本选定遵循repair-drift修复漂移原则优先在同路径源码same-path source上修复只允许最小化的强制漂移minimum forced drift。即升级的目标不是引入新特性而是让现有源码在新基线上无行为差异地继续工作。三、站点配置适配 Next 16 的四项关键改动站点site即文档站点应用的 Next 16 适配是本车道的主要工作量之一。升级后对站点配置做了四类改动启用顶层turbopack配置Next 16 的默认构建/开发链路已切换为 Turbopack站点配置相应在顶层声明turbopack字段。TypeScript 配置增加.next/types的 includeNext 16 生成的类型声明被纳入类型检查范围。删除无效的eslint配置Next 16 不再接受next.config.js中的eslint键。不再强制使用 webpack放弃--webpack强制定向让 Next 16 运行在默认的 Turbopack 链路上。在当前仓库的 apps/www/next.config.ts 中可以找到与这些决策呼应的实现痕迹配置顶层存在turbopack字段开发环境下注入resolveAlias将platejs/*与udecode/*等 workspace 包映射到src或dist入口具体由buildWorkspaceDevAliases()依据PLATE_WWW_DEV_SOURCE环境变量决定typescript.ignoreBuildErrors被保留为true原先的webpack自定义块externals、polyfill、NormalModuleReplacementPlugin 等已被整体注释只保留transpilePackages: [ts-morph]与reactCompiler: !isDev等与打包器无关的配置。从源码结构看移除无效 eslint 键、放弃强制 webpack、回归 Turbopack 默认链路 这一改动方向在该配置文件中得到了完整落实。其中移除next.config.js中的eslint键是最容易踩坑的点旧项目迁移到 Next 16 时如果直接带着eslint.ignoreDuringBuilds等旧配置next build会给出 eslint 不再是受支持的 next.config.js 选项 的警告而该警告并不会在旧配置下自动消失必须显式删除。四、React 19 类型落地的三类修复文档明确记录React 19 的类型连锁影响范围很小且局部small and local主要集中在三类问题上修复落在slate-react源码中更严格的useRef初始化stricteruseRefinitializationReact 19 类型对useRef的初始参数与返回类型约束更严空初始值场景必须显式给出类型否则推断为undefined。null 感知的 ref 对象类型null-aware ref object typingref 对象在挂载前的类型为nullReact 19 类型系统要求代码对这些 null 状态进行收窄处理。可编辑输入处理器上的React.InputEvent原本依赖的事件类型需要显式改用React.InputEvent以匹配新的合成事件类型定义。这类 类型收窄 修复是 React 大版本升级中最常见的落地形态——它们不改变任何运行逻辑纯粹是为了让既有的、本来正确的代码通过新版本的类型检查。对于维护者而言这印证了升级时优先跑tsc/typecheck 而非手工逐文件排查的价值类型错误通常已经精确定位到需要改动的位置。五、显式导入映射解决 Next 16 路由打包 .d.ts 文件的经典问题本次升级暴露了一个极具代表性的 Next 16 构建问题示例页面的模板字符串动态导入导致路由打包器把.d.ts声明文件当作运行时模块编译其配套解决方案文档详见 docs/solutions/developer-experience/2026-04-16-next-16-webpack-example-imports-must-use-explicit-maps-and-drop-next-config-eslint.md。症状生产构建在site/examples/ts/custom-types.d.ts上报Module parse failed: Unexpected token导入追溯链指向示例页加载器site/pages/examples/[example].tsx尽管包级 build/typecheck/lint/test 在 React 19.2 下已全部变绿站点构建仍持续红色。根因旧的示例页加载器使用模板字符串动态导入dynamic(() import(../../examples/ts/${path}))模板字符串的导入上下文范围太宽Next 16 的路径分析会把匹配目录下的所有文件包括custom-types.d.ts纳入路由 bundle 的编译范围声明文件自然无法通过模块编译。文档明确指出如果 Next 16 构建开始把.d.ts当作模块解析先检查是否有过宽的动态导入而不是去动声明文件本身。解决方案显式导入映射表将模板字符串动态导入替换为显式 importer map把 bundle 图收窄到真实的示例模块const EXAMPLE_IMPORTERS: Record string, () Promise{ default: React.ComponentType } { richtext: () import(../../examples/ts/richtext), tables: () import(../../examples/ts/tables), // ... } dynamic(EXAMPLE_IMPORTERS[path], { loading: path huge-document ? HugeDocumentLoader : ComponentLoader, })显式映射表让路由打包器只能看见真实存在的示例模块声明文件不再被当作运行时代码。文档特别注明这个修复不会扩大运行时漂移without widening runtime drift与 Tranche 2 的 repair-drift 约束一致。配套的预防规则有三条跨大版本升级时不要无条件沿用旧next.config.js键示例画廊类路由的动态导入优先使用显式映射表遇到.d.ts被解析为模块时先怀疑动态导入宽度。六、验证流水线从安装到全量测试Tranche 2 的完成判定不依赖单点验证而是完整的质量流水线。文档记录的验证命令序列如下在独立执行仓库slate-v2中运行# 1. 依赖安装 pnpm install # 2. 目标包构建串行按 filter 限定影响面 pnpm turbo build --concurrency1 \ --filter./packages/slate \ --filter./packages/slate-history \ --filter./packages/slate-hyperscript \ --filter./packages/slate-dom \ --filter./packages/slate-react # 3. 目标包类型检查 pnpm turbo typecheck --concurrency1 \ --filter./packages/slate \ --filter./packages/slate-history \ --filter./packages/slate-hyperscript \ --filter./packages/slate-dom \ --filter./packages/slate-react # 4. 站点类型检查 pnpm typecheck:site # 5. 全量构建 pnpm build # 6. 代码规范修复与校验 pnpm lint:fix pnpm lint # 7. 全量测试 pnpm test这套流水线体现了 monorepo 升级的三个要点用turbo --filter限定包范围先在小范围内验证核心包slate、slate-history、slate-hyperscript、slate-dom、slate-react的构建与类型避免升级噪音污染全仓--concurrency1串行执行保证构建/类型检查顺序可复现、错误归属清晰lint 与 test 放在最后全量执行确认代码规范与行为在升级后无回归。在当前仓库中这些验证能力被收敛为根 package.json 的聚合脚本pnpm build对应g:buildTurbo 并行构建全部包并在失败时自动降级为串行、pnpm typecheck对应g:typecheck先构建再对包执行--only类型检查、pnpm lint/pnpm lint:fixBiome ESLint 双引擎、pnpm testBun 测试快车道另有test:slow/test:slowest分档以及pnpm check一键串联 lint、typecheck、全部测试。读者在自己仓库复刻这套验证顺序时可直接对照此脚本布局。七、约束执行与完成状态Tranche 2 明确遵守两条硬性约束并在完成时保留一条后续门禁Tranche 规则Next 升级必须归属本车道不得提前在 Tranche 1 完成Repair-drift同路径源码优先只做最小强制漂移Review stop评审暂停点Tranche 完成后仍适用即本车道的合入结果需要经过评审门禁不能直接视作可无限制推进。文档进度记录显示该 Tranche 已执行完毕根目录升级至 React19.2.5与 Next16.2.4站点配置完成 Next 16 适配slate-react的显式 Tranche 2 源码连锁问题已修复显式示例导入映射表已恢复Next 16 不再打包custom-types.d.ts上述七步验证全部通过状态标记为status: complete。从后续路线看Tranche 2 只是 Slate v2 迁移的中间车道后续的 docs/slate-v2/slate-tranche-3-execution.md 记录了packages/slate内核的收尾text-units、transaction-contract、bookmark、normalization 等 proof-owner 文件的落地再往后是slate-history/slate-hyperscript、slate-domTranche 5、slate-reactTranche 6以及示例对齐、根 proof 闭环、overlay/超大文档/局部性基准车道Tranche 7。进度同步会持续反映到 docs/slate-v2/master-roadmap.md、docs/slate-v2/replacement-gates-scoreboard.md 与 docs/slate-v2/release-readiness-decision.md 等控制文档中。八、可迁移的工程经验小结结合 Tranche 2 的执行记录与配套解决方案文档可以提炼出四条适用于任何大型编辑器/富文本仓库做框架大版本升级的经验按车道隔离升级把依赖基线升级、行为语义改动、性能优化拆成独立 tranche每个车道只回答一个问题评审与回滚边界清晰。升级前先确认目标版本升级后先跑类型检查React 19 的类型连锁影响通常是小而局部的useRef初始化、null-aware ref、合成事件类型交给 typecheck 定位即可不必预判所有改动点。Next 大版本升级要主动清点next.config.js键像eslint这类被移除的配置键不会静默忽略必须显式删除同时跟随默认打包器Turbopack迁移而不是强撑 webpack 定制。路由级动态导入用显式映射表模板字符串动态导入会放大路由 bundle 的扫描范围把.d.ts等声明文件误当模块编译显式 importer map 是窄化 bundle 图的标准解法。如果读者正在计划将 React 19.2 / Next 16 引入自己的 monorepo本文档及其引用的站点配置apps/www/next.config.ts与执行记录docs/plans/2026-04-16-slate-v2-tranche-2-execution.md提供了一份可直接对照的完整范本。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考