Safari 自适应深色模式:SSR 首帧测试

用独立的 Node.js 页面区分服务端主题、系统偏好和 Safari 自适应渲染,给出首帧、表单、SVG、画布与渐变的分层验收办法。

一个页面打开时先亮一下,再变暗;另一个页面肉眼已经变暗,控制台读出来的背景却还是白色。前者可能是应用在首帧之后才应用主题,后者则可能是 Safari 在绘制阶段替网页调整了颜色。两种现象看起来相似,但调查方向完全相反。修第一个问题,需要把主题决定往服务端或首份样式移动;修第二个问题,不应该编写脚本试探用户有没有打开浏览器功能,而要把颜色声明、实际画面和交互放进不同的测试。

WebKit 在 2026 年 11 月 3 日介绍了 Safari 27.3 beta 的 Adaptive Dark Mode。按它的说明,在系统使用深色外观且用户开启该功能时,浏览器能为未声明深色支持的亮色站点调整绘制结果;已主动声明浅色和深色支持的页面不需要由它代劳。11 月 18 日的 Safari Technology Preview 257 发布说明又列出一项具体修复:当大量渐变受这种颜色过滤影响时,渲染和滚动曾变慢。两条消息针对不同的软件渠道。发布说明不等于稳定版已启用这项能力,也不是本站或任意页面的性能报告。WebKit 功能说明 · 技术预览版 257 发布说明

确定谁负责颜色,再决定看什么证据

服务端知道的是站点自己的选择,例如用户上次明确点了浅色、深色或跟随系统。它默认并不知道用户设备这一刻的外观,不应把没收到偏好解释成浅色。首次访问时,我们可以给浏览器两套真正存在的配色,由 CSS 媒体条件在首屏决定用哪一套。用户明确选了一套时,则让初始 HTML 和 CSS 对这项选择达成一致,不再由系统偏好覆盖。这样,首帧不依赖前端代码启动速度,也不依赖应用是否能读取 localStorage。

color-scheme 的职责也有限。它告诉浏览器页面可以用哪些原生外观,影响表单、滚动条及浏览器提供的默认绘制;它不会自动为应用选好自己的品牌色、状态色和图标。反过来,只切换自定义变量而不声明原生外观,按钮不错,输入框和日期选择器却仍可能像来自另一套主题。媒体查询回答的是系统偏好,不是站点状态,更不是 Safari 自适应功能状态。遇到浏览器自适应调色,由于转换发生在绘制阶段,WebKit 明确说 JavaScript 查询 CSS 颜色时仍会拿到原来的设计值。这不是应用代码可以补一个判断绕开的限制。

需要分开保存三份证据。响应体与缓存头用于判断服务器发了什么;DOM 属性、媒体查询和 CSS 计算值用于判断应用选择了什么;截图和实际键盘操作用于判断用户最后看见了什么。一次报告若只有截图,你无法判定变色发生在应用样式还是引擎里;若只有读数,你无法知道半透明图形叠到实际背景后是不是消失了。把这三个层次记到同一个测试用例,比争论一个十六进制值正确与否更快。

搭一个不需要打包的服务端实验

使用 Node.js 22 或更高版本,不安装依赖。将下列片段保存为 server.mjs。实验保持页面只有一份模板,使用表单提交和重定向刷新服务端主题。切换不依赖客户端接管,后面的脚本只采集读数和画一个固定的标尺,不接受主题设置。这样能有意排除 hydration 自身造成的第二套状态,先把服务端基线做对。

import { createServer } from "node:http";

function preference(cookie = "") {
  for (const pair of cookie.split(";")) {
    const [name, ...value] = pair.trim().split("=");
    if (name === "lab-theme") {
      const mode = value.join("=");
      return (mode === "light" || mode === "dark") ? mode : "system";
    }
  }
  return "system";
}
function scheme(mode) {
  return mode === "light" || mode === "dark" ? mode : "light dark";
}
function parseModes(modes) {
  return modes.length === 1 && ["light", "dark", "system"].includes(modes[0])
    ? modes[0] : null;
}

