[RFC] 优化 SSR 及 SSG 下的 HTML 生成

[PeachScript]

问题

目前 Umi 中的 HTML 生成一共有 4 套之多，分别是：

1. SPA 普通构建的 HTML 生成：聚合 headScripts、scripts、styles、links、metas、favicons 配置项，内部生成默认 HTML 内容，再调用 modifyHTML 钩子，最后输出文件
2. SPA SSR 构建的 HTML 生成：由 umi.server.js 产物的 middleware 返回 HTML，内容由 server 的默认 HTML 内容 + metadataLoader 的内容组成
3. SPA SSG 构建的 HTML 生成：前半部分同 1，在 modifyExportHTMLFiles 阶段通过 umi.server.js 获取对应路由的预渲染内容，然后将 helmet 的片段、body 中的片段以及 html 之后的模板片段拼接到 1 的结果上
4. MPA 构建的 HTML 生成：由 HtmlWebpackPlugin 直接生成

该 RFC 只看前 3 种，它们在 HTML 生成的行为差异大致如下：

类别	支持配置项	支持插件 API	支持 metadataLoader	React 渲染根节点
SSR	❌	❌	✅	html
普通构建（client）	✅	✅	❌	#root
SSG (server)	✅	✅	✅	html

上述差异主要会导致 3 个问题：

1. 在 SSR 场景下，用户配置和插件 API 都无法影响 HTML 生成
2. 在 SSG 场景下，由于构建时预渲染的根节点（server）和 普通构建（client）渲染的根节点不同，会导致 React 的 useId 值不同导致水合失败
3. 在 SSG 场景下无法支持 dev，因为 dev 也是基于 SSR umi.server.js 提供的 middleware，其 HTML 产物内容和 SSG 不一致

对于问题 2， @MadCcc 最初在 #12002 做了反向尝试，即把 SSG 渲染的根节点从 html 换成 #root，后来发现 React 官方是要求流从是一整个 HTML，转而采用正向方案，即 client 渲染也从 html 开始的方案，目前仍存在 html lang 不一致的警告，详情可查看 #12002 。

解决方案

整体思路是尽可能地对齐 SSR 及 SSG/client 的行为，大致如下：

类别	支持配置项	支持插件 API	支持 metadataLoader	React 渲染根节点
SSR	✅	❌	✅	html
普通构建（CSR）	✅	❌	❌	html（SSG & SSR only）
SSG (SSR)	✅	⚠️	✅	html

主要做 3 点改造：

1. SSR 支持 HTML 相关的静态配置项（scripts & etc.），把配置值一起打进 umi.server.js
2. SSR 开启时 ban 掉 modifyHTML 钩子，如果用到打出 warning
3. SSR 开启且没开 exportStatic 时 ban 掉 modifyExportHTMLFiles 钩子，如果用到打出 warning
4. SSG 的基础 HTML 从框架生成的 HTML 改为 SSR 生成的 HTML，避免影响水合（目前是反过来的，把 SSR 的内容往默认 HTML 里灌），且 SSG 仍然提供 modifyExportHTMLFiles，但里面理论上只插入对水合无副作用的内容，比如 head 中的标签，或者 body 里的 script
5. CSR 在 hydrate 时将 React 渲染根节点切换为 html，套空的 html 组件确保结构与 SSR 一致、不会影响注水即可

新方案的已知问题：

1. modifyExportHTMLFiles 仅在 SSG 时执行，可能造成水合失败，需要用户自己保证
2. metadataLoader 仅在 SSR 时执行，所以可能造成水合警告，需要用户自己保证（比如自定义了 lang 导致 SSR/CSR 渲染结果不一致，但不会影响水合结果）

以下为细分的改造点。

SSR 支持 HTML 相关的静态配置项

对于 head 中的配置项，getClientRootComponent 已有的 metadata 数据应该可以描述，思路：

