Webpack搭建React项目配置Tailwind CSS遇@符号解析错误解决方案

问题场景 #

手动搭建React+Webpack项目（未使用create-react-app），集成Tailwind CSS时出现编译错误：

ERROR in ./index.css 1:0
Module parse failed: Unexpected character '@' (1:0)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> @tailwind base;
| @tailwind components;
| @tailwind utilities;
 @ ./index.js 4:0-21

webpack 5.75.0 compiled with 1 error in 43 ms

相关文件内容 #

index.css

@tailwind base;
@tailwind components;
@tailwind utilities;

index.js

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./src/App";
import "./index.css";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

原Webpack配置文件

const path = require("path");

module.exports = {
  mode: "development",
  entry: "./index.js",
  output: {
    path: path.resolve(__dirname, "public"),
    filename: "main.js",
  },
  target: "web",
  devServer: {
    port: "3000",
    static: ["./public"],
    open: true,
    hot: true,
    liveReload: true,
  },
  resolve: {
    extensions: [".js", ".jsx", ".json"],
  },
  module: {
    rules: [
      {
        test: /\.js|\.jsx$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader",
          options: {
            presets: ["@babel/preset-react", "@babel/preset-env"],
          },
        },
      },
      {
        test: /\.(css|sass)$/i,
        include: path.resolve(__dirname, "src"),
        use: ["style-loader", "css-loader", "sass-loader", "raw-loader"],
      },
    ],
  },
};

原package.json

{
  "name": "package.json",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack-dev-server .",
    "build": "webpack"
  },
  "author": "Ravi_Bro",
  "license": "ISC",
  "devDependencies": {
    "@babel/core": "^7.20.7",
    "@babel/eslint-parser": "^7.19.1",
    "@babel/plugin-transform-runtime": "^7.19.6",
    "@babel/preset-env": "^7.20.2",
    "@babel/preset-react": "^7.18.6",
    "@babel/runtime": "^7.20.7",
    "babel-loader": "^9.1.0",
    "css-loader": "^6.7.3",
    "eslint": "^8.30.0",
    "eslint-config-airbnb-base": "^15.0.0",
    "eslint-config-prettier": "^8.5.0",
    "json-server": "^0.17.1",
    "postcss": "^8.4.20",
    "postcss-import": "^15.1.0",
    "postcss-loader": "^7.0.2",
    "postcss-preset-env": "^7.8.3",
    "style-loader": "^3.3.1",
    "tailwindcss": "^3.2.4",
    "webpack": "^5.75.0",
    "webpack-cli": "^5.0.1",
    "webpack-dev-server": "^4.11.1"
  },
  "dependencies": {
    "@babel/cli": "^7.20.7",
    "@tanstack/react-query": "^4.20.4",
    "axios": "^1.2.2",
    "babel-preset-es2015": "^6.24.1",
    "node-sass": "^8.0.0",
    "path": "^0.12.7",
    "path-to-regexp": "^6.2.1",
    "raw-loader": "^4.0.2",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-query": "^3.39.2",
    "sass-loader": "^13.2.0"
  }
}

错误原因 #

1. Webpack的CSS规则仅匹配src目录下的文件，但你的index.css在项目根目录，导致未被处理
2. 缺少处理Tailwind自定义指令的postcss-loader，无法解析@tailwind语法
3. Loader顺序错误：Webpack loader执行顺序为从右到左，原配置中sass-loader和raw-loader的顺序会导致解析异常，且非必要场景下可以移除

正确配置步骤 #

1. 修改Webpack的CSS规则 #

更新module.rules中的CSS处理规则，加入postcss-loader并调整匹配范围：

module: {
  rules: [
    // 保留原有的babel-loader规则
    {
      test: /\.js|\.jsx$/,
      exclude: /node_modules/,
      use: {
        loader: "babel-loader",
        options: {
          presets: ["@babel/preset-react", "@babel/preset-env"],
        },
      },
    },
    // 处理CSS文件
    {
      test: /\.css$/i,
      // 移除include限制，让Webpack处理所有目录下的css文件，可按需调整路径
      use: [
        "style-loader", // 将CSS注入DOM
        "css-loader", // 解析@import和url()语法
        "postcss-loader" // 处理Tailwind等PostCSS插件
      ],
    },
    // 若需处理Sass，可单独配置以下规则（可选）
    // {
    //   test: /\.(sass|scss)$/i,
    //   use: ["style-loader", "css-loader", "postcss-loader", "sass-loader"],
    // },
  ],
},

2. 创建Tailwind配置文件 #

在项目根目录运行命令生成tailwind.config.js：

npx tailwindcss init

修改配置文件，指定需要扫描的React组件路径：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx}", // 扫描src下所有React文件
    "./index.html" // 若有单独HTML文件需加入
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

3. 创建PostCSS配置文件 #

在项目根目录创建postcss.config.js，配置Tailwind和PostCSS预设：

module.exports = {
  plugins: {
    tailwindcss: {},
    postcss-preset-env: {},
  },
}

4. 验证配置 #

启动项目测试：

npm start

在React组件中添加Tailwind类名验证，例如：

// src/App.jsx
function App() {
  return <h1 className="text-3xl font-bold text-red-500">Hello Tailwind!</h1>;
}

export default App;

页面正常渲染样式即表示配置成功。

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