跳到主要内容

快速集成

最简单：直接用已验证 demo​

仓库内 demo 与当前版本一起维护，并提供 HBuilderX Web、微信小程序、Android、iOS 和鸿蒙本地 E2E 用例：

查看已验证 demo

不要使用旧的 icebreaker-template/uni-app-x-hbuilderx 作为 Tailwind CSS 4 起点；它仍是 tailwindcss@3 + weapp-tailwindcss@4 配置。

手动集成​

下面给出 Tailwind CSS 4 配置，当前文档仅维护 Tailwind CSS 4 接入说明。

前置条件​

  • 已安装 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) 安装依赖​

npm i -D tailwindcss weapp-tailwindcss

3) 注册 weapp-tailwindcss​

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

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

const projectRoot = dirname(fileURLToPath(import.meta.url))

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

4) 配置 Tailwind CSS 入口​

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) 把入口 CSS 加入 HBuilderX 构建图​

cssEntries 只告诉 weapp-tailwindcss 从哪里生成 Tailwind CSS，不会替代 HBuilderX / Vite 引入样式。在 App.uvue 的全局样式中导入入口：

App.uvue
<style>
@import './main.css';
</style>

缺少这一步时，候选类可以被扫描到，但 Web、小程序和 App 页面都不会加载生成后的 CSS。这正是 issue #964 中“构建不报错但所有端样式都没有反应”的核心原因。

6) 运行与验证​

在 HBuilderX 中依次运行到 Web、微信小程序和计划支持的 App 平台。先用一个任意值类名验证生成和转译是否生效：

<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
pnpm e2e:hbuilderx:local:web
pnpm e2e:hbuilderx:local:mp
pnpm e2e:hbuilderx:local:app
pnpm e2e:hbuilderx:local:android
pnpm e2e:hbuilderx:local:ios
pnpm e2e:hbuilderx:local:harmony

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

7) 编辑器智能提示​

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
企业级的分布式搜索型数据库