跳到主要内容

快速集成

最简单：直接用模板项目​

模板项目已经配好 HBuilderX、uni-app x 和 weapp-tailwindcss：

使用模板开始

导入 HBuilderX 后，运行到 Android 模拟器、iOS 模拟器或微信小程序即可检查效果。

手动集成​

下面给出 Tailwind CSS 3 和 Tailwind CSS 4 两套配置。两者都使用 uniAppX 预设，不需要执行 weapp-tw patch，也不要把官方 Tailwind PostCSS/Vite 插件注册到小程序构建链路里。

前置条件​

  • 已安装 HBuilderX，并安装 uni-app x 的 Android / iOS 编译插件
  • Node.js 满足仓库要求：^20.19.0 || >=22.12.0
  • 本地 App E2E 需要 Android 模拟器或 iOS 模拟器；iOS 还需要完整 Xcode

1) 创建项目​

在 HBuilderX 中创建新的 uni-app x 项目，然后在项目根目录初始化 package.json：

npm init -y

2) 安装依赖​

Tailwind CSS 3 项目：

npm i -D tailwindcss@3 weapp-tailwindcss

Tailwind CSS 4 项目：

npm i -D tailwindcss weapp-tailwindcss

3) 注册 weapp-tailwindcss​

Tailwind CSS 3 可以只配置 base。如果入口文件无法被构建链路稳定识别，也可以补上 cssEntries。

vite.config.ts
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { uniAppX } from 'weapp-tailwindcss/presets'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss(
      uniAppX({
        base: __dirname,
        rem2rpx: true,
      }),
    ),
  ],
})

Tailwind CSS 4 建议显式声明 CSS 入口，指向纯 .css 文件：

vite.config.ts
import path from 'node:path'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { uniAppX } from 'weapp-tailwindcss/presets'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss(
      uniAppX({
        base: __dirname,
        cssEntries: [
          path.resolve(__dirname, 'main.css'),
        ],
        rem2rpx: true,
      }),
    ),
  ],
})

4) 配置 Tailwind CSS 入口​

Tailwind CSS 3 使用 tailwind.config.js 扫描 uts / uvue 文件：

shared.js
const path = require('node:path')

function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = { r }
tailwind.config.js
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}'),
    `!${r('./uni_modules/**/*')}`,
  ],
  corePlugins: {
    preflight: false,
  },
}

入口样式：

App.uvue
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>

Tailwind CSS 4 使用 CSS-first 入口。入口文件建议放在项目根目录或源码目录下，并在 cssEntries 中使用绝对路径引用：

main.css
@import "tailwindcss" source(none);
@source "./App.uvue";
@source "./pages/**/*.{uts,uvue}";
@source "./components/**/*.{uts,uvue}";
@source "./stores/**/*.{uts,uvue}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";

5) 运行与验证​

在 HBuilderX 中选择目标平台运行。先用一个任意值类名验证生成和转译是否生效：

<view class="p-4">
  <text class="text-xl text-[#f7fbff] bg-[#102938] w-[173px]">Hello Tailwind on uni-app x</text>
</view>
运行

本仓库的本地验证命令：

npm run e2e:hbuilderx:local
npm run e2e:hbuilderx:local:app
npm run e2e:hbuilderx:local:android
npm run e2e:hbuilderx:local:ios

这些命令依赖本机 HBuilderX、模拟器和 Xcode，不放进 CI/CD。

6) 编辑器智能提示​

VS Code 默认不认识 uvue / uts。可以给 Tailwind 扩展加语言映射：

.vscode/settings.json
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}

同时安装 DCloud 的语言服务插件：dcloud-ide.hbuilderx-language-services。

重要限制​

  • 原生 App 端文本需要放在 <text> 元素里，文本样式也要直接作用在 <text> 上
  • uvue 原生 App 端不支持 gap、gap-x-*、gap-y-*
  • space-x-*、space-y-* 在 uni-app x 中也不要作为布局方案
  • 跨端间距建议直接对子项写 mt-* / ml-*，或者封装固定结构的间距组件
  • HBuilderX 控制台出现 CSS 兼容警告时，优先按目标平台限制调整样式
SPONSORED
Easysearch
企业级的分布式搜索型数据库