Tailwind CSS配置完成后页面样式未生效问题求助

问题背景 #

个人简易Web项目完成Tailwind环境搭建后，HTML中编写的Tailwind类名样式未生效，项目相关信息如下：

• 启动方式：执行yarn dev通过webpack-dev-server启动本地开发服务，对应package.json脚本配置：

"scripts": {
    "build": "webpack --config ./bundler/webpack.prod.js",
    "dev": "webpack serve --config ./bundler/webpack.dev.js"
}

• index.html代码：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Nilton SF</title>        
        <link rel="stylesheet" href="../tailwind/output.css">
</head>
<body>
    <div>
        <h1 class="text-blue-600">
            Hello world!
        </h1>
    </div>
</body>
</html>

• tailwind.config.js配置：

/** @type {import('tailwindcss').Config} */
module.exports = {
  purge: ["./src/*.{html}"],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

• 项目目录结构参考：
  

排查方向与修复方案 #

按优先级从高到低排查以下问题：

• 配置项与扫描路径错误
  1. 如果你使用的是Tailwind CSS v3及以上版本，配置中的purge字段已经废弃，需要替换为content字段，否则类名扫描逻辑不会执行。
  2. 当前配置的扫描路径./src/*.{html}匹配范围过窄，仅能识别src根目录下直接存放的html文件，无法覆盖子目录文件、js/ts等其他可能写入Tailwind类名的文件。修改为递归匹配规则即可：

  // tailwind.config.js 修正后核心配置
  module.exports = {
    content: ["./src/**/*.{html,js}"], // 匹配src下所有层级的html、js文件
    darkMode: false,
    theme: { extend: {} },
    variants: { extend: {} },
    plugins: [],
  }
  

• Tailwind编译链路缺失
  你使用webpack作为构建工具，必须完成以下配置才能正常编译Tailwind语法：
  1. 确认项目存在CSS入口文件，且文件头部写入Tailwind三个核心指令，否则编译输出的css文件为空：

  /* 全局CSS入口文件，例如src/css/input.css */
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  

  2. 根目录新增postcss.config.js配置文件，注册Tailwind相关插件：

  // postcss.config.js
  module.exports = {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    }
  }
  

  3. 检查webpack配置的module.rules规则，确认已正确配置css-loader、postcss-loader处理css文件，否则Tailwind指令不会被解析。
• 静态资源路径错误
  打开浏览器开发者工具的Network面板，检查output.css的请求状态：
  • 如果状态码是404，说明html中写的../tailwind/output.css相对路径和webpack开发服务的静态资源映射路径不匹配，调整引用路径或者webpack的静态资源输出路径即可。
  • 如果状态码是200，点开响应内容查看是否存在text-blue-600对应的样式规则，没有的话回到前两步检查编译配置和扫描路径。
• 开发服务缓存问题
  所有配置修改完成后，手动停止当前webpack-dev-server进程，重新执行yarn dev启动服务，Tailwind配置改动不会触发热更新，重启后才会生效。

内容的提问来源于stack exchange，提问作者Nilton Schumacher F