NNext.js 中文网 GitHub

inlineCss

experimental

启用内联 CSS 支持。

用法#

在 <head> 中内联 CSS 的实验性支持。启用此标志后,通常生成 <link> 标签的所有位置都会改为生成 <style> 标签。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    inlineCss: true,
  },
}

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    inlineCss: true,
  },
}

module.exports = nextConfig

权衡#

  • 启用:如果你使用原子 CSS(如 Tailwind),并希望为新访客优化首屏加载性能
  • 跳过:如果回访访客较多,且你希望他们能受益于缓存的样式表

内联 CSS 何时有帮助#

通常,浏览器必须先下载 HTML、解析它、发现 CSS <link> 标签,然后请求样式表,才能进行渲染。内联消除了这种请求瀑布流,使样式随着 HTML 一起到达,从而浏览器可以立即渲染。

这种优势在以下情形中最为明显:

  • 首次访问的访客:由于 CSS 文件会阻塞渲染,内联消除了首次访问者经历的初始下载延迟。拥有缓存样式表的回访访客则不会看到此优势。
  • 性能指标:通过消除对 CSS 文件的额外网络请求,内联可以显著改善 First Contentful Paint (FCP) 和 Largest Contentful Paint (LCP)。
  • 慢速连接:对于高延迟网络上的用户,每次额外请求都会增加延迟。内联减少了往返次数,这在连接较慢时尤为重要。
  • 原子 CSS(Tailwind):工具类优先的框架只生成你使用的类,使 CSS 保持很小。页面的样式不会随页面复杂度成比例增长——无论你构建多少 UI,样式通常都很紧凑。这使得内联切实可行,因为你获得了性能优势,同时不会显著膨胀 HTML。

外部 CSS 何时更优#

内联样式无法与 HTML 分开缓存。每次页面加载都会重新下载相同的 CSS。

这种权衡在以下情形中最为重要:

  • 回访访客:反复访问你网站的用户会受益于缓存的外部样式表。使用内联后,他们每次访问都要重新下载样式。
  • 大型 CSS bundle:外部样式表可以独立缓存,并在现代基础设施上高效加载。内联 CSS 会随着每个 HTML 响应一起到达,增加 Time to First Byte (TTFB),并阻止浏览器单独缓存样式。这种权衡适用于小型 CSS(如 Tailwind 这样的原子框架),但对于较大的 bundle(如 Bootstrap 或 Material UI 这样的组件库)会增加开销。
  • 多个页面共享样式:在一个页面上缓存的外部样式表可以加快导航到其他页面的速度。内联样式没有跨页面缓存的优势。

小知识:

此功能目前处于实验阶段,存在一些已知限制:

  • CSS 内联是全局应用的,无法按页面配置
  • 在初始页面加载期间样式会重复——一次在用于 SSR 的 <style> 标签中,一次在 RSC Payload 中
  • 导航到预渲染页面时,样式将使用 <link> 标签而不是内联 CSS,以避免重复
  • 此功能在开发模式下不可用,仅适用于生产构建
Next.js 中文网