From ca3df3221d3c1279d64d465f4c575783f1e76496 Mon Sep 17 00:00:00 2001 From: zhangxiang Date: Tue, 20 Oct 2026 08:16:06 +0800 Subject: [PATCH] =?UTF-8?q?fix(motion):=20=E5=86=B7=E9=A6=96=E8=AE=BF?= =?UTF-8?q?=E7=99=BD=E5=B1=8F=E2=80=94=E2=80=94JS=20=E5=B0=B1=E7=BB=AA?= =?UTF-8?q?=E5=89=8D=E5=BC=BA=E5=88=B6=E5=85=A5=E5=9C=BA=E5=85=83=E7=B4=A0?= =?UTF-8?q?=E5=8F=AF=E8=A7=81=EF=BC=8C=E6=B0=B4=E5=90=88=E5=90=8E=E5=86=8D?= =?UTF-8?q?=E4=BA=A4=E8=BF=98=20framer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户反馈「首次访问白屏,需要刷新才可以」。用禁用缓存 + 限速复现并量化: 745ms 时 SSR HTML 已在(正文 1177 字),但 h1 的 opacity 仍为 0; 直到 5945ms 才变 1 ⇒ 冷首访/弱网下 3–5 秒白屏,刷新后脚本已在缓存里所以「刷新就好」。 根因是全站性的:167 处 framer 入场把初始 opacity 内联成 0 (SSR 实测 style="opacity:0;transform:translateY(30px)"),而它只能由 JS 驱动; 页面级 template 的 initial 也是 {opacity:0,y:8}。逐文件改既大又有误伤风险 (面板/轮播的 opacity 是状态语义,不是入场)。 修法(一处兜底 + 一处交接,失败也是敞开的): - globals.css 新增规则:当 html 上没有 data-content-ready 时, 把内联 opacity:0 的入场元素强制为 1(同时匹配 "opacity:0" 与 "opacity: 0" 两种写法)。 JS 尚未执行时内容可见;若脚本永远失败,则永不置位,内容一直可见。 - 营销页 template:水合后 800ms(> 最长入场 280ms + 余量)置位 data-content-ready, 把控制权交还 framer,避免「闪一下」。 回归守卫 e2e/first-paint-visibility.spec.ts: ① 禁用 JS 时 h1 内联仍 opacity:0 但计算值为 1(兜底生效,且证明前提仍在); ② 正常加载时 data-content-ready 置位、交接前后 h1 均为 1。 变异验证:删掉 CSS 规则 ⇒ 2 条全红;恢复 ⇒ 2 条绿。 复算:tsc / type-check:e2e 0、check:visual 0、视觉 chromium-desktop 25/25、reduce 回归 2 绿。 --- e2e/first-paint-visibility.spec.ts | 50 ++++++++++++++++++++++++++++++ src/app/(marketing)/template.tsx | 10 ++++++ src/app/globals.css | 14 +++++++++ 3 files changed, 74 insertions(+) create mode 100644 e2e/first-paint-visibility.spec.ts diff --git a/e2e/first-paint-visibility.spec.ts b/e2e/first-paint-visibility.spec.ts new file mode 100644 index 0000000..563d83b --- /dev/null +++ b/e2e/first-paint-visibility.spec.ts @@ -0,0 +1,50 @@ +import { test, expect } from './fixtures'; + +/** + * 冷首访可见性守卫(2026-10-20)。 + * + * 缺陷原型:全站 framer 入场把初始 opacity 内联成 0(SSR 实测 `style="opacity:0;transform:translateY(30px)"`), + * 只能由 JS 水合后驱动 ⇒ 冷首访/弱网(实测限速下 3–5s)整页白,刷新后才好。 + * 修复用 globals.css 的 `html:not([data-content-ready])` 规则在 JS 就绪前强制可见, + * 营销页 template 在水合后 800ms 置位交还 framer。 + * + * 断言两条,都能失败: + * ① 禁用 JS(等价"脚本没跑起来"):h1 的内联样式仍是 opacity:0,但**计算值必须为 1**; + * ② 正常加载:水合后置位 data-content-ready,且 h1 仍可见(交接不闪回 0)。 + */ +test.describe('首屏可见性(无 JS / 水合交接)', () => { + test('禁用 JS 时 h1 计算 opacity 为 1(内联仍是 0,靠兜底规则)', async ({ browser }) => { + const ctx = await browser.newContext({ javaScriptEnabled: false, viewport: { width: 1280, height: 900 } }); + const page = await ctx.newPage(); + await page.goto('/about', { waitUntil: 'domcontentloaded', timeout: 60000 }); + const snap = await page.evaluate(() => { + const h1 = document.querySelector('h1') as HTMLElement | null; + return { + inline: h1?.getAttribute('style') ?? null, + computed: h1 ? Number(getComputedStyle(h1).opacity) : -1, + }; + }); + expect(snap.inline, '前提:SSR 内联样式仍带 opacity:0(否则本用例失去意义)').toContain('opacity:0'); + expect(snap.computed, '无 JS 时首屏必须可见(CSS 兜底生效)').toBe(1); + await ctx.close(); + }); + + test('水合后 800ms 置位 data-content-ready 且 h1 仍可见', async ({ page }) => { + await page.goto('/about', { waitUntil: 'domcontentloaded', timeout: 60000 }); + const h1 = page.locator('h1').first(); + await expect(h1).toBeVisible({ timeout: 10000 }); + const early = await h1.evaluate((el) => Number(getComputedStyle(el).opacity)); + expect(early, '首帧(水合前后)h1 必须是可见的').toBe(1); + + await expect + .poll(() => page.evaluate(() => document.documentElement.getAttribute('data-content-ready')), { + timeout: 5000, + message: '水合后应置位 data-content-ready(把控制权交还 framer)', + }) + .toBe('1'); + + await page.waitForTimeout(400); + const after = await h1.evaluate((el) => Number(getComputedStyle(el).opacity)); + expect(after, '交接后不得闪回 opacity:0').toBe(1); + }); +}); diff --git a/src/app/(marketing)/template.tsx b/src/app/(marketing)/template.tsx index 819802a..b164078 100644 --- a/src/app/(marketing)/template.tsx +++ b/src/app/(marketing)/template.tsx @@ -1,5 +1,6 @@ 'use client'; +import { useEffect } from 'react'; import { motion, type Variants } from 'framer-motion'; import { useReducedMotion } from '@/hooks/use-reduced-motion'; @@ -36,6 +37,15 @@ export default function MarketingTemplate({ }) { const shouldReduceMotion = useReducedMotion(); + // 2026-10-20:水合后把首屏可见性的兜底交还给 framer(见 globals.css 的 data-content-ready 规则)。 + // 800ms > 最长入场 280ms,保证交接时入场动画已结束、不会闪一下。 + useEffect(() => { + const id = window.setTimeout(() => { + document.documentElement.setAttribute('data-content-ready', '1'); + }, 800); + return () => window.clearTimeout(id); + }, []); + // 2026-10-20:**不再早返回 `<>{children}`** —— 那会让树结构与 SSR 不同 // (服务端永远渲染 motion.div,客户端 reduce 用户渲染裸 Fragment)⇒ React #418。 // 改为结构恒定,只在挂载后把 variants 换成空组(时长 0、无位移)。 diff --git a/src/app/globals.css b/src/app/globals.css index 5389e54..c0241ac 100644 --- a/src/app/globals.css +++ b/src/app/globals.css @@ -1513,3 +1513,17 @@ p, li, span { font-style: normal; /* 子集只覆盖源码实际用字(1050 码位);CMS 新增中文由后面的系统衬线兜底 */ } + +/* ───────────────────────────────────────────────────────────────────────── + 首屏可见性兜底(2026-10-20,冷首访白屏) + 全站 167 处 framer-motion 入场把初始 opacity 内联成 0 + (实测 SSR: style="opacity:0;transform:translateY(30px)"), + 而它只能由 JS 水合后驱动 ⇒ 冷首访/弱网/脚本失败时整页白(实测限速下 3–5s)。 + 规则:`data-content-ready` 未置位前,强制这些入场元素可见;由营销页 template + 在水合后 800ms(> 最长入场 280ms + 余量)置位,把控制权交还 framer。 + 失败也是敞开的:若 JS 始终不执行,则永不置位 ⇒ 内容保持可见。 + ───────────────────────────────────────────────────────────────────────── */ +html:not([data-content-ready]) [style*="opacity:0"], +html:not([data-content-ready]) [style*="opacity: 0"] { + opacity: 1 !important; +}