function page(mode, bare) {
  const announced = bare ? "" :
    '<meta name="color-scheme" content="' + scheme(mode) + '">';
  const options = ["system", "light", "dark"].map(value =>
    '<option value="' + value + '"' +
    (value === mode ? " selected" : "") + ">" + value + "</option>"
  ).join("");
  const canvas = '(function () {' +
    'const c = document.querySelector("canvas");' +
    'const g = c.getContext("2d");' +
    'if (!g) return;' +
    'g.fillStyle = "#fef3c7"; g.fillRect(0,0,120,36);' +
    'g.fillStyle = "#422006"; g.fillRect(10,10,60,14);' +
    'const r = document.documentElement;' +
    'console.table({theme:r.dataset.theme,' +
    'osDark:matchMedia("(prefers-color-scheme: dark)").matches,' +
    'surface:getComputedStyle(document.body).backgroundColor,' +
    'scheme:getComputedStyle(r).colorScheme,' +
    'canvasPixel:Array.from(g.getImageData(15,15,1,1).data).join(",")});' +
    '})();';

  return '<!doctype html><html lang="zh-Hans" data-theme="' +
    (bare ? "bare" : mode) + '"><head><meta charset="utf-8">' +
    announced +
    '<meta name="viewport" content="width=device-width,initial-scale=1">' +
    '<title>主题绘制实验</title><style>' +
    ':root{--bg:#ffffff;--fg:#172033;--panel:#eef3ff;color-scheme:light dark}' +
    ':root[data-theme=bare]{color-scheme:normal}' +
    ':root[data-theme=light]{color-scheme:light}' +
    ':root[data-theme=dark]{color-scheme:dark;--bg:#182033;--fg:#eef3ff;--panel:#253257}' +
    '@media(prefers-color-scheme:dark){:root[data-theme=system]' +
    '{--bg:#182033;--fg:#eef3ff;--panel:#253257}}' +
    'body{background:var(--bg);color:var(--fg);font:1rem system-ui;margin:1.5rem}' +
    'section{padding:1rem;background:linear-gradient(120deg,var(--panel),var(--bg))}' +
    'svg{vertical-align:middle}label{display:inline-block;margin:.5rem 0}' +
    'canvas{display:block;margin:.5rem 0;border:1px solid currentColor}' +
    '</style></head><body><h1>主题绘制实验</h1>' +
    '<form method="post" action="/theme"><label>站点外观 ' +
    '<select name="theme">' + options + '</select></label> ' +
    '<button type="submit">保存</button></form>' +
    '<p><a href="/">应用主题</a> · <a href="/bare">未声明对照</a></p>' +
    '<section><label>日期 <input type="date"></label>' +
    '<p><svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24">' +
    '<circle cx="12" cy="12" r="8" fill="currentColor"/></svg> 有状态的图标</p>' +
    '<canvas width="120" height="36" aria-label="固定色块"></canvas>' +
    '</section><script>' + canvas + '</script></body></html>';
}

createServer(async (req, res) => {
  res.setHeader("Cache-Control", "private, no-store");
  if (req.method === "POST" && req.url === "/theme") {
    const type = (req.headers["content-type"] || "").split(";")[0].trim();
    if (type !== "application/x-www-form-urlencoded") {
      res.writeHead(415).end("Unsupported Media Type");
      return;
    }
    let raw = "";
    try {
      for await (const chunk of req) {
        raw += chunk.toString("utf8");
        if (Buffer.byteLength(raw, "utf8") > 256) {
          res.writeHead(413, { Connection: "close" }).end("Content Too Large");
          return;
        }
      }
    } catch {
      res.destroy();
      return;
    }
    const mode = parseModes(new URLSearchParams(raw).getAll("theme"));
    if (!mode) {
      res.writeHead(400).end("Invalid theme");
      return;
    }
    const cookie = "lab-theme=" + (mode === "system" ? "" : mode) +
      "; Path=/; HttpOnly; SameSite=Lax; Max-Age=" + (mode === "system" ? 0 : 2592000);
    res.writeHead(303, { Location: "/", "Set-Cookie": cookie }).end();
    return;
  }
  if (req.method !== "GET" || !["/", "/bare"].includes(req.url)) {
    res.writeHead(404).end("Not Found");
    return;
  }
  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
  res.end(page(preference(req.headers.cookie), req.url === "/bare"));
}).listen(8080, "127.0.0.1");

