入门篇：快速认识 Tailwind CSS 4 与 weapp-tailwindcss
Tailwind CSS 4 把配置入口移到 CSS：主题变量与自定义工具都可以用原生语法声明。weapp-tailwindcss 已经适配这套编译流程。本篇用 30 分钟搭好一套 tailwindcss@4 + weapp-tailwindcss 的基础开发环境，并说明几个必须看懂的配置点。
本篇能学到什么
- 搭建一套可运行的 Tailwind CSS 4 + 小程序项目骨架
- 分清核心配置（
@source、@reference、必要时的cssEntries等）各自负责的事情 - 理解 v5 生成模式为什么只需要注册
WeappTailwindcss构建器插件 - 掌握验证样式是否生效的最小闭环，避免“写了没生效”的常见坑
如果你还未接触过 weapp-tailwindcss，建议先浏览 新手快速上手（Tailwind CSS 3.x） 了解插件能解决的问题，再回来完成 4.x 的配置。
环境准备
| 名称 | 说明 |
|---|---|
| Node.js `^20.19.0 | |
| pnpm ≥ 8 | Monorepo 与文档项目统一使用 pnpm |
| 小程序框架 | 任选 weapp-vite、uni-app、taro 等，推荐使用现成模板 |
| 代码编辑器 | VS Code 并安装 Tailwind CSS IntelliSense 插件 |
初始化项目后，执行一次 pnpm install 以及框架 CLI 的初始化命令（如 pnpm create @tarojs/cli）。随后即可进入 Tailwind CSS 配置步骤。
步骤一：安装依赖
在项目根目录执行：
- npm
- Yarn
- pnpm
- Bun
npm install -D tailwindcss@latest weapp-tailwindcss
yarn add --dev tailwindcss@latest weapp-tailwindcss
pnpm add -D tailwindcss@latest weapp-tailwindcss
bun add --dev tailwindcss@latest weapp-tailwindcss
weapp-tailwindcss@5默认启用生成模式，大部分 Vite / Webpack 小程序项目只需要注册WeappTailwindcss。不要再额外注册@tailwindcss/vite、@tailwindcss/postcss或 Tailwind CSS v3 的tailwindcssPostCSS 插件。
步骤二：注册 weapp-tailwindcss 插件
以 weapp-vite 为例（不同框架请对照对应的 集成指南）：
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
export default defineConfig({
plugins: [
WeappTailwindcss({
// 常用内置能力：开启 px 自动转换
rem2rpx: true,
}),
],
})
常规 Vite 项目会自动识别被引入的 Tailwind CSS 入口。只有多入口、入口未被 Vite 引入、自动识别失败等场景，才需要手动配置 cssEntries。
步骤三：检查 PostCSS 配置
生成模式下不需要为了 Tailwind CSS 新增 postcss.config.js。如果项目已经有 PostCSS 配置，保留业务自己的插件即可；请不要在这里注册 @tailwindcss/postcss 或 tailwindcss，否则会和 WeappTailwindcss 形成两套 Tailwind 生成链路。
步骤四：创建入口 CSS
在 src/app.css 中写入：
@import "tailwindcss";
/* 声明模板扫描路径，确保原子类能被收集 */
@source "../src/**/*.{vue,tsx,jsx,svelte,wxml}";
/* 需要自定义设计令牌时可在此编写 */
@theme {
--color-brand: oklch(67% 0.2 264);
--spacing-safe: clamp(12px, 1.2vw + 8px, 24px);
}
生成模式下，推荐在 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。
@source 是 Tailwind 4 的新写法，用于替代旧版本的 content 配置。路径请根据项目结构调整。若你需要在局部样式文件使用 @apply，在对应文件顶部添加 @reference "./app.css";。
步骤五：验证类名是否生效
创建一个最小页面（以 src/pages/index/index.vue 为例）：
<template>
<view class="flex min-h-screen flex-col items-center justify-center bg-slate-50 px-6 py-safe">
<view class="w-full max-w-md rounded-3xl bg-white p-6 shadow-lg shadow-slate-200">
<text class="text-xs font-semibold uppercase tracking-[0.22em] text-slate-500">Tailwind CSS 4</text>
<text class="mt-3 text-2xl font-bold text-slate-900">欢迎来到 weapp-tailwindcss</text>
<text class="mt-2 text-sm leading-6 text-slate-600">
现在可以尝试修改 <text class="font-medium text-brand">bg-brand</text> 或自定义 <text class="font-medium">utility</text>。
</text>
<button class="mt-6 inline-flex items-center justify-center rounded-xl bg-brand px-4 py-2 text-sm font-semibold text-white shadow transition hover:bg-brand/90 active:scale-95">
开始实践
</button>
</view>
</view>
</template>
py-safe是我们在上文@theme中声明的自定义变量（通过--spacing-safe导出），可验证主题自定义是否生效。
运行框架命令（如 pnpm dev:weapp 或 pnpm run build -- --watch），查看开发者工具中的页面是否渲染出预期样式。如果没有：
- 确认
@source是否包含当前文件扩展名 - 确认入口 CSS 是否被构建器引入；多入口或自动识别失败时，再检查
cssEntries是否指向正确路径 - 若在单文件组件内使用
@apply，确保添加了@reference
常见下一步
- 阅读 Tailwind CSS 4 官方文档 了解更多原生指令
- 针对不同框架的集成细节，请查阅「🧪Tailwind CSS @4.x」分类中的各篇文档
- 想理解
@layer在小程序下的降级方案，可继续阅读本教程的 进阶篇 与 高阶篇
完成本篇后，可以继续看真实组件里的写法，重点关注 @source、@reference 和小程序目标 CSS 的输出结果。
