跳到主要内容

uni-app x

运行环境要求

当前版本需要 Node.js ^22.18.0 || >=24.11.0 和 HBuilderX >=5.11。较旧的 HBuilderX 内置 Node 可能无法加载当前依赖。

uni-app x 使用 HBuilderX 和 @dcloudio/vite-plugin-uni。建议配合内置的 uniAppX 预设使用。

当前仓库的 HBuilderX 本地 E2E 覆盖了 uni-app x Web、微信小程序、Android、iOS 和鸿蒙。小程序与 App E2E 依赖本机 HBuilderX、开发者工具或模拟器，只在本地执行。

Tailwind CSSuni-app x

查看已验证 demo（推荐）

按步骤手动集成

这篇文档适合谁​

  • 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
  • 需要同时覆盖 Web、小程序、Android、iOS 和鸿蒙的原子化样式方案
  • 已经使用 HBuilderX 运行或发布 uni-app x 项目

当前支持范围​

当前文档面向 Tailwind CSS 4。uni-app x 项目建议通过 WeappTailwindcss(uniAppX(...)) 注册插件，Tailwind 的生成和小程序/App 转译都交给 weapp-tailwindcss。

Tailwind 版本入口方式扫描方式当前验证
Tailwind CSS 4@import "tailwindcss" source(none);CSS 入口里的 @sourceHBuilderX Web、微信小程序、Android、iOS、鸿蒙
本地 E2E

HBuilderX 依赖本机安装环境，所以 Web/小程序/App E2E 都在本地运行。仓库里对应的命令是 pnpm e2e:hbuilderx:local:web、pnpm e2e:hbuilderx:local:mp、pnpm e2e:hbuilderx:local:android、pnpm e2e:hbuilderx:local:ios 和 pnpm e2e:hbuilderx:local:harmony。

最快开始​

想最快跑起来：点击上方「查看已验证 demo」，按 README 步骤打开 HBuilderX 运行即可。不要使用旧的 icebreaker-template/uni-app-x-hbuilderx 作为新项目起点，请按本页的 Tailwind CSS 4 CSS-first 配置创建入口。

手动集成​

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

前置条件​

  • 已安装 HBuilderX >=5.11，并安装 uni-app x 的 Android / iOS 编译插件
  • Node.js 满足当前包要求：^22.18.0 || >=24.11.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,
      }),
    ),
  ],
})

Tailwind CSS 生成由 weapp-tailwindcss 接管，不要再注册 tailwindcss、@tailwindcss/postcss 或 @tailwindcss/vite。

Web 与 App 调试注意

cssEntries 用来告诉 weapp-tailwindcss Tailwind CSS 4 的入口文件，入口仍应是 HBuilderX / Vite 能处理到的真实 CSS 文件。Web/H5、Android 和 iOS 都需要保持 appType: 'uni-app-x'，不要因为运行到 Web 端手动关闭 uniAppX，否则 .uvue 模板里的任意值类名不会转换成安全选择器。

rem2rpx、unitsToPx、unitConversion 是 uniAppX() 预设的顶层选项，不要放进 cssOptions。

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/**/*";

不要把 unpackage 放进扫描范围，否则 HBuilderX 产物会反过来干扰开发构建。

5) 把入口 CSS 加入 HBuilderX 构建图​

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

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

缺少这一步时，候选类可以被扫描到，但 Web、小程序和 App 页面都不会加载生成后的 CSS。

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>
运行

本仓库的本地验证命令：

pnpm e2e:hbuilderx:local:web
pnpm e2e:hbuilderx:local:mp
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 扩展加语言映射，并安装 DCloud 的语言服务插件 dcloud-ide.hbuilderx-language-services：

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

开发建议​

  • 推荐用 VS Code 写代码，用 HBuilderX 负责运行与构建
  • 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App，先用 Android 模拟器打通路径
  • 原生 App 端文字必须放在 <text> 标签，文本样式也要直接作用在该元素上
  • 如果某些样式在 App 端受限，先保证 Android 端体验，再按需做条件编译适配小程序/Web

布局能力边界​

  • uvue 原生 App 端不支持 gap、gap-x-*、gap-y-*，包括 grid gap 与 flex gap
  • space-x-*、space-y-* 在 uni-app x 中也不要作为布局方案
  • 跨端间距建议直接对子项写 mt-* / ml-*，或者封装固定结构的间距组件
  • HBuilderX 控制台出现 CSS 兼容警告时，优先按目标平台限制调整样式

常见问题​

VS Code 对 uvue/uts 的高亮与跳转​

安装官方语言服务插件：

运行方式​

uni-app x 的运行和构建仍以 HBuilderX 为准。需要命令行自动化时，可以使用 HBuilderX CLI；本仓库的本地 E2E 通过 hbuilderx launch 运行 Web、小程序和 App 目标。

接下来​

SPONSORED
Easysearch
企业级的分布式搜索型数据库