启动后在待测浏览器打开 http://127.0.0.1:8080/。如果设备上存在 HTTP 代理,先确保环回地址没有被转发;不要为测试把这个没有认证层的示例直接监听到公网。示例使用 HttpOnly 是为了让偏好由服务端读取并且无需在前端访问 Cookie;本地走 HTTP,生产 HTTPS 部署应按环境设置 Secure。实验故意没有账户、重放保护、身份参数或外部跳转。如果迁移到登录后的账户设置接口,主题值虽然不敏感,仍应沿用项目对变更请求的来源检查、容量限制与安全防护。不要拿实验服务器替换生产的 POST 处理器。

可以先用命令检查服务端合同。第二条应看到明确的深色根属性和相应头部声明,第三条应返回 303,最后一条不应更改偏好。已有 Cookie 不从 HTML 字符串直接回显;只接受固定枚举,重复的表单字段也被视为无效。选择 system 会删除覆盖值,不会把当前设备恰巧使用的 dark 永久写进 Cookie。这样更换设备外观之后,跟随系统仍然有意义。

node server.mjs
# 另开一个终端:
curl -s http://127.0.0.1:8080/
curl -s -b lab-theme=dark http://127.0.0.1:8080/
curl -si -d 'theme=dark' http://127.0.0.1:8080/theme
curl -si -d 'theme=dark&theme=light' http://127.0.0.1:8080/theme

验证边界:在独立 JavaScript 运行时实际执行了 13 条断言,覆盖 Cookie 缺失、有效、错误与额外等号,主题枚举对应的声明,以及表单值为空、单选、重复和非法字符的情况。HTTP 请求、Safari 实际绘制、预览版滚动和下述截图步骤没有在此次验证中运行;这里给出复验方式与预期观察,不将其写成实测。

用一组同时记录首帧与稳态的用例

先做应用属于自己的三种选择。系统深色、没有 Cookie 时,响应体应仍然写 system,而不是由服务器猜测 dark。浏览器稳态中的应用背景应进入深色分支;更改系统外观后无需重新请求服务器即可改变该分支。系统浅色而 Cookie 选 dark 时,响应已经声明 dark,截图与原生输入控件不应由于媒体条件翻回浅色。系统深色而 Cookie 选 light 时,应用设计色仍应采用浅色分支;这不能推出某个 beta 版本下浏览器永不变换像素。

要隔离浏览器适配,先关闭自适应功能做基线,再以完全相同的条件打开它。只有确实需要强制某个局部保持浅色时,才另开用例验证 color-scheme: light only,并记下浏览器版本。WebKit 提到 only 的支持从 Safari 27.3 beta 2 到来,不宜由这个说明替以前版本背书。

首次绘制和稳定后的截图要分别看。先录制刷新过程,最好包含导航开始前后的连续帧,然后给页面一次冷访问和一次热访问。如果使用性能工具,需记下设备、视口、系统外观、缓存状态和是否开启电源节约;不要比较两个不同设备的一张屏幕截屏就声称修了闪白。浏览器导航时的窗口背景、页面自身第一帧,以及后来应用接管造成的闪烁也不是同一件事。示例把 CSS 放在头部,以更容易观察页面自己的首帧。生产页面使用外链时,应核对首屏样式是否在关键加载路径上,而不是靠向全站加一层黑色遮挡来掩盖。

