快速集成
最简单：直接用模板项目（推荐）
立即上手而不纠结配置细节，点击下面链接即可：
打开后按 README 步骤，用 HBuilderX 运行到 Android 模拟器或真机即可看到效果。
手动集成（由浅入深）
你也可以按下面步骤，从零开始完成配置。
前置条件
- 已安装最新 HBuilderX
- 安装 Node.js（建议 ≥ 18）
- 建议准备 Android 模拟器（或真机），便于快速验证
1) 创建项目
在 HBuilderX 中创建一个全新的 uni-app x 项目；随后在项目根目录初始化 package.json：
- npm
- Yarn
- pnpm
- Bun
npm init -y
yarn init -y
pnpm init -y
bun init -y
也可以手动创建
package.json文件。
2) 安装并引入 Tailwind CSS 3
- npm
- Yarn
- pnpm
- Bun
# 安装 tailwindcss@3 所需依赖
npm i -D tailwindcss@3 postcss autoprefixer
# 安装 tailwindcss@3 所需依赖
yarn add --dev tailwindcss@3 postcss autoprefixer
# 安装 tailwindcss@3 所需依赖
pnpm add -D tailwindcss@3 postcss autoprefixer
# 安装 tailwindcss@3 所需依赖
bun add --dev tailwindcss@3 postcss autoprefixer
- npm
- Yarn
- pnpm
- Bun
# 初始化 Tailwind 配置文件
npx tailwindcss init
# 初始化 Tailwind 配置文件
yarn dlx tailwindcss init
# 初始化 Tailwind 配置文件
pnpm dlx tailwindcss init
# 初始化 Tailwind 配置文件
bun x tailwindcss init
在应用入口 App.uvue 中全局引入：
App.uvue
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
3) 安装 weapp-tailwindcss 并添加补丁脚本
- npm
- Yarn
- pnpm
- Bun
npm i -D weapp-tailwindcss
yarn add --dev weapp-tailwindcss
pnpm add -D weapp-tailwindcss
bun add --dev weapp-tailwindcss
在 package.json 中增加 postinstall 脚本：
package.json
{
"scripts": {
"postinstall": "weapp-tw patch"
}
}
了解原因可阅读：weapp-tailwindcss 使用说明
4) 在 uni-app x 中注册 weapp-tailwindcss
先创建一个简单的路径工具函数，方便在配置里引用绝对路径：
shared.js
const path = require('node:path')
function r(...args) {
return path.resolve(__dirname, ...args)
}
module.exports = { r }
创建 vite.config.ts 并注册插件（注意 uniAppX 预设来自 weapp-tailwindcss/presets）：
vite.config.ts
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'
import { r } from './shared'
import { uniAppX } from 'weapp-tailwindcss/presets'
import tailwindcss from 'tailwindcss'
export default defineConfig({
plugins: [
uni(),
UnifiedViteWeappTailwindcssPlugin(
uniAppX({
base: __dirname,
rem2rpx: true,
}),
),
],
css: {
postcss: {
plugins: [
tailwindcss({
config: r('./tailwind.config.js'),
}),
],
},
},
})
5) 配置 Tailwind
使用绝对路径包含所有需要提取原子类的文件：
tailwind.config.js
const { r } = require('./shared')
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
r('./pages/**/*.{uts,uvue}'),
r('./components/**/*.{uts,uvue}'),
],
corePlugins: {
// 由 uni-app x 提供基础样式，这里关闭 preflight 避免冲突
preflight: false,
},
}
如需从更多目录提取样式，按需扩展 content 的 glob。
6) 运行与验证
- 在 HBuilderX 中点击「运行」并选择目标平台（推荐 Android 模拟器/真机）
- 新建/打开任意页面，写入示例类名验证：
<view class="p-4">
<text class="text-xl text-red-500 font-medium">Hello Tailwind on uni-app x</text>
</view>
7) 编辑器智能提示（可选）
VS Code 配合插件体验最佳。为 Tailwind 扩展增加语言映射，让其识别 uvue/uts：
.vscode/settings.json
{
"tailwindCSS.includeLanguages": {
"uvue": "html",
"uts": "javascript"
}
}
同时安装官方语言服务插件（ID: dcloud-ide.hbuilderx-language-services）以获得完整语法支持。
重要说明与限制
- 仅推荐在
[email protected]下跨端使用（v4 在该场景下暂不兼容） - 原生 App 端对文本与部分 CSS 特性有约束：文本使用
<text>元素，且样式需直接作用其上 - 如遇到 HBuilderX 控制台 CSS 警告，请按提示做兼容性调整或采用条件编译