1. server.tpl 里把相关配置序列化成 metadata 配置项，传给 requestHander 和 generator，关键位置：

   umi/packages/preset-umi/templates/server.tpl

   Line 43 in 8d55ffb

   const createOpts = {

2. generator 生成 metadata 时从 opts.metadata 读取作为默认值，注意解引用，关键位置：

   umi/packages/server/src/ssr.ts

   Line 108 in 60896f5

   const metadata: Record<string, any> = {};

对于 body 中的配置项，只能给 getClientRootComponent 新增 scripts 配置项了，思路：

1. 新增并消费 scripts 数据，关键位置：

   umi/packages/renderer-react/src/server.tsx

   Line 20 in e63fed3

   export async function getClientRootComponent(opts: IHtmlProps) {

2. 剩余思路省略，和上面类似

ban 掉 API

ssr 启用时 ban 掉 modifyHTML，关键位置：

umi/packages/preset-umi/src/commands/dev/getMarkupArgs.ts

Lines 42 to 51 in c068d9a

	let $ = cheerio.load(memo, {
	// @ts-ignore
	decodeEntities: false,
	});
	$ = await opts.api.applyPlugins({
	key: 'modifyHTML',
	initialValue: $,
	args,
	});
	let html = $.html();

1. 通过 opts.api.config.ssr 可以判断 ssr 配置项是否开启
2. 通过 opts.api.service.hooks.modifyHTML?.length 可以判断是否有其他插件注册了这个 API，有的话抛出警告

ssr 启用但 exportStatic 未启用时 ban 掉 modifyExportHTMLFiles，关键位置：

umi/packages/preset-umi/src/commands/build.ts

Lines 185 to 194 in 13dd25b

	htmlFiles = await api.applyPlugins({
	key: 'modifyExportHTMLFiles',
	initialValue: [
	{
	path: 'index.html',
	content: await getMarkup(finalMarkUpArgs),
	},
	],
	args: { markupArgs: finalMarkUpArgs, getMarkup },
	});

步骤省略，和上面类似

SSG 的基础 HTML 改为 SSR 的结果

在 exportStatic 中，原逻辑是基于框架默认的 HTML 骨架，把 SSR HTML 结果中的 Helmet、body 和 html 外的模板 3 个部分插入到默认 HTML 中，但只要有换行之类的问题都会导致水合失败，所以这次尝试直接用 SSR 的 HTML 产物：

1. 把处理相对路径 publicPath 的逻辑都挪到『SSR 支持 HTML 相关的静态配置项』的改造里，确保配置项生成的时候已经处理过相对路径了，关键位置：

   umi/packages/preset-umi/src/features/exportStatic/exportStatic.ts

   Lines 162 to 220 in 60896f5

   	// handle relative publicPath, such as `./`
   	if (publicPath.startsWith('.')) {
   	assert(
   	api.config.runtimePublicPath,
   	'`runtimePublicPath` should be enable when `publicPath` is relative!',
   	);
   	const rltPrefix = relative(dirname(file), '.');
   	// prefix for all assets
   	if (rltPrefix) {
   	// HINT: clone for keep original markupArgs unmodified
   	const picked = lodash.cloneDeep(
   	lodash.pick(markupArgs, [
   	'favicons',
   	'links',
   	'styles',
   	'headScripts',
   	'scripts',
   	]),
   	);
   	// handle favicons
   	picked.favicons.forEach((item: string, i: number) => {
   	if (item.startsWith(publicPath)) {
   	picked.favicons[i] = winPath(join(rltPrefix, item));
   	}
   	});
   	// handle links
   	picked.links.forEach((link: { href: string }) => {
   	if (link.href?.startsWith(publicPath)) {
   	link.href = winPath(join(rltPrefix, link.href));
   	}
   	});
   	// handle scripts
   	[picked.headScripts, picked.scripts, picked.styles].forEach(
   	(group: ({ src: string } | string)[]) => {
   	group.forEach((script, i) => {
   	if (
   	typeof script === 'string' &&
   	script.startsWith(publicPath)
   	) {
   	group[i] = winPath(join(rltPrefix, script));
   	} else if (
   	typeof script === 'object' &&
   	script.src?.startsWith(publicPath)
   	) {
   	script.src = winPath(join(rltPrefix, script.src));
   	}
   	});
   	},
   	);
   	// update markupArgs
   	markupArgs = Object.assign({}, markupArgs, picked);
   	}
   	}

2. 把 async script 的处理逻辑也挪到『SSR 支持 HTML 相关的静态配置项』的改造里，关键位置：

   umi/packages/preset-umi/src/features/exportStatic/exportStatic.ts

   Lines 154 to 160 in 60896f5

   	if (api.config.ssr && prerender) {
   	markupArgs.scripts.forEach((script: any) => {
   	if (script.src) {
   	script.async = true;
   	}
   	});
   	}

3. getPreRenderedHTML 移除对 htmlTpl 的依赖，直接返回预渲染的内容作为 HTML，它已经是完整的了

CSR hydrate 从 html 开始

已在 #12002 跟进，在 hydrate 时走特殊逻辑，套上 HTML 外壳确保和 SSR 的结构一致，diff：https://github.com/umijs/umi/pull/12002/files#diff-b555a0512a6215972d217c16fb3b0b0389d4c8c1654d15609cbd0c0c7d8f26f1L339-R345

[MadCcc]

2. SSR 开启时 ban 掉 modifyHTML 钩子，如果用到打出 warning

这个是不是可以像 nextjs 一样提供 RootLayout 定制组件，让用户自定义 Html 这个组件来达成 modifyHTML 想要做的事情？

[fz6m]

1. 渲染节点：参考 fix(ssr): render same root in server #12002 (comment) 我这个回复里，我认为 hydrate 节点应该和社区一致，从 root 的 react app 开始，而不是整个 html ，因为 html 里有啥我们不确定，并且还有 loaderData ，那我们如何在客户端 browser 代码里找到 loaderData ：

   // 在 browser 环境中
   
     ReactDOM.hydrateRoot(
         document,
         // ↓ 此处需要知道 loaderData 
         <Html {...opts}>
           <Browser />
         </Html>,
       );

   但如果是 react root 节点就没有这些问题了。

   我认为无论什么场景，都应该从 react root 节点开始 hydrate ，需要考虑的就是调整 render 节点可能会发生 Breaking change 。

2. ssr 可以以插件方式介入渲染流程：现在不管是 ssr 还是用于 dumi 的 ssg ，都无法通过插件介入修改 stream ，需要一种机制去在插件中介入并修改，从而实现 antd 的 ssr ，实现 helment 抽取，实现 styled-components 的 ssr 抽取；现在 helment 耦合在 umi 代码内部，我认为是不清真的，这个功能应该以插件方式提供，并且像 styled-components 的插件也可以添加 ssr 的干预逻辑，从而在 stream 阶段去提取 SC 的样式，不然像现在 umi 官方文档站点一样是无法使用 SC 的，因为没法干预到 ssr 的过程。

以上这两个问题是我认为现在 umi 4 的 ssr 存在的最大问题。

[PeachScript]

周四有空的话我们 Umi 周会上简单过一下这个 RFC？