Weapp-vite

提示

主线接入文档已合并到 原生小程序 / weapp-vite。本页保留给旧链接和 Tailwind CSS 4 专项排障。

externalClasses 提醒

weapp-vite 自定义组件如果声明了 externalClasses，请在插件配置的 customAttributes 中列出这些属性。否则像 my-class="bg-[#fafa00] text-[40px]" 这样的写法会被微信开发者工具拆成无效片段，导致样式失效。

详细说明与更多示例请查阅 👉 《组件外部样式类（externalClasses）的支持》。

安装

npm

npm install -D tailwindcss weapp-tailwindcss

Yarn

yarn add --dev tailwindcss weapp-tailwindcss

pnpm

pnpm add -D tailwindcss weapp-tailwindcss

Bun

bun add --dev tailwindcss weapp-tailwindcss

配置

更改 vite.config.ts 注册 weapp-tailwindcss

vite.config.ts

import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  plugins: [
    WeappTailwindcss({
      rem2rpx: true,
    }),
  ],
})

weapp-tailwindcss@5 默认启用生成模式，不需要再注册 @tailwindcss/vite 或 @tailwindcss/postcss。如果项目已有 postcss.config.js，可以继续保留业务自己的 PostCSS 插件，但请移除 Tailwind 官方生成插件。 常规 weapp-vite 项目会自动识别 app.css 这类 Tailwind CSS 入口。只有多入口、入口没有被 Vite 引入、自动识别失败等场景，才需要手动配置 cssEntries。

添加样式

在项目目录下，小程序全局的 app.css 中，添加以下内容：

app.css

@import "tailwindcss";
@source "./src/**/*.{wxml,js,ts,vue}";
@source "./app.{js,ts,json}";
@source not "./dist";

关于 @import 'tailwindcss'

生成模式下，推荐在 Tailwind CSS 4.x 入口里直接写 @import 'tailwindcss'。WeappTailwindcss 会根据 target: 'weapp' 生成小程序目标 CSS。

这也能继续复用官方文档和 IntelliSense 识别的写法 @import 'tailwindcss'，以获得更好的 IDE 智能提示 支持。

存量项目中已经存在的 @import 'weapp-tailwindcss/index.css' 仍然可以继续使用，适合暂时不调整 CSS 入口的 v4 项目。

不论使用哪种入口，都请确保 cssEntries 指向纯 .css 文件，并且不要额外注册 @tailwindcss/postcss 或 @tailwindcss/vite。

更改好配置之后，直接启动即可