升级Next.js 15后出现Tailwind CSS预加载警告求助

问题分析 #

这个警告源于Next.js 15的资源预加载机制更新：它自动为拆分出的Tailwind基础CSS chunk添加了preload标签，但该chunk仅包含Tailwind的CSS变量定义，没有页面实际引用的具体样式，浏览器检测到资源预加载后未在规定时间内被使用，因此抛出警告。

解决方案 #

1. 确认全局CSS的正确导入方式

确保你的Tailwind全局CSS（app/ui/global.css）仅在根layout文件（app/layout.tsx或app/layout.jsx）中导入一次，且符合Next.js App Router规范：

// app/layout.tsx
import './ui/global.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

注意：根layout无需添加'use client'指令，Next.js会自动处理全局CSS的服务端渲染与客户端注入。

2. 优化Tailwind配置，避免无效CSS chunk

检查tailwind.config.ts的content配置，确保覆盖所有使用Tailwind样式的文件，让Tailwind仅生成实际用到的样式，减少不必要的chunk拆分：

// tailwind.config.ts
import type { Config } from 'tailwindcss';

const config: Config = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    // 其他使用Tailwind的目录也需添加
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

export default config;

执行npm run build重新打包，查看是否还会生成未被使用的CSS chunk。

3. 修改Webpack配置合并CSS chunk

如果上述方法无效，可通过Webpack配置将所有CSS合并为单个chunk，避免小chunk被预加载却未使用：

// next.config.ts
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.optimization.splitChunks.cacheGroups.styles = {
        test: /\.css$/,
        chunks: 'all',
        enforce: true,
        name: 'global-styles',
      };
    }
    return config;
  },
};

export default nextConfig;

此配置会将所有CSS资源合并到global-styles chunk中，减少预加载的无效资源。

4. 临时禁用CSS预加载（不推荐长期使用）

若只是想快速消除警告，可在next.config.ts中禁用CSS预加载功能：

// next.config.ts
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    preloadCSS: false,
  },
};

export default nextConfig;

注意：此方法会影响页面加载性能，仅建议作为临时排查手段。

内容的提问来源于stack exchange，提问作者moth