Next.js 15（Pages Router）中Tailwind 4工具类失效求助

核心问题定位 #

Tailwind CSS 4.x的配置逻辑和3.x差异极大，尤其是PostCSS集成和CSS导入方式，你的问题大概率是配置文件不符合v4要求，导致PostCSS管道无法正确加载Tailwind的主题和工具类。

分步修复方案 #

1. 修正PostCSS配置文件 #

Tailwind CSS 4.x不再使用tailwindcss作为PostCSS插件，必须用@tailwindcss/postcss，配置结构如下：

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {}, // 保留以确保浏览器兼容性
  },
};

注意：不要混用tailwindcss和@tailwindcss/postcss插件，v4仅支持后者

2. 重置globals.css的导入语法 #

Tailwind CSS 4.x废弃了v3的@tailwind指令，改用标准CSS导入：

/* src/styles/globals.css */
@import "tailwindcss";
@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

@apply必须包裹在@layer层级内，不能直接写在全局根层级：

@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }
}

@layer utilities {
  .custom-btn {
    @apply bg-primary-600 hover:bg-primary-700 text-white;
  }
}

3. 修正tailwind.config.js的结构 #

Tailwind CSS 4.x要求显式导出配置对象，主题配置方式也有调整：

// tailwind.config.js
import { colors } from 'tailwindcss';

export default {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: colors.blue, // 基于默认blue色系自定义primary颜色
      },
    },
  },
  plugins: [],
};

v4中theme()函数仅能在@layer内部使用，无需额外导入主题文件

4. 验证Next.js的CSS加载配置 #

确保next.config.js中没有干扰CSS处理的配置：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // 不要添加experimental.css等可能破坏默认CSS处理逻辑的配置
};

export default nextConfig;

5. 彻底清理缓存并重新构建 #

执行以下命令清除所有缓存文件后重新安装依赖：

rm -rf .next node_modules package-lock.json
npm install
npm run dev

关键注意事项 #

• Tailwind CSS 4.x是重大版本更新，不要沿用v3的配置习惯
• 确保content路径覆盖所有使用Tailwind类的文件，包括Pages和Components目录
• JSX中直接使用的工具类，对应的文件必须被包含在content配置中，否则会被Tailwind从生产构建中剔除

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