Taro

Taro v4 可以走 Webpack，也可以走 Vite。新项目优先选 Webpack，问题少一些；Taro Vite 可以用，但更适合已有项目排障。

警告

如果 tailwindcss 工具类不生效，先检查微信开发者工具是否开启了 代码自动热重载。关闭它后再重新预览。

如果你同时使用 NutUI，或启用了 @tarojs/plugin-html，请先看这个注意事项。

下面的配置适用于 Taro 的 react / preact / vue2 / vue3。文档默认你的源码都放在 src 目录下，这也是 Taro 模板的默认结构。

Tailwind CSS 版本选择

框架注册方式和 Tailwind 版本没有强绑定，主要差异在 src/app.css：

Tailwind 版本	安装	CSS 入口	扫描配置
3.x	pnpm add -D tailwindcss@3 weapp-tailwindcss	@tailwind base; 等指令	tailwind.config.js 的 content
4.x	pnpm add -D tailwindcss weapp-tailwindcss	@import "tailwindcss" source(none);	CSS 入口里的 @source

小程序构建只注册 WeappTailwindcss。不要再在 PostCSS 中注册 tailwindcss 或 @tailwindcss/postcss，也不要为 Taro Vite 注册 @tailwindcss/vite。

Tailwind CSS 3.x 入口

src/app.css

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

如果你的 Taro 项目本来引入的是 src/app.scss 或 src/app.less，Tailwind CSS 3 也可以继续放在这个文件里。Taro 会先处理 Sass/Less，再进入后面的样式链路。

tailwind.config.js

module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx,vue}',
    '!./dist/**/*',
    '!./node_modules/**/*',
  ],
  corePlugins: {
    preflight: false,
  },
}

Tailwind CSS 4.x 入口

src/app.css

@import "tailwindcss" source(none);
@source "../src";

这里不用再单独写 pages、components。Taro 默认源码都在 src 里，扫 ../src 更简单，也能覆盖你后面新增的 src/features、src/utils、src/widgets 这类目录。

source(none) 会关掉 Tailwind 4 的默认自动扫描，只按我们写的 @source "../src" 扫源码。这样不会把 dist、node_modules 这类目录带进来。

Tailwind 4 的入口请放在纯 .css 文件里。业务样式可以继续使用 Sass/Less，但不要把 @import "tailwindcss" 直接写进预处理入口。记得在 src/app.ts 或 src/app.js 里引入这个 CSS 文件：

src/app.ts

import './app.css'

使用 Webpack 作为打包工具

注册插件

在项目的配置文件 config/index 中注册。小程序和 H5 都需要注册 WeappTailwindcss：小程序目标会输出小程序可用 CSS，TARO_ENV=h5 时会自动切到 Web 目标。

config/index.[jt]s

const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
// 使用 ts 配置时，可以改用下方 import 写法
// import { WeappTailwindcss } from 'weapp-tailwindcss/webpack'

const weappTailwindcssOptions = {
  rem2rpx: true,
  tailwindcssBasedir: process.cwd(),
}

function registerWeappTailwindcss(chain) {
  chain.merge({
    plugin: {
      install: {
        plugin: WeappTailwindcss,
        args: [weappTailwindcssOptions],
      },
    },
  })
}

{
  mini: {
    webpackChain(chain, webpack) {
      registerWeappTailwindcss(chain)
    }
  },
  h5: {
    webpackChain(chain, webpack) {
      registerWeappTailwindcss(chain)
    }
  }
}

然后正常运行项目即可。常规 Taro 项目只要 src/app.ts 引入了 ./app.css，这里不用写 cssEntries。

如果你把 Tailwind 入口放到了别的目录，或者项目有多个 Tailwind 入口，再手动补 cssEntries：

config/index.[jt]s

const path = require('node:path')

const weappTailwindcssOptions = {
  rem2rpx: true,
  tailwindcssBasedir: process.cwd(),
  cssEntries: [
    path.resolve(__dirname, '../src/app.css'),
  ],
}

cssEntries 指向的是 Tailwind 入口文件。Tailwind 4 请指向纯 .css；Tailwind 3 如果你确实把 @tailwind 写在 app.scss 或 app.less 里，就指向这个实际入口。

不要在 H5 里写 disabled: process.env.TARO_ENV === 'h5'。小程序和 H5 都注册插件，weapp-tailwindcss 会按目标端处理。

信息

weapp-tailwindcss/webpack 对应的推荐插件名 WeappTailwindcss 适用于 webpack@5

在使用 Taro 时，检查一下 config/index 文件的配置项 compiler，来确认你的 webpack 版本。当前版本不再内置 Webpack4 入口，推荐使用 'webpack5'

如果你使用了 taro-plugin-compiler-optimization，建议移除。它会让打包结果变得混乱。详见 issues/123 issues/131

taro 的 prebundle 也容易干扰排查。如果项目启动异常且原因不明，可以先关闭这个配置。

使用 Vite 作为打包工具

危险

Taro Vite 目前整体稳定性较差，已知问题和样式链路 bug 较多，不推荐在新项目里使用。

如果你没有强依赖 Taro Vite，优先选择 Taro Webpack、uni-app、weapp-vite 等更稳定的方案。

Taro Vite 需要把 WeappTailwindcss 注册到 config/index 的 compiler.vitePlugins，这样小程序和 H5 都能走同一份插件配置。Tailwind CSS 由 WeappTailwindcss 生成，不需要再注册 Tailwind 官方 Vite 或 PostCSS 插件。

在 config/index.ts 中注册插件

config/index.[jt]s

import type { Plugin } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const baseConfig: UserConfigExport<'vite'> = {
  // ... 其他配置
  compiler: {
    type: 'vite',
    vitePlugins: [
      WeappTailwindcss({
        // rem转rpx
        rem2rpx: true,
        // Taro Vite 可能移除 Tailwind CSS 变量，需要重新注入变量作用域
        injectAdditionalCssVarScope: true,
      })
    ] as Plugin[] // 从 vite 引入 type, 为了智能提示
  },
  // ... 其他配置
}

Tailwind CSS 生成由 weapp-tailwindcss 接管，不需要再把 Tailwind 官方生成插件注册到 PostCSS 或 Vite 配置里。src/app.css 按上方版本选择写 Tailwind 3 或 4 的入口。

常规 Taro Vite 项目也可以自动识别被引入的 src/app.css。只有入口没有被引入、多入口、自动识别失败时，再按 Webpack 那段补 cssEntries。

TARO_ENV=h5 时，生成器默认目标会自动切换为 web，不再需要写 disabled: process.env.TARO_ENV === 'h5'。如果 RN 或 Harmony 构建不希望插件参与，可以只针对这些目标显式设置 disabled。

vite.config.ts 只有在运行小程序时才会加载，h5 不会。小程序 + h5 双端兼容请把插件注册放在 config/index 的 compiler.vitePlugins 中。 Taro Vite 当前仍然不稳定，这部分内容仅作为历史方案和排障参考，不建议作为新项目默认选型。

视频演示