feat(ssr): inject fallback reason to html (#7053)

await-ovo · web-flow · commit c964f072a72b · 2025-04-16T20:13:47.000+08:00
diff --git a/.changeset/quick-mayflies-sort.md b/.changeset/quick-mayflies-sort.md
@@ -0,0 +1,6 @@
+---
+'@modern-js/server-core': patch
+---
+
+feat(ssr): inject fallback reason to html
+feat(ssr): 注入降级原因到响应的 html
diff --git a/packages/server/core/src/plugins/render/render.ts b/packages/server/core/src/plugins/render/render.ts
@@ -146,8 +146,8 @@ export async function createRender({
       forMatchpathname,
       matchEntryName,
     );
-    const framework = metaName || 'modern-js';
-    const fallbackHeader = `x-${cutNameByHyphen(framework)}-ssr-fallback`;
+    const framework = cutNameByHyphen(metaName || 'modern-js');
+    const fallbackHeader = `x-${framework}-ssr-fallback`;
     let fallbackReason = null;
 
     const fallbackWrapper: FallbackWrapper = async (reason, error?) => {
@@ -227,13 +227,27 @@ export async function createRender({
       onTiming,
     };
 
+    if (fallbackReason) {
+      renderOptions.html = injectFallbackReasonToHtml({
+        html: renderOptions.html,
+        reason: fallbackReason,
+        framework,
+      });
+    }
+
     let response: Response;
 
     switch (renderMode) {
       case 'data':
         response =
           (await dataHandler(req, renderOptions)) ||
-          (await renderHandler(req, renderOptions, 'ssr', fallbackWrapper));
+          (await renderHandler(
+            req,
+            renderOptions,
+            'ssr',
+            fallbackWrapper,
+            framework,
+          ));
         break;
       case 'rsc-tree':
         response = await renderRscHandler(req, renderOptions);
@@ -248,6 +262,7 @@ export async function createRender({
           renderOptions,
           renderMode,
           fallbackWrapper,
+          framework,
         );
         break;
       default:
@@ -266,6 +281,7 @@ async function renderHandler(
   options: SSRRenderOptions,
   mode: 'ssr' | 'csr',
   fallbackWrapper: FallbackWrapper,
+  framework: string,
 ) {
   let response: Response | null = null;
 
@@ -318,7 +334,14 @@ async function renderHandler(
     } catch (e) {
       options.onError(e as Error, ErrorDigest.ERENDER);
       await fallbackWrapper('error', e);
-      response = csrRender(options.html);
+
+      response = csrRender(
+        injectFallbackReasonToHtml({
+          html: options.html,
+          reason: 'error',
+          framework,
+        }),
+      );
     }
   } else {
     response = csrRender(options.html);
@@ -374,6 +397,19 @@ async function getRenderMode(
   }
 }
 
+function injectFallbackReasonToHtml({
+  html,
+  reason,
+  framework,
+}: {
+  html: string;
+  reason: FallbackReason;
+  framework: string;
+}) {
+  const tag = `<script id="__${framework}_ssr_fallback_reason__" type="application/json">${JSON.stringify({ reason })}</script>`;
+  return html.replace(/<\/head>/, `${tag}</head>`);
+}
+
 function csrRender(html: string): Response {
   return new Response(html, {
     status: 200,
diff --git a/packages/server/core/tests/fixtures/render/ssr/bundles/main.js b/packages/server/core/tests/fixtures/render/ssr/bundles/main.js
@@ -1,4 +1,7 @@
-export function requestHandler() {
+export function requestHandler(request) {
+  if (request.headers.get('x-render-error')) {
+    throw new Error('custom render error');
+  }
   return new Response('SSR Render', {
     headers: {
       'content-type': 'text/html; charset=UTF-8',
diff --git a/packages/server/core/tests/fixtures/render/ssr/index.html b/packages/server/core/tests/fixtures/render/ssr/index.html
@@ -1,3 +1,11 @@
-<body>
-  <h3>Hello Modern</h3>
-</body>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Document</title>
+  </head>
+  <body>
+    <h3>Hello Modern</h3>
+  </body>
+</html>
diff --git a/packages/server/core/tests/plugins/render.test.ts b/packages/server/core/tests/plugins/render.test.ts
@@ -121,6 +121,11 @@ describe('should render html correctly', () => {
       },
     );
     expect(html2).toMatch(/Hello Modern/);
+    expect(
+      html2.includes(
+        `<script id="__modern_ssr_fallback_reason__" type="application/json">{"reason":"query"}</script>`,
+      ),
+    ).toBe(true);
     expect(fallbackHeader).toBe('1;reason=query');
 
     const html3 = await Promise.resolve(
@@ -138,6 +143,11 @@ describe('should render html correctly', () => {
       return res.text();
     });
     expect(fallbackHeader).toBe('1;reason=header');
+    expect(
+      html3.includes(
+        `<script id="__modern_ssr_fallback_reason__" type="application/json">{"reason":"header"}</script>`,
+      ),
+    ).toBe(true);
     expect(html3).toMatch(/Hello Modern/);
 
     // custom fallback reason in header.
@@ -156,6 +166,11 @@ describe('should render html correctly', () => {
       return res.text();
     });
     expect(fallbackHeader).toBe('1;reason=header,custom fallback reason');
+    expect(
+      html4.includes(
+        `<script id="__modern_ssr_fallback_reason__" type="application/json">{"reason":"header,custom fallback reason"}</script>`,
+      ),
+    ).toBe(true);
     expect(html4).toMatch(/Hello Modern/);
   });
 
@@ -173,4 +188,35 @@ describe('should render html correctly', () => {
     const text2 = await response2.text();
     expect(text2).toBe('handle user');
   });
+
+  it('should fallback to csr when render error', async () => {
+    const ssrPwd = path.join(pwd, 'ssr');
+    const server = await createSSRServer(ssrPwd, {
+      ssr: {
+        forceCSR: true,
+      },
+    });
+    let fallbackHeader;
+    // custom fallback reason in header.
+    const html = await Promise.resolve(
+      server.request(
+        '/',
+        {
+          headers: new Headers({
+            'x-render-error': '1',
+          }),
+        },
+        {},
+      ),
+    ).then(res => {
+      fallbackHeader = res.headers.get('x-modern-ssr-fallback');
+      return res.text();
+    });
+    expect(fallbackHeader).toBe('1;reason=error');
+    expect(
+      html.includes(
+        `<script id="__modern_ssr_fallback_reason__" type="application/json">{"reason":"error"}</script>`,
+      ),
+    ).toBe(true);
+  });
 });