接着用 /bare 做对照。它移除头部外观声明,根元素使用 normal,正文依然是亮色,这使它和已主动支持深色的 / 区分开。在支持该功能、且按 WebKit 描述启用的 Safari 中,比对开关前后的同一路径。记录正文背景在控制台里的值和截图上的颜色;如果截图变化而原始 CSS 读数不变,这符合引擎内的转换模型。如果两者都没变,先检查系统是不是深色、该浏览器构建有没有此功能、设置是否有效,以及页面是否确实被判定为亮色;不要用脚本推断设置。如果两者同时变了,先查服务端枚举、媒体查询、样式优先级和浏览器扩展。有了对照,失败不会被简单归类成「Safari 深色有问题」。

检查画面时,从正文往组件走。先在日期输入框用键盘走一圈,看选择器、默认焦点环和文字;这里抓的是原生控件与应用油漆不同步的问题。再看内联 SVG 圆点是否因继承 currentColor 而保住轮廓,对真实项目中的外链 SVG 和固定填充值应增加独立样本,因为浏览器对它们的处理路径可能不同。

最后看画布中的黄底棕条。控制台的画布采样只能证明绘制缓冲区给出了设计值;画布边缘与周围网页之间的对比,必须拿截图或实际设备确认。WebKit 对自适应模式的说明也明确区分了普通网页颜色与画布内容,所以不能指望浏览器代替图表库更新轴标签、网格和提示层。画布周围的 DOM 容器仍可能变色,叠加的 tooltip 或图例需要一起看。

需要复查预览版 257 所提的渐变滚动问题时,不要用这个只有一张渐变卡片的页面下结论。复制同样大小的卡片组成长列表,保留只有纯色背景的同长度对照;在同一设备、同一浏览器构建中改变自适应开关,录制相同的滚动路径,再对比帧时间、卡顿位置和实际呈现。如果前后两版都没有有效开启此功能,两条曲线并不能评价这项修复。即使确认某一组渐变很慢,也先试减少重复绘制面积或给真正支持深色的页面交付独立主题,不必为了一条预览版发布说明删光设计系统的渐变。

与框架接管和缓存一起交付

把示例移进真实 SSR 框架时,保持服务端产生的根属性和客户端初始状态同源。客户端若上来重读 localStorage 并把它当作更高优先级,就会恢复两个主题所有者,甚至出现 hydration 失配。站点已有本地偏好时可设计明确迁移:固定一段时间内从旧值在客户端发一次请求同步 Cookie,状态归并后删除旧入口;无法首帧无闪烁的存量迁移,应单独写进测试而不是假称自动无缝。客户端跨标签页即时更新也可以后来加,但其职责只是同步已明确提交的站点偏好,不该用媒体查询替代对服务端结果的核对。用户偏好跟着浏览器会话保留,不代表多标签页的界面会在一次表单提交后自动同步,实验故意没有承诺这点。

个性化 HTML 还会改变 CDN 策略。若公共缓存只按 URL 缓存,深色用户生成的 HTML 可能被发给下一个浅色用户;对站点来说这是主题错乱,对包含用户数据的页面则更危险。实验直接私有且不存储,适合做验证基线。

实际站点可以只缓存不区分用户的静态壳、让 CSS 解决 system 分支;也可以让边缘只按三态主题做受控分桶,但前提是 HTML 没有账户相关内容,缓存键构造要过滤非枚举 Cookie,且 POST 响应不能被当作可共享缓存。无理由给整页加 Vary: Cookie 往往会把各种营销或登录 Cookie 都纳入变化来源,命中率难以预估。对高流量匿名站优先评估静态壳,对登录应用优先保证响应边界,再谈首帧性能。

验收不以「所有截图像素一致」为目标。应用应保证自己宣称支持的配色在无 JavaScript 时也可读,键盘可达,原生控件与选定外观一致;浏览器可自行调整的页面则保证关键内容可用,画布和外部图片仍有足够边界。测试记录要能回答三件事:服务端当时发送哪个主题,浏览器按什么规则选择了作者颜色,最终有哪部分画面跟读数不同。做到这一步,遇到用户报告亮色闪一下,或出现表面看似矛盾的计算值,才能从证据定位到真正需要修的那一层。

相关文章

评论

登录后即可参与讨论

暂无评